{"slug":"oip-token-boundary","title":"What is a Token Boundary?","body":"A token boundary defines the explicit scope of access and operation for an OIP (Object Invocation Protocol) work object during an invocation. It specifies the resources, capabilities, or data segments that an OIP object, identified by its unique key, is authorized to interact with. The token boundary is established at the point of invocation and is recorded as part of the invocation's immutable ledger entry, providing a verifiable proof of scope. Conformant behavior requires that all OIP object executions respect the defined token boundary, preventing unauthorized access or operations beyond its specified limits.\n\n## What is a Token Boundary?\n\nA token boundary is a protocol-defined constraint that delineates the operational perimeter for an OIP work object. It is a property of an /a/oip-what-is-token, specifying the maximum extent of its authority within the OIP ecosystem. This boundary is enforced during the execution of an OIP object, ensuring that the object's actions remain within its granted permissions. The token boundary is distinct from the /a/oip-object-model itself, which defines the object's inherent capabilities; instead, it defines the *allowed* application of those capabilities for a specific invocation.\n\n## Token Boundary Operation\n\nThe token boundary is established during an OIP invocation, which is a request to execute an OIP work object. An invocation occurs via the `/api/dispatch` route. The invoking entity provides a token, and the OIP system interprets the token's associated boundary to constrain the object's execution. The OIP system, acting as the executor, applies the token boundary as a filter or a guardrail for all subsequent operations performed by the invoked object. This mechanism ensures that an object, even if possessing broad inherent capabilities, operates only within the scope permitted by the specific token presented for that invocation.\n\n```bash\ncurl -X POST https://miscsubjects.com/api/dispatch \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"key\": \"example-object-key\",\n    \"body\": {\n      \"action\": \"read_data\",\n      \"dataset_id\": \"restricted_dataset_123\",\n      \"token\": {\n        \"id\": \"token_scope_dataset_123\",\n        \"boundary\": {\n          \"access\": [\"read\"],\n          \"datasets\": [\"restricted_dataset_123\"]\n        }\n      }\n    }\n  }'\n```\n\n## Token Boundary Receipt\n\nAn OIP receipt provides immutable proof of an invocation, including the token boundary that was applied during its execution. Upon successful invocation, the OIP system returns a receipt, accessible via `GET /api/dispatch?receipt=inv_ID`. This receipt includes a record of the token presented and the effective boundary enforced. The presence of the `token_boundary_enforced` field within the receipt confirms that the OIP system processed the invocation with the specified scope constraints.\n\n```json\n{\n  \"invocation_id\": \"inv_abcdef123456\",\n  \"object_key\": \"example-object-key\",\n  \"status\": \"completed\",\n  \"timestamp\": \"2023-10-27T10:00:00Z\",\n  \"input_body\": {\n    \"action\": \"read_data\",\n    \"dataset_id\": \"restricted_dataset_123\",\n    \"token\": {\n      \"id\": \"token_scope_dataset_123\",\n      \"boundary\": {\n        \"access\": [\"read\"],\n        \"datasets\": [\"restricted_dataset_123\"]\n      }\n    }\n  },\n  \"output\": {\n    \"data_read_status\": \"success\",\n    \"rows_count\": 100\n  },\n  \"token_boundary_enforced\": {\n    \"access\": [\"read\"],\n    \"datasets\": [\"restricted_dataset_123\"]\n  },\n  \"ledger_entry_id\": \"ledger_entry_xyz789\"\n}\n```\n\n## Token Boundary Conformance\n\nConformant OIP systems and objects adhere strictly to the token boundary specified in an invocation. An OIP object's execution must not attempt operations or access resources outside the `token_boundary_enforced` scope recorded in the receipt. If an object attempts an action beyond its boundary, the OIP system must terminate the invocation and record a failure status in the receipt, explicitly stating the boundary violation. This ensures the integrity and security of OIP operations, preventing privilege escalation or unauthorized data access.\n\n## End-to-End Example: Token-Scoped Invocation\n\nThis example demonstrates invoking an OIP object to process a specific report, constrained by a token boundary that limits access to `report_id_456` and permits only `process` actions. The invocation is performed using `curl` against the `/api/dispatch` endpoint.\n\n1.  **Invocation Request**: A `POST` request to `/api/dispatch` with an object key and a body containing the token with its boundary.\n\n    ```bash\n    curl -X POST https://miscsubjects.com/api/dispatch \\\n      -H \"Content-Type: application/json\" \\\n      -d '{\n        \"key\": \"report-processor-object\",\n        \"body\": {\n          \"action\": \"process\",\n          \"report_id\": \"report_id_456\",\n          \"token\": {\n            \"id\": \"report_processor_token\",\n            \"boundary\": {\n              \"allowed_reports\": [\"report_id_456\"],\n              \"allowed_actions\": [\"process\"]\n            }\n          }\n        }\n      }'\n    ```\n\n2.  **System Processing**: The OIP system receives the invocation, identifies the `report-processor-object`, and applies the `report_processor_token`'s boundary. The object proceeds to `process` `report_id_456` within these constraints.\n\n3.  **Receipt Retrieval**: The system returns an `invocation_id`. The receipt is retrieved using a `GET` request to `/api/dispatch?receipt=inv_ID`.\n\n    ```bash\n    curl -X GET \"https://miscsubjects.com/api/dispatch?receipt=inv_abcdef123456\"\n    ```\n\n4.  **Receipt Content**: The receipt confirms the successful processing and explicitly states the `token_boundary_enforced`.\n\n    ```json\n    {\n      \"invocation_id\": \"inv_abcdef123456\",\n      \"object_key\": \"report-processor-object\",\n      \"status\": \"completed\",\n      \"timestamp\": \"2023-10-27T10:05:00Z\",\n      \"input_body\": {\n        \"action\": \"process\",\n        \"report_id\": \"report_id_456\",\n        \"token\": {\n          \"id\": \"report_processor_token\",\n          \"boundary\": {\n            \"allowed_reports\": [\"report_id_456\"],\n            \"allowed_actions\": [\"process\"]\n          }\n        }\n      },\n      \"output\": {\n        \"processing_status\": \"success\",\n        \"processed_report_id\": \"report_id_456\"\n      },\n      \"token_boundary_enforced\": {\n        \"allowed_reports\": [\"report_id_456\"],\n        \"allowed_actions\": [\"process\"]\n      },\n      \"ledger_entry_id\": \"ledger_entry_uvw456\"\n    }\n    ```\n\n## Token Boundary and Model Context Protocol (MCP)\n\nOIP's token boundary defines the operational scope for an individual OIP object invocation, specifying explicit resource and action constraints. MCP (Model Context Protocol), in contrast, defines the session context for a model's interaction with a server, encompassing tools, resources, and prompts over a continuous session. The OIP token boundary is a discrete, invocation-specific enforcement mechanism, while the MCP session context establishes a broader, stateful environment for a series of model interactions. An OIP object invoked within an MCP session would still respect its specific token boundary, operating within the session's overall context but constrained by its own invocation-level permissions.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","dynamic"],"style":{"accent":"#16324f","measure":860},"claims":[{"id":"oip-c1","tier":"system","text":"The OIP article layer is generated from live directory rows, so it documents the objects that actually run the reference implementation.","who_claims":"system/oip_articles","source_ids":["oip-s3","oip-s4"]},{"id":"oip-c2","tier":"system","text":"The OIP operating path is caller to directory object to dispatch runner to invocation ledger to receipt.","who_claims":"system/oip_articles","source_ids":["oip-s1"]},{"id":"oip-c3","tier":"system","text":"Every executable capability in the reference implementation is reachable as an OIP object with a human article, a machine document, invocation history, and receipt path.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s3"]},{"id":"oip-c4","tier":"system","text":"Tap & Go is the copy primitive: one drop carries credential, protocol, tree, search, execute, and receipt instructions without a separate token-map-bundle assembly step.","who_claims":"system/oip_articles","source_ids":["oip-s2"]},{"id":"oip-c5","tier":"system","text":"OIP receipts are the proof object for actions: they record request, response, actor, links, replay, repair, and lineage.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s5"]}],"sources":[{"id":"oip-s1","type":"protocol","title":"BUILD_SPEC object invocation path","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","summary":"Defines directory rows, dispatch, ledger, and the escalation path for changing the build.","quote":"Run anything: POST https://miscsubjects.com/api/dispatch {key, body}","claim_ids":["oip-c2"],"link_status":"ok","hash":"oipbuildspec0001"},{"id":"oip-s2","type":"protocol","title":"Object Invocation Protocol spec","url":"https://miscsubjects.com/api/file/docs/OIP.md","summary":"Defines OIP surfaces, invariant loop, receipt/replay/repair, and invocation envelopes.","quote":"identify, explain, invoke, ledger, yield","claim_ids":["oip-c3","oip-c4","oip-c5"],"link_status":"ok","hash":"oipspec00000002"},{"id":"oip-s3","type":"protocol","title":"Live OIP capability tree","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","summary":"Public recursive capability tree.","quote":"root > shelf > system article > capability article > receipt","claim_ids":["oip-c1","oip-c3"],"link_status":"ok","hash":"oipmap0000000002"},{"id":"oip-s4","type":"protocol","title":"Directory row documentation","url":"https://miscsubjects.com/api/dispatch?key=OIP_TREE&format=markdown","summary":"Capability articles are generated from live rows.","quote":"Machine Contract","claim_ids":["oip-c1"],"link_status":"ok","hash":"oiprow0000000003"},{"id":"oip-s5","type":"protocol","title":"Invocation ledger","url":"https://miscsubjects.com/api/invocations","summary":"Append-only invocation records and receipt links.","quote":"invocations","claim_ids":["oip-c5"],"link_status":"ok","hash":"oipinvocations0005"}],"prov":{"model":"system/oip_articles","action":"generate"}}