@mseep/open-computer-use 1.0.0

package/contracts/exec/exec-channel.schema.json

@@ -0,0 +1,240 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.open-computer-use.dev/exec/exec-channel.schema.json",
+  "$comment": "SPDX-License-Identifier: FSL-1.1-Apache-2.0. Copyright (c) 2025 Open Computer Use Contributors. Exec/PTY WebSocket control-frame envelope (Control API -> Session sandbox). One WebSocket per session; host-dialled, non-host peers rejected at accept (NFR-IC-03, NFR-SEC-43). Text frames carry the tagged-JSON control messages below; raw stdio travels as separate binary frames announced by the StdIo* control tags (raw bytes are not JSON, so they are described structurally here, not validated). Per RFC 6455 WebSocket; control tags are an OCU-defined union.",
+
+  "title": "ExecChannelMessage",
+  "description": "A single tagged-JSON control frame on the exec WebSocket. The discriminator is the sole top-level property name (an externally-tagged union). Binary stdio frames are out of band of this schema and follow a StdIo* announce frame.",
+
+  "$defs": {
+    "ProcessId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "ContainerName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "Signal": {
+      "$comment": "A signal is either a number (1..64) or a POSIX name; type/length/pattern bounded to strict-validate input (NFR-SEC-51). The discriminator is the message key, not this value's type.",
+      "oneOf": [
+        { "type": "integer", "minimum": 1, "maximum": 64 },
+        { "type": "string", "pattern": "^SIG[A-Z0-9]{1,12}$" }
+      ]
+    },
+    "ExitCode": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 255
+    },
+    "BoundedReason": {
+      "$comment": "NFR-SEC-51: bounded error verbosity. Caller gets a stable reason code; message must not carry stack traces or internal topology. Length capped.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "reason_code": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]{1,63}$"
+        },
+        "message": {
+          "$comment": "x-ocu-default: maxLength 256 is an NFR-SEC-51 default pending sign-off, not a source-pinned value; retunable per workload tier.",
+          "type": "string",
+          "maxLength": 256
+        }
+      },
+      "required": ["reason_code"]
+    },
+
+    "CreateProcess": {
+      "$comment": "Spawn parameters. env-scrub and uid/gid drop are the no-creds-in-guest carriers; the schema records the fields, the sandbox enforces the scrub. The cmd/cwd/args-item maxLength 4096, args maxItems 1024, and env maxProperties 1024 are x-ocu-default bounds satisfying NFR-SEC-46 (a bound must exist) pending sign-off on the value; retunable per workload tier. The env-value maxLength 32768 matches the negotiated WebSocket buffer ceiling (NFR-SEC-46). Integer maxima are wire-type ceilings (uint8/16/32/64), not policy.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "cmd": { "type": "string", "minLength": 1, "maxLength": 4096 },
+        "args": {
+          "type": "array",
+          "items": { "type": "string", "maxLength": 4096 },
+          "maxItems": 1024
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string", "maxLength": 32768 },
+          "maxProperties": 1024
+        },
+        "cwd": { "type": "string", "maxLength": 4096 },
+        "rows": { "type": "integer", "minimum": 0, "maximum": 65535 },
+        "cols": { "type": "integer", "minimum": 0, "maximum": 65535 },
+        "timeout": { "$comment": "wall-clock seconds; expiry -> ProcessTimedOut", "type": "integer", "minimum": 0, "maximum": 4294967295 },
+        "cpu_timeout": { "$comment": "CPU-time budget seconds; exhaustion -> ProcessCpuTimedOut", "type": "integer", "minimum": 0, "maximum": 4294967295 },
+        "memory_limit_bytes": { "$comment": "per-process cap (u64 bytes); breach -> ProcessOutOfMemory. The u64 ceiling (2^64-1) is not expressed as a JSON-number maximum — it exceeds IEEE-754 safe-integer range and a validator would round it; the 64-bit domain is enforced by the wire type.", "type": "integer", "minimum": 0 },
+        "clear_env": { "type": "boolean", "default": false },
+        "uid": { "type": "integer", "minimum": 0, "maximum": 4294967295 },
+        "gid": { "type": "integer", "minimum": 0, "maximum": 4294967295 },
+        "allow_process_id_reuse": { "type": "boolean", "default": false },
+        "reattachable": { "type": "boolean", "default": false },
+        "bound_pid": {
+          "type": ["integer", "null"],
+          "minimum": 0,
+          "maximum": 4294967295
+        }
+      },
+      "required": ["cmd", "args"]
+    },
+
+    "ProcessConnection": {
+      "$comment": "Handshake envelope (client message 1 or 2). create_req present => spawn; absent => reattach. expected_container_name and the out-of-band JWT sub both carry NFR-SEC-43 container binding. want_trace_events and accept_compression are the client side of capability negotiation: the client advertises them in the handshake; the server answers with the ConnectionCapabilities first frame.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "process_id": { "$ref": "#/$defs/ProcessId" },
+        "create_req": { "$ref": "#/$defs/CreateProcess" },
+        "expected_container_name": { "$ref": "#/$defs/ContainerName" },
+        "want_trace_events": { "type": "boolean" },
+        "accept_compression": {
+          "type": "boolean",
+          "x-ocu-tbd": "Client advertises it accepts frame compression. The algorithm and the compressed-frame layout are not pinned by any source; carried as a negotiation flag, not a frozen algorithm choice (x-ocu-open-questions: compression-algorithm)."
+        }
+      },
+      "required": ["process_id"]
+    },
+
+    "ConnectionCapabilities": {
+      "$comment": "First server frame after the handshake. Per-feature negotiation, not a version integer: each flag toggles one capability so the protocol evolves without a global version bump. The V1/V2 split is expressed through the message tags (ProcessCreated vs ProcessCreatedV2, AttachedToProcess vs AttachedToProcessV2), not a version field in the handshake. supports_compression advertises that frames may be compressed; the algorithm and compressed-frame layout are not pinned by any source, so the flag is carried but the wire format is left to the sandbox.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "supports_traces": { "type": "boolean" },
+        "supports_compression": {
+          "type": "boolean",
+          "x-ocu-tbd": "Server advertises frame compression support. The algorithm and frame layout are unsourced; carried as a negotiation flag, not a frozen algorithm choice (x-ocu-open-questions: compression-algorithm)."
+        }
+      },
+      "required": ["supports_traces", "supports_compression"]
+    },
+
+    "ServerMessage": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": false,
+      "properties": {
+        "ConnectionCapabilities": { "$ref": "#/$defs/ConnectionCapabilities" },
+
+        "ProcessCreated": { "type": "null" },
+        "ProcessCreatedV2": {
+          "$comment": "V2 spawn-success variant. The tag exists; no source pins its payload body, so it is left as an open object (TBD: field set, see x-ocu-open-questions).",
+          "type": "object"
+        },
+        "AttachedToProcess": { "type": "null" },
+        "AttachedToProcessV2": {
+          "$comment": "V2 reattach-success variant. The tag exists; its payload body is unpinned by any source, same TBD as ProcessCreatedV2.",
+          "type": "object"
+        },
+        "ProcessNotRunning": { "type": "null" },
+        "ProcessAlreadyAttached": {
+          "$comment": "NFR-IC-05: single owner per pid (sequential-default concurrency).",
+          "type": "null"
+        },
+        "FailedToStart": {
+          "$comment": "Generic start failure. Distinct from FailedToStartProcessWithSameIdRunning per OCU-canon split.",
+          "$ref": "#/$defs/BoundedReason"
+        },
+        "FailedToStartProcessWithSameIdRunning": {
+          "$comment": "Pid-reuse violation (allow_process_id_reuse=false).",
+          "type": "null"
+        },
+        "InfraError": { "$ref": "#/$defs/BoundedReason" },
+
+        "ExpectStdOut": {
+          "$comment": "Announce frame: the next binary frame on the socket is stdout, bounded by max-ws-buffer-size 32768 (NFR-SEC-46).",
+          "type": "null"
+        },
+        "StdOutEOF": { "type": "null" },
+        "ExpectStdErr": {
+          "$comment": "Announce frame: next binary frame is stderr, bounded by NFR-SEC-46.",
+          "type": "null"
+        },
+        "StdErrEOF": { "type": "null" },
+
+        "SignalSent": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "signal": { "$ref": "#/$defs/Signal" } },
+          "required": ["signal"]
+        },
+        "FailedToSendSignal": { "$ref": "#/$defs/BoundedReason" },
+        "InvalidSignal": { "$ref": "#/$defs/BoundedReason" },
+
+        "TraceEvent": {
+          "$comment": "Server-side trace event; emitted only when supports_traces was negotiated. No source pins a field list, so the body is an open object (TBD: field set, see x-ocu-open-questions).",
+          "type": "object"
+        },
+
+        "ProcessExited": {
+          "$comment": "Normal exit, carrying the exit code only. Signal-terminated and signal-stopped are distinct internal termination reasons but have no distinct wire variant in any source; they surface through this same code field (a 128+signal convention is the sandbox's choice, not asserted here). No source exposes code/signal as separate serialized fields.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "code": { "$ref": "#/$defs/ExitCode" } },
+          "required": ["code"]
+        },
+        "ProcessTimedOut": { "type": "null" },
+        "ProcessCpuTimedOut": { "type": "null" },
+        "ProcessOutOfMemory": { "type": "null" },
+        "ContainerOutOfMemory": { "type": "null" },
+        "ShuttingDown": { "type": "null" }
+      }
+    },
+
+    "ClientMessage": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": false,
+      "properties": {
+        "SendSignal": { "$ref": "#/$defs/Signal" },
+        "ExpectStdIn": {
+          "$comment": "OCU-canon: announce-only. The next binary frame carries stdin bytes (bounded by max-ws-buffer-size 32768, NFR-SEC-46); a non-binary follow-up is an error.",
+          "type": "null"
+        },
+        "StdInEOF": {
+          "$comment": "OCU-canon: the client has no further stdin; the guest closes the child's stdin write side. Symmetric to the server-side StdOutEOF/StdErrEOF announces. An explicit tag is required because a zero-length binary frame is indistinguishable from an empty write.",
+          "type": "null"
+        },
+        "Resize": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "rows": { "type": "integer", "minimum": 0, "maximum": 65535 },
+            "cols": { "type": "integer", "minimum": 0, "maximum": 65535 }
+          },
+          "required": ["rows", "cols"]
+        },
+        "Detach": {
+          "$comment": "Leaves the process running; valid only when create_req.reattachable was true.",
+          "type": "null"
+        },
+        "KeepAlive": { "type": "null" },
+        "Closed": { "type": "null" },
+        "TraceEvent": {
+          "$comment": "Client-side trace event; valid only when supports_traces was negotiated. Body unspecified by any source, so left as an open object (TBD: field set, see x-ocu-open-questions).",
+          "type": "object"
+        }
+      }
+    }
+  },
+
+  "x-ocu-open-questions": [
+    "ProcessCreatedV2 / AttachedToProcessV2 payload body: the V2 success tags exist but no source pins their frame body. A server-tracked status set (memory_usage_bytes, memory_cgroup_path, process_group_pid, internal_state with states CgroupCreated/Ready) is the expected payload, but its carrier frame is unconfirmed. Pin the V2 payload (and whether it carries the status set) before hardening either tag's body beyond an open object.",
+    "TraceEvent field set: the tag is negotiated via supports_traces but no source pins its fields; define a trace contract before constraining the body.",
+    "compression-algorithm: accept_compression / supports_compression negotiate frame compression, but no source pins the algorithm or the compressed-frame layout; pick and pin the algorithm before constraining the wire format."
+  ],
+
+  "$comment-anyOf": "A frame is the phase-1 handshake (ProcessConnection, identified by its required process_id) or a post-handshake control frame. Frame direction — server-sent vs client-sent — is a transport property (which peer wrote it), not an envelope distinction, so the same tag may appear in both directions (e.g. TraceEvent flows both ways under a negotiated supports_traces). anyOf, not oneOf: a TraceEvent frame is a valid control frame in either direction, and the envelope does not assert mutual exclusivity the wire does not have.",
+  "anyOf": [
+    { "$ref": "#/$defs/ProcessConnection" },
+    { "$ref": "#/$defs/ServerMessage" },
+    { "$ref": "#/$defs/ClientMessage" }
+  ]
+}

package/contracts/mcp/2025-06-18/ocu-constraints.schema.json

@@ -0,0 +1,178 @@
+{
+  "$comment": "SPDX-License-Identifier: FSL-1.1-Apache-2.0 | Copyright (c) 2025 Open Computer Use Contributors | OCU constraint overlay (profile) on MCP revision 2025-06-18: conform-not-define. Pins the revision and layers OCU-side limits onto Tool/CallToolResult; does not restate the MCP base schema.",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.open-computer-use.dev/mcp/2025-06-18/ocu-constraints.schema.json",
+  "title": "OCU MCP constraint profile (2025-06-18)",
+  "description": "Conform-not-define overlay. The wire contract is the public MCP revision 2025-06-18 (https://modelcontextprotocol.io/specification/2025-06-18, schema https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-06-18/schema.json). OCU is a Conformist and does not redefine MCP types. This file pins the revision and the OCU-side constraints that the base schema leaves open: audience-validated authz (NFR-SEC-09), bounded error and tool-result verbosity (NFR-SEC-51), bounded payload size (NFR-SEC-46), sequential-default tool execution (NFR-IC-05), date-revision negotiation as the breaking signal (NFR-IC-04). Validators MUST apply the MCP base schema first, then this profile.",
+
+  "x-ocu-profile": {
+    "conformance": "conform-not-define",
+    "base-contract": {
+      "protocol": "MCP over JSON-RPC 2.0",
+      "revision": "2025-06-18",
+      "spec": "https://modelcontextprotocol.io/specification/2025-06-18",
+      "schema": "https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-06-18/schema.json",
+      "tool-input-schema-dialect-default": "https://json-schema.org/draft/2020-12/schema"
+    },
+    "authoritative-references": [
+      "https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle",
+      "https://modelcontextprotocol.io/specification/2025-06-18/basic/transports",
+      "https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization",
+      "https://modelcontextprotocol.io/specification/2025-06-18/server/tools",
+      "https://www.jsonrpc.org/specification",
+      "https://www.rfc-editor.org/rfc/rfc8707",
+      "https://www.rfc-editor.org/rfc/rfc9728"
+    ],
+    "server-capabilities-pinned": {
+      "tools": { "listChanged": false },
+      "x-note": "OCU exposes the tools capability only. prompts, resources, logging, completions, sampling, elicitation, roots are not emitted by the OCU server. listChanged is false: the OCU tool set is registered statically at server construction (a fixed tool set per session) and notifications/tools/list_changed is never sent. Confirmed: the tool set does not mutate within a session; per-session content variation rides InitializeResult.instructions, not a changed tool list."
+    },
+    "protocol-version-binding": {
+      "negotiated-field": "$.params.protocolVersion (initialize) / $.result.protocolVersion (InitializeResult)",
+      "value": "2025-06-18",
+      "http-header": "MCP-Protocol-Version",
+      "missing-header-policy": "reject",
+      "x-deviation": "MCP base SHOULD-fallback to 2025-03-26 on a missing MCP-Protocol-Version header only when the server has no other way to identify the version (the version is otherwise negotiated at initialize). OCU tightens this to reject (HTTP 400) to pin the revision. Intentional deviation. (NFR-IC-04)"
+    },
+    "concurrency": {
+      "mode": "sequential-default-per-session",
+      "carrier": "none (gateway behavior, not a wire field)",
+      "x-note": "MCP permits concurrent in-flight requests with distinct id. OCU serialises tool execution per session by default; parallelism is opt-in. Documented as a gateway constraint, not validated on the wire. (NFR-IC-05)"
+    }
+  },
+
+  "x-ocu-limits": {
+    "$comment": "Numeric caps the MCP base schema leaves unspecified. NFR-SEC-46 (bounded message/object size, chunk-above-ceiling) and NFR-SEC-51 (size-bounded, identifier-minimized errors/responses) MANDATE that these bounds exist, are enforced pre-buffer at the gateway, and are configurable per workload tier — but pin NO specific byte/length value for the MCP profile. The exec-channel transport bounds (per-frame WS buffer, per-stream stdio ceiling) live on the Exec surface, not here, and do not bind MCP CallToolResult/error/tool-description sizes. Each value is an operational default, NOT a frozen contract value: an enforced gateway default the operator may retune within the NFR-SEC-46/51 floor, pending numeric sign-off. This is a vendor-extension registry, not a validatable $def; the bounded* schemas below mirror these numbers as enforceable maxLength/maxItems keywords, and counts are code points, not bytes — the byte ceiling is the gateway's pre-buffer check.",
+    "maxErrorMessageBytes": { "value": 1024, "nfr": "NFR-SEC-51", "of": "JSON-RPC error.message; stable reason code only" },
+    "maxErrorDataBytes": { "value": 4096, "nfr": "NFR-SEC-51", "of": "JSON-RPC error.data; negotiation hint only, no stack/topology" },
+    "maxToolDescriptionBytes": { "value": 8192, "nfr": "NFR-SEC-51", "of": "Tool.description; bounded discovery surface" },
+    "maxInstructionsBytes": { "value": 8192, "nfr": "NFR-SEC-51", "of": "InitializeResult.instructions; bounded free text" },
+    "maxCallToolResultBytes": { "value": 1048576, "nfr": "NFR-SEC-46", "of": "total serialized CallToolResult; over-ceiling rejected pre-buffer, never partially staged" },
+    "maxContentBlocks": { "value": 256, "nfr": "NFR-SEC-46", "of": "CallToolResult.content block count" },
+    "maxToolArgumentsBytes": { "value": 262144, "nfr": "NFR-SEC-46/51", "of": "CallToolRequest.params.arguments; bounded, strict-validated input" }
+  },
+
+  "x-ocu-overlay-map": {
+    "$comment": "This file is a non-self-executing overlay: it has no root type, so a validator pointed at it alone accepts everything. The gateway applies each $def below to the named MCP base type per message. Conformance is this map, not prose.",
+    "boundedError": "JSON-RPC error object (Tier-1 protocol error)",
+    "boundedTool": "MCP Tool object (tools/list, tools/call definitions)",
+    "boundedCallToolResult": "MCP CallToolResult (Tier-2 tool error rides isError)",
+    "boundedInitializeResult": "MCP InitializeResult (capability + revision pin)",
+    "jsonRpcSingleMessage": "the HTTP request/response body envelope (batching removed)"
+  },
+
+  "$defs": {
+    "jsonRpcSingleMessage": {
+      "$comment": "Batching is removed in 2025-06-18: an HTTP body MUST be a single object, never an array.",
+      "type": "object",
+      "not": { "type": "array" }
+    },
+
+    "boundedError": {
+      "$comment": "JSON-RPC error object (Tier 1, protocol error). Never reaches the model. Carries a stable reason code only; no topology/stack. error.message and error.data length-bounded per NFR-SEC-51.",
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "type": "integer",
+          "$comment": "Standard JSON-RPC codes only. No MCP-specific numeric codes are defined in 2025-06-18; implementation range below -32000 is not invented here. -32602 covers unknown tool, invalid arguments, and unsupported protocol version.",
+          "enum": [-32700, -32600, -32601, -32602, -32603]
+        },
+        "message": {
+          "type": "string",
+          "maxLength": 1024,
+          "$comment": "NFR-SEC-51: bounded; no internal detail. maxLength mirrors x-ocu-limits.maxErrorMessageBytes (a retunable default, not a frozen value)."
+        },
+        "data": {
+          "$comment": "NFR-SEC-51: optional, bounded by x-ocu-limits.maxErrorDataBytes at the gateway; carries the protocol-version negotiation hint {supported:[],requested} for -32602 and no stack/topology otherwise."
+        }
+      }
+    },
+
+    "boundedTool": {
+      "$comment": "OCU overlay on the MCP Tool object. Constrains only OCU-bounded fields; name/inputSchema/outputSchema/annotations semantics remain the MCP base.",
+      "type": "object",
+      "required": ["name", "inputSchema"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "description": {
+          "type": "string",
+          "maxLength": 8192,
+          "$comment": "NFR-SEC-51: bounded. maxLength mirrors x-ocu-limits.maxToolDescriptionBytes (a retunable default, not a frozen value)."
+        },
+        "inputSchema": {
+          "type": "object",
+          "required": ["type"],
+          "properties": { "type": { "const": "object" } },
+          "$comment": "MCP requires type:object. Embedded dialect defaults to JSON Schema 2020-12; a declared $schema selects another dialect."
+        },
+        "annotations": {
+          "$comment": "ToolAnnotations are non-binding hints and UNTRUSTED unless from a trusted server. OCU as gateway sets/strips these and does not pass third-party hints through unvalidated. (Layer-7)"
+        }
+      }
+    },
+
+    "boundedCallToolResult": {
+      "$comment": "OCU overlay on the MCP CallToolResult. Tier-2 error model: isError:true is a tool-execution error returned to the model as sanitized, bounded content; protocol errors use boundedError instead. (NFR-SEC-51, NFR-SEC-46)",
+      "type": "object",
+      "required": ["content"],
+      "properties": {
+        "content": {
+          "type": "array",
+          "maxItems": 256,
+          "$comment": "NFR-SEC-46: block count and total serialized size bounded at the gateway (x-ocu-limits.maxCallToolResultBytes / maxContentBlocks). maxItems mirrors the block-count default; total-bytes is enforced at the gateway pre-buffer. Retunable defaults, not frozen values. The OCU tool surface emits only text and image content blocks (no audio, no embedded-resource blocks); per-block type is the MCP base ContentBlock union, OCU does not redefine it."
+        },
+        "structuredContent": {
+          "type": "object",
+          "$comment": "Present iff the tool declares outputSchema; MUST conform to it. The OCU tool surface returns text/image content blocks and does not currently declare per-tool outputSchema; this field is permitted (a future tool MAY declare one) but not required. TBD: per-tool outputSchema adoption — no source pins it."
+        },
+        "isError": { "type": "boolean", "default": false }
+      }
+    },
+
+    "boundedInitializeResult": {
+      "$comment": "OCU pins the negotiated revision and the tools-only capability set; bounds the free-text instructions field.",
+      "type": "object",
+      "required": ["protocolVersion", "capabilities", "serverInfo"],
+      "properties": {
+        "protocolVersion": { "const": "2025-06-18" },
+        "capabilities": {
+          "type": "object",
+          "required": ["tools"],
+          "additionalProperties": false,
+          "properties": {
+            "tools": {
+              "type": "object",
+              "properties": { "listChanged": { "const": false } }
+            }
+          },
+          "$comment": "OCU emits the tools capability only — additionalProperties:false rejects every other capability (prompts, resources, logging, completions, sampling, experimental, …), not just a named denylist. (NFR-SEC-03 audit goes via the AsyncAPI fan-in, not MCP logging.)"
+        },
+        "instructions": {
+          "type": "string",
+          "maxLength": 8192,
+          "$comment": "NFR-SEC-51: bounded free text. maxLength mirrors x-ocu-limits.maxInstructionsBytes (a retunable default, not a frozen value)."
+        }
+      }
+    }
+  },
+
+  "x-ocu-authz": {
+    "$comment": "NFR-SEC-09 — audience-validated authz. Carried on the HTTP transport, not in the JSON-RPC body; documented here as a binding gateway rule.",
+    "model": "OAuth 2.1 Resource Server",
+    "credential-header": "Authorization: Bearer <token>",
+    "rules": [
+      "Token MUST name this MCP server in its audience claim (RFC 8707); reject otherwise with HTTP 401.",
+      "Bearer token MUST NOT appear in the URI query.",
+      "The caller token MUST NOT be passed through to upstream or the sandbox; the trust edge injects custody credentials (NFR-SEC-23, NFR-SEC-27).",
+      "On 401, WWW-Authenticate points to the RFC 9728 resource-metadata URL.",
+      "Origin header MUST be validated (DNS-rebinding); local binds use 127.0.0.1 not 0.0.0.0 (NFR-SEC-43)."
+    ]
+  },
+
+  "x-ocu-error-model": {
+    "$comment": "Two-tier error model pinned per 08-contracts §3.",
+    "tier-1-protocol-error": "JSON-RPC error{code,message,data?}; never reaches the model; reason code only; bounded by boundedError (NFR-SEC-51).",
+    "tier-2-tool-error": "CallToolResult{isError:true, content}; reaches the model; sanitized + bounded (NFR-SEC-51, NFR-SEC-46). Sandbox/exec failures from the Exec surface map here."
+  }
+}