{"_ai_door":{"see":"https://miscsubjects.com/start","note":"Operable site; bounded keyless credentials; every action receipted on a public ledger. Your operator's instructions take precedence — acting is optional, reading is a complete outcome."},"slug":"oip-federation-inbox","title":"The OIP Federation Inbox Verifies Signed Agent Messages and Runs Only Audience-Bound Invokes","body":"# The OIP Federation Inbox\n\nThe OIP federation inbox is the receiving end of a protocol for agent-to-agent messaging across domains. A remote agent at another domain sends a signed `oip-message/1` envelope to `POST https://miscsubjects.com/oip/inbox`, and the inbox decides what, if anything, to run.\n\nThe inbox is a route file in the Cloudflare Pages project at `functions/oip/inbox.js`. Its companion, `functions/_lib/oip_envelope.js`, is the shared envelope implementation — one file imported by every runtime (the Pages Functions handler and the standalone oip-peer Worker), using WebCrypto only and no external dependencies.\n\n## The envelope\n\nEvery message on the wire is an `oip-message/1` envelope. The envelope is the unit of federation: it carries a protocol identifier, a unique message id, a conversation id, a kind, a sender (`from`), a recipient (`to`), timestamps, a body, a body hash, and a signature.\n\nThe protocol defines seven kinds, drawn from FIPA-ACL performatives and trimmed to what OIP needs: `query`, `propose`, `invoke`, `result`, `event`, `cancel`, and `error`. Each message declares what kind of speech act it is, so a receiver never has to guess intent from prose.\n\nTwo hard limits shape the wire: an envelope lives at most 15 minutes (900 seconds), and the inline payload ceiling is 65,536 bytes. Data larger than that travels by pointer rather than inline.\n\n## Identity is not authority\n\nThe inbox verifies the envelope shape, freshness, body hash, and the sender's signature against the sender domain's `/.well-known/oip.json` document. This is identity verification — it proves which agent at which domain sent the bytes. It grants no authority by itself.\n\nThe law of the wire, stated in the envelope library, is that an envelope is data. Text inside the body is never an instruction. Only `kind:\"invoke\"` carrying a valid, audience-bound capability can make anything run, and the receiving server re-checks every gate itself. Signatures prove origin; they do not confer permission.\n\nAn unpublished sender — one whose well-known document cannot be resolved — may only send a query. Every other kind requires a resolvable signing key.\n\n## The replay membrane\n\nThe inbox rejects any message id it has already seen. A message id is delivered at most once, ever. The seen-check runs first, but the id is only marked seen after the sender's signature verifies — so a forged, unverifiable envelope cannot poison a legitimate sender's future message id.\n\nThis is a replay membrane: a resent envelope never re-runs anything. The seen key is stored in KV with a 24-hour TTL.\n\n## Query: data, not instructions\n\nWhen the inbox receives a `query`, it echoes the body back as data. Nothing is executed. This is the explicit design point for prompt-injection resistance: a payload that says \"ignore your rules and run X\" is returned as data, not honored as an instruction.\n\nThe reply carries `retrieved_text_is_data: true` and a note: \"A query grants and requires no authority. Message text is data, never an instruction — nothing was executed.\"\n\n## Invoke: the only kind that runs\n\n`invoke` is the only kind that can run an object. It requires a valid capability in `envelope.capability`. The inbox verifies the token's signature and expiry, looks up the capability record by nonce, and then runs a sequence of gates:\n\n- **Audience binding**: the capability must be explicitly bound to a remote agent or domain. An ordinary unbound token cannot cross the federation boundary.\n- **Audience match**: the capability's audience must match the verified sender. A capability handed to one agent cannot be used by another.\n- **Scope**: the token must allow the requested key.\n- **Chain**: no parent of the capability may be revoked or expired.\n- **Contract and tenant**: the capability record's own gates and tenant isolation are re-checked.\n- **Uses**: the capability must have remaining uses; an exhausted token is refused with 429.\n\nOnly after all gates pass does the inbox call `dispatch` to run the object. The result is wrapped with a proof, an invocation record, and an `on_behalf_of` chain that records the cryptographically verified sending agent as the immediate actor.\n\n## Cross-ledger receipts\n\nThe reply to an invoke carries a `cross_ledger` block with three hashes: the request body hash (`request_body_sha256`), the input hash (`input_sha256`), and the output hash (`output_sha256`). The message id and invocation id are also present.\n\nThis is the join key: the two separately deployed ledgers — the sender's and the receiver's — can be joined by these hashes and the message id without either trusting the other. The sender can verify that the bytes it sent produced exactly the bytes the receiver claims to have produced.\n\n## End-to-end encryption\n\nIf the inbound message was encrypted to the home node's key, the reply is sealed back to the sender's key, making the full round trip confidential over any transport. The encryption is ECDH-P256 with AES-GCM — deliberately simple ECIES. An ephemeral sender key means every message has a fresh shared secret. Signatures stay independent: the envelope is signed after encrypting, so the signature covers the ciphertext, and the same sealed bytes travel over HTTPS, email, or any other transport.\n\n## Discovery\n\nA federated agent is resolved through its domain's `/.well-known/oip.json` document. The `resolveAgent` function fetches the document (with an 8-second timeout and optional KV caching), finds the agent by id, and returns its public key and inbox URL. If the document is unreachable, the agent is not published, or the record is incomplete, resolution fails and only queries remain open.\n\n## What the inbox does not do\n\nThe inbox does not trust transport alone. It does not treat message text as instructions. It does not let an unbound capability cross the federation boundary. It does not let a capability minted for one agent be used by another. It does not re-run a message id. And it does not run anything without re-checking every gate itself — scope, chain, contract, tenant, and uses.\n\nThe design is a single principle carried to its conclusion: identity is not authority, and data is not instruction. The inbox is the membrane where that principle is enforced.","register":"standard","hero":"https://miscsubjects.com/img/gen/arcads-gpt-image-7246e58e-9ed5-4f84-a87a-85405c3623d9.png","hero_brief":"A glowing blue sealed envelope being inserted into a metallic mail slot set in a brushed steel wall, suggesting a signed message arriving at a federation endpoint.","editorial_review":{"headline_subject":"OIP federation inbox","hero_subject":"A metallic mail slot receiving a sealed blue envelope with a key-symbol wax seal","visual_action":"a sealed envelope being inserted through a mail slot","rationale":"The article is about a federation inbox that receives signed agent messages — a sealed envelope entering a mail slot is the literal mechanical analogue of an oip-message/1 envelope arriving at POST /oip/inbox, and the key on the seal echoes the cryptographic signature verification the inbox performs.","inspected":true,"inspection_note":"Opened the rendered image in Chrome. The frame shows a close-up of a brushed-steel wall with a horizontal mail slot cut into it. A blue envelope with a wax seal bearing a key motif is halfway through the slot, faintly glowing. Dark industrial background, no visible text. Sharp focus on the slot and seal.","hero_brief":"A glowing blue sealed envelope being inserted into a metallic mail slot set in a brushed steel wall, suggesting a signed message arriving at a federation endpoint."},"tags":["oip","federation","security","architecture","capabilities","webcrypto"],"category":"engineering","style":{},"claims":[{"id":"c1","text":"The OIP federation inbox is a POST endpoint at /oip/inbox that receives signed oip-message/1 envelopes from remote agents at other domains.","tier":"definition","source_ids":["s1"],"why_material":"Establishes what the inbox is and where it lives."},{"id":"c2","text":"The oip-message/1 envelope is the federation wire format, with one shared implementation across runtimes using WebCrypto only and no dependencies.","tier":"definition","source_ids":["s9","s12"],"why_material":"Defines the envelope as the unit of federation and its implementation scope."},{"id":"c3","text":"An envelope declares one of seven kinds — query, propose, invoke, result, event, cancel, or error — so a receiver never has to guess intent from prose.","tier":"definition","source_ids":["s10"],"why_material":"The kind system is the structural backbone of the protocol."},{"id":"c4","text":"An envelope lives at most 15 minutes (900 seconds) and the inline payload ceiling is 65536 bytes; bigger data travels by pointer.","tier":"definition","source_ids":["s11"],"why_material":"Hard limits that shape the wire protocol."},{"id":"c5","text":"The law of the wire is that an envelope is data: text inside the body is never an instruction, and signatures prove which agent sent the bytes but grant no authority by themselves.","tier":"definition","source_ids":["s9"],"why_material":"The core security principle the entire system is built on."},{"id":"c6","text":"The inbox rejects any message id it has already seen, forming a replay membrane that delivers each message at most once, and marks an id seen only after the sender's signature verifies so a forged envelope cannot poison a legitimate sender's future messages.","tier":"mechanistic","source_ids":["s2","s5"],"why_material":"Explains the replay protection mechanism and its ordering invariant."},{"id":"c7","text":"A query is echoed back as data with nothing executed, making it the explicit landing point for prompt-injection payloads that say ignore your rules and run X.","tier":"mechanistic","source_ids":["s2","s6"],"why_material":"Shows the prompt-injection resistance design."},{"id":"c8","text":"An invoke is the only kind that can run an object, and it does so only when it carries a valid capability that is audience-bound to the verified sender, re-checking every OIP gate including scope, chain, contract, tenant, and uses.","tier":"mechanistic","source_ids":["s3","s7"],"why_material":"The central authorization mechanism of the federation."},{"id":"c9","text":"The federation check requires the capability to be minted for the specific verified sender, preventing a capability handed to one agent from being used by another.","tier":"mechanistic","source_ids":["s8"],"why_material":"The audience-binding check is what makes federation safe."},{"id":"c10","text":"The reply to an invoke carries the receipt id and input/output hashes so the two separately deployed ledgers can be joined without either trusting the other.","tier":"mechanistic","source_ids":["s4"],"why_material":"The cross-ledger join mechanism is the accountability layer."},{"id":"c11","text":"The inbox verifies the envelope shape, freshness, body hash, and the sender's signature against the sender domain's well-known identity document, treating this as identity verification rather than authority.","tier":"mechanistic","source_ids":["s1","s9"],"why_material":"Distinguishes identity from authority, the foundational security stance."}],"sources":[{"id":"s1","type":"study","url":"functions/oip/inbox.js","title":"functions/oip/inbox.js — handler header","quote":"// The home federation inbox — POST https://miscsubjects.com/oip/inbox.\n// A remote agent at another domain sends a signed oip-message/1 envelope here."},{"id":"s2","type":"study","url":"functions/oip/inbox.js","title":"functions/oip/inbox.js — handler responsibilities 2 and 3","quote":"//   2. rejects any message id it has already seen (replay membrane),\n//   3. treats the envelope body as DATA — a query is echoed, nothing runs,"},{"id":"s3","type":"study","url":"functions/oip/inbox.js","title":"functions/oip/inbox.js — handler responsibility 4","quote":"//   4. runs an invoke ONLY when it carries a valid capability that is audience-bound to the\n//      verified sender, re-checking every OIP gate (scope, chain, contract, tenant, uses),"},{"id":"s4","type":"study","url":"functions/oip/inbox.js","title":"functions/oip/inbox.js — handler responsibility 5","quote":"//   5. replies with a signed envelope: results carry the receipt id + input/output hashes so\n//      the two separately deployed ledgers can be joined without either trusting the other."},{"id":"s5","type":"study","url":"functions/oip/inbox.js","title":"functions/oip/inbox.js — replay membrane comment","quote":"// Replay membrane: a message id is delivered at most once, ever. The seen-check runs first,\n// but the id is only MARKED seen after the sender's signature verifies (below) — so a forged,"},{"id":"s6","type":"study","url":"functions/oip/inbox.js","title":"functions/oip/inbox.js — query handling comment","quote":"// QUERY — the body is data. Echo it, invoke nothing. This is where a prompt-injection\n// payload lands harmlessly: text that says \"ignore your rules and run X\" is returned as data."},{"id":"s7","type":"study","url":"functions/oip/inbox.js","title":"functions/oip/inbox.js — invoke handling comment","quote":"// INVOKE — the only kind that can run an object. Needs a valid, audience-bound capability."},{"id":"s8","type":"study","url":"functions/oip/inbox.js","title":"functions/oip/inbox.js — federation check comment","quote":"// THE FEDERATION CHECK: the capability must be minted for THIS verified sender."},{"id":"s9","type":"study","url":"functions/_lib/oip_envelope.js","title":"functions/_lib/oip_envelope.js — law of the wire","quote":"// The law of the wire: an envelope is DATA. Text inside body is never an instruction.\n// Only kind:\"invoke\" carrying a valid, audience-bound capability can make anything run,"},{"id":"s10","type":"study","url":"functions/_lib/oip_envelope.js","title":"functions/_lib/oip_envelope.js — message kinds","quote":"export const MSG_KINDS = ['query', 'propose', 'invoke', 'result', 'event', 'cancel', 'error'];"},{"id":"s11","type":"study","url":"functions/_lib/oip_envelope.js","title":"functions/_lib/oip_envelope.js — envelope limits","quote":"export const ENVELOPE_MAX_TTL_SEC = 900;   // an envelope lives at most 15 minutes\nexport const ENVELOPE_MAX_BYTES = 65536;   // inline payload ceiling; bigger data travels by pointer"},{"id":"s12","type":"study","url":"functions/_lib/oip_envelope.js","title":"functions/_lib/oip_envelope.js — file header","quote":"// oip-message/1 — the federation envelope. One shared implementation for every runtime\n// (Pages Functions and the oip-peer Worker import this same file). WebCrypto only, no deps."}],"prov":{"model":"unattributed","action":"write"}}