What is a Token Boundary?

What is a Token Boundary?

A 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.

Token Boundary Operation

The 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.

curl -X POST https://miscsubjects.com/api/dispatch \
  -H "Content-Type: application/json" \
  -d '{
    "key": "example-object-key",
    "body": {
      "action": "read_data",
      "dataset_id": "restricted_dataset_123",
      "token": {
        "id": "token_scope_dataset_123",
        "boundary": {
          "access": ["read"],
          "datasets": ["restricted_dataset_123"]
        }
      }
    }
  }'

Token Boundary Receipt

An 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.

{
  "invocation_id": "inv_abcdef123456",
  "object_key": "example-object-key",
  "status": "completed",
  "timestamp": "2023-10-27T10:00:00Z",
  "input_body": {
    "action": "read_data",
    "dataset_id": "restricted_dataset_123",
    "token": {
      "id": "token_scope_dataset_123",
      "boundary": {
        "access": ["read"],
        "datasets": ["restricted_dataset_123"]
      }
    }
  },
  "output": {
    "data_read_status": "success",
    "rows_count": 100
  },
  "token_boundary_enforced": {
    "access": ["read"],
    "datasets": ["restricted_dataset_123"]
  },
  "ledger_entry_id": "ledger_entry_xyz789"
}

Token Boundary Conformance

Conformant 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.

End-to-End Example: Token-Scoped Invocation

This 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.

1. Invocation Request: A POST request to /api/dispatch with an object key and a body containing the token with its boundary.

`bash curl -X POST https://miscsubjects.com/api/dispatch \ -H "Content-Type: application/json" \ -d '{ "key": "report-processor-object", "body": { "action": "process", "report_id": "report_id_456", "token": { "id": "report_processor_token", "boundary": { "allowed_reports": ["report_id_456"], "allowed_actions": ["process"] } } } }' `

1. 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.

1. Receipt Retrieval: The system returns an invocation_id. The receipt is retrieved using a GET request to /api/dispatch?receipt=inv_ID.

`bash curl -X GET "https://miscsubjects.com/api/dispatch?receipt=inv_abcdef123456" `

1. Receipt Content: The receipt confirms the successful processing and explicitly states the token_boundary_enforced.

`json { "invocation_id": "inv_abcdef123456", "object_key": "report-processor-object", "status": "completed", "timestamp": "2023-10-27T10:05:00Z", "input_body": { "action": "process", "report_id": "report_id_456", "token": { "id": "report_processor_token", "boundary": { "allowed_reports": ["report_id_456"], "allowed_actions": ["process"] } } }, "output": { "processing_status": "success", "processed_report_id": "report_id_456" }, "token_boundary_enforced": { "allowed_reports": ["report_id_456"], "allowed_actions": ["process"] }, "ledger_entry_id": "ledger_entry_uvw456" } `

Token Boundary and Model Context Protocol (MCP)

OIP'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.