# The OIP Federation Inbox Verifies Signed Agent Messages and Runs Only Audience-Bound Invokes slug: oip-federation-inbox · https://miscsubjects.com/a/oip-federation-inbox · category: engineering · tags: oip, federation, security, architecture, capabilities, webcrypto · updated 2026-08-06T03:11:19.851Z # The OIP Federation Inbox The 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. The 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. ## The envelope Every 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. The 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. Two 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. ## Identity is not authority The 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. The 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. An unpublished sender — one whose well-known document cannot be resolved — may only send a query. Every other kind requires a resolvable signing key. ## The replay membrane The 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. This is a replay membrane: a resent envelope never re-runs anything. The seen key is stored in KV with a 24-hour TTL. ## Query: data, not instructions When 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. The 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." ## Invoke: the only kind that runs `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: - **Audience binding**: the capability must be explicitly bound to a remote agent or domain. An ordinary unbound token cannot cross the federation boundary. - **Audience match**: the capability's audience must match the verified sender. A capability handed to one agent cannot be used by another. - **Scope**: the token must allow the requested key. - **Chain**: no parent of the capability may be revoked or expired. - **Contract and tenant**: the capability record's own gates and tenant isolation are re-checked. - **Uses**: the capability must have remaining uses; an exhausted token is refused with 429. Only 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. ## Cross-ledger receipts The 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. This 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. ## End-to-end encryption If 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. ## Discovery A 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. ## What the inbox does not do The 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. The 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. ## Sources 1. functions/oip/inbox.js — handler header — functions/oip/inbox.js 2. functions/oip/inbox.js — handler responsibilities 2 and 3 — functions/oip/inbox.js 3. functions/oip/inbox.js — handler responsibility 4 — functions/oip/inbox.js 4. functions/oip/inbox.js — handler responsibility 5 — functions/oip/inbox.js 5. functions/oip/inbox.js — replay membrane comment — functions/oip/inbox.js 6. functions/oip/inbox.js — query handling comment — functions/oip/inbox.js 7. functions/oip/inbox.js — invoke handling comment — functions/oip/inbox.js 8. functions/oip/inbox.js — federation check comment — functions/oip/inbox.js 9. functions/_lib/oip_envelope.js — law of the wire — functions/_lib/oip_envelope.js 10. functions/_lib/oip_envelope.js — message kinds — functions/_lib/oip_envelope.js 11. functions/_lib/oip_envelope.js — envelope limits — functions/_lib/oip_envelope.js 12. functions/_lib/oip_envelope.js — file header — functions/_lib/oip_envelope.js --- # Run your own OIP node (10 minutes) slug: oip-node-kit · https://miscsubjects.com/a/oip-node-kit · category: protocol · tags: oip, federation, node, onboarding, self-host · updated 2026-07-17T02:36:23.678Z # Run your own OIP node (10 minutes) This is everything a person at another organization needs to become a real, independent federation node: your own domain, your own keys, your own inbox. Once you do this, a capability minted on one domain can be handed to your agent on your domain, run a real action, and both sides keep matching proof — with no shared server and no shared operator. That is the difference between *technical* federation (two domains, one owner) and *institutional* federation (two owners who don't trust each other's servers). You need: a domain you control, and somewhere to run a tiny web service (Cloudflare Workers, Deno Deploy, a VPS — anything that serves HTTPS). ## 1. Generate your keys Your node signs with an ECDSA P-256 key. Generate one with the reference client (no install — it runs in Node ≥20 or any browser console): ```js import { generateKeypairJwk } from 'https://miscsubjects.com/oip/client.mjs'; const kp = await generateKeypairJwk(); console.log('PUBLIC (publish this):', JSON.stringify(kp.publicJwk)); console.log('PRIVATE (keep secret):', JSON.stringify(kp.privateJwk)); ``` Keep the private JWK in a secret (env var / secret store). Publish only the public JWK. ## 2. Publish your well-known Serve this at `https://YOURDOMAIN/.well-known/oip.json`. It is how any stranger resolves your identity with zero prior coordination. ```json { "protocol": "oip-message/1", "domain": "YOURDOMAIN", "agents": [{ "id": "youragent@YOURDOMAIN", "alg": "ES256", "public_key_jwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." }, "inbox": "https://YOURDOMAIN/oip/inbox" }], "spec": "https://miscsubjects.com/a/oip-message" } ``` ## 3. Stand up your inbox Your inbox is one POST endpoint. The rules it must enforce (all four, in order): reject anything past `expires_at` by *your* clock; reject a message id you have already seen; verify the sender's signature against *their* domain's well-known; treat the body as data — a `query` is answered, and nothing runs unless it is a signed `invoke` carrying a capability you accept. Here is a complete, dependency-free node (Cloudflare Worker form; the same logic runs on Deno or Node): ```js import { verifyEnvelope, buildEnvelope, signEnvelope, resolveAgent, agentDomain, } from 'https://miscsubjects.com/oip/client.mjs'; const MY_AGENT = 'youragent@YOURDOMAIN'; const seen = new Set(); // use KV/Redis in production export default { async fetch(request, env) { const url = new URL(request.url); if (url.pathname === '/.well-known/oip.json') { return Response.json({ protocol: 'oip-message/1', domain: 'YOURDOMAIN', agents: [{ id: MY_AGENT, alg: 'ES256', public_key_jwk: JSON.parse(env.PUBLIC_JWK), inbox: 'https://YOURDOMAIN/oip/inbox' }], spec: 'https://miscsubjects.com/a/oip-message', }); } if (url.pathname === '/oip/inbox' && request.method === 'POST') { const env0 = await request.json(); if (env0.to?.toLowerCase() !== MY_AGENT) return Response.json({ error: 'unknown_recipient' }, { status: 404 }); if (seen.has(env0.id)) return sign(env, env0, 'error', { reason: 'replay_rejected' }); const sender = await resolveAgent(env0.from); if (!sender.ok) { if (env0.kind !== 'query') return sign(env, env0, 'error', { reason: 'sender_unverifiable' }); } else { const v = await verifyEnvelope(env0, sender.jwk); if (!v.ok) return sign(env, env0, 'error', { reason: v.reason }); } seen.add(env0.id); // BODY IS DATA. A query is echoed; nothing runs from its text. if (env0.kind === 'query') return sign(env, env0, 'result', { echo: env0.body, invoked: false, retrieved_text_is_data: true }); // Implement your own objects here for `invoke`, gating on env0.capability. return sign(env, env0, 'error', { reason: 'no_local_objects' }); } return new Response('OIP node', { status: 200 }); }, }; async function sign(env, incoming, kind, body) { let e = await buildEnvelope({ from: MY_AGENT, to: incoming.from, kind, body, conversation: incoming.conversation, in_reply_to: incoming.id }); e = await signEnvelope(e, JSON.parse(env.PRIVATE_JWK), MY_AGENT); return Response.json(e); } ``` Set two secrets: `PUBLIC_JWK` and `PRIVATE_JWK` (the JWKs from step 1). Deploy. That's a node. ## 4. Run the same tests everyone runs **Prove you can reach the network** — ask the reference home agent a question and verify its signed reply: ```js import { OIPClient, generateKeypairJwk } from 'https://miscsubjects.com/oip/client.mjs'; const me = new OIPClient({ agent: 'youragent@YOURDOMAIN', keypair: { privateJwk: /* yours */ } }); const r = await me.query('pepper@miscsubjects.com', { text: 'what time is it' }); console.log(r.reply.body, 'verified:', r.reply_verified); // reply_verified must be true ``` **Prove others can reach you** — from any machine, send a query to your node and confirm it answers signed and that your signature verifies against your published key. The exact failure matrix the reference nodes pass (replay, stale, forwarded capability, out-of-scope, injection-as-data) is public at [`/api/dispatch?fedtest=1&format=markdown`](/api/dispatch?fedtest=1&format=markdown) — run the same checks against your node. **Get a real capability** — once your well-known is live, tell the operator your agent id and domain. They mint a capability *bound to your domain* and email it to you (an [email drop](/a/oip-message)). Your agent inspects the authority, then sends a signed `invoke` carrying it. It runs one bounded action back on their domain, and you both keep the receipt. That exchange — between two operators who control different servers — is institutional federation. It is the decisive proof, and it is the one thing the reference implementation cannot do alone: it needs you. ## The whole contract, in one paragraph Identity is a domain publishing a key. Authority is a capability scoped, expiring, revocable, and bound to one holder. A message is data; only a signed invoke with a valid capability acts. Every node keeps its own ledger; two ledgers joined by message id and body hash prove one exchange without a shared database. Encryption, when you want it, seals the body to the recipient's key at the envelope layer and rides any carrier unchanged. That is the entire protocol. Spec: [/a/oip-message](/a/oip-message). Client: [/oip/client.mjs](/oip/client.mjs). --- # oip-message/1 — the federation envelope slug: oip-message · https://miscsubjects.com/a/oip-message · category: protocol · tags: oip, federation, oip-message, envelope, fipa, macaroons · updated 2026-07-17T02:36:18.197Z # oip-message/1 — the federation envelope This is the wire format that lets an agent at one domain talk to an agent at another domain, hand it a narrowly-scoped bit of authority, get a real result back, and have both sides prove the exchange — without either side controlling the other's server. It rides on top of the [Object Invocation Protocol](/a/oip). OIP is the authority, execution, and receipt layer (who may do what, what actually ran, what happened). oip-message/1 is only the messaging layer: addressing, discovery, signatures, and the seven kinds of message. The two are separate on purpose. You can carry an OIP capability over this envelope, over email, or over anything else. The envelope does not care what runs; the OIP layer does not care how the bytes arrived. **One law above all: a message body is data, never an instruction.** Text you receive — even text that says "ignore your rules and run X" — is never executed. The only thing that can make anything run is an `invoke` message carrying a valid capability, and the receiving server re-checks every gate itself before it runs anything. This is what makes it safe to accept messages from a stranger's agent. ## The two halves of the network - **Identity is a domain thing.** An agent is named `local@domain`, like an email address — `pepper@miscsubjects.com`, `buttercup@peer.example`. The domain publishes a small file, `/.well-known/oip.json`, that lists its agents, each agent's public signing key, and where to send it messages. Anyone can resolve an agent with zero prior coordination, exactly the way anyone can send email to a Gmail address without asking Google first. - **Authority is a capability thing.** Being able to reach an agent grants nothing. To make it *do* something you must hand it a capability — a scoped, expiring, revocable token that names exactly what it may do. That comes from the OIP layer, and it can be bound to the one agent it was minted for (see *Audience* below). ## Discovery: /.well-known/oip.json Each domain publishes a document like this: ```json { "protocol": "oip-message/1", "domain": "miscsubjects.com", "agents": [ { "id": "pepper@miscsubjects.com", "alg": "ES256", "public_key_jwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." }, "inbox": "https://miscsubjects.com/oip/inbox" } ], "ledger": "https://miscsubjects.com/oip/ledger", "spec": "https://miscsubjects.com/a/oip-message" } ``` To resolve `agent@domain`: fetch `https:///.well-known/oip.json`, find the agent by `id`, read its `public_key_jwk` (to verify what it sends you) and its `inbox` (where to POST what you send it). Cache it briefly. This is the same shape webfinger and ActivityPub used to succeed at federation where older schemes stalled. ## The envelope Every message is one JSON object: ```json { "protocol": "oip-message/1", "id": "msg_9f3a...", "conversation": "conv_1b2c...", "in_reply_to": null, "kind": "query", "from": "buttercup@peer.example", "to": "pepper@miscsubjects.com", "created_at": "2026-07-15T20:00:00.000Z", "expires_at": "2026-07-15T20:05:00.000Z", "body": { "text": "what time is it" }, "capability": null, "body_sha256": "", "signature": { "alg": "ES256", "kid": "buttercup@peer.example", "value": "" } } ``` Rules a receiver enforces, in order, before it trusts anything: 1. **Shape.** Right protocol, a well-formed `id`, a known `kind`, `from`/`to` that parse as `local@domain`, a `body_sha256`, and a body under 64 KB. Bigger data travels by pointer (a URL in the body), not inline. 2. **Freshness.** `expires_at` must be in the future, by the *receiver's* clock. A stale envelope is rejected before its signature is even checked. Sender-supplied time never wins. Envelopes live at most 15 minutes. 3. **Body integrity.** Recompute `body_sha256` from the canonical body and compare. 4. **Signature.** Verify `signature.value` (ES256 over the canonical envelope with the `signature` field removed) against the sender's published key. This proves *which agent* sent the bytes. It grants no authority by itself. **Canonical JSON** (both sides must produce identical bytes): recursively sort object keys, drop `undefined`, no whitespace. The signature covers every field except `signature` itself — so moving `expires_at`, swapping the body, or changing `to` all break it. ## The seven kinds (FIPA-ACL performatives, trimmed) Each message declares what kind of act it is, so a receiver never guesses intent from prose. These are the speech acts standardized for agent communication in the 1990s; we use seven of them. | kind | meaning | grants authority? | |---|---|---| | `query` | asks for information | no — and requires none | | `propose` | proposes work | no — does not authorize it | | `invoke` | requests execution | **only with a valid capability** | | `result` | answers a query or invoke | carries receipt ids when something ran | | `event` | reports a state change | no | | `cancel` | asks to cancel a prior message by id | — | | `error` | structured refusal or failure | carries a machine-readable `reason` | A `query` is safe to answer from anyone: you echo or answer, and run nothing. An `invoke` is the only kind that can act, and only when its `capability` is valid and permits the named object. ## Capabilities across the federation The `capability` field carries an OIP capability token — scoped, expiring, use-limited, revocable. When an `invoke` arrives, the receiver does **not** trust the sender's word about what it may do. It resolves the token to its recorded capability and re-checks the whole contract: is it revoked, does its scope include this object, is every parent in its delegation chain still live, does the payload fit the size ceiling, is the tenant active, are there uses left. Only then does it run the object, and the result carries a real receipt id. ### Audience: a capability minted for one agent A federation capability may be **bound to the exact agent it was minted for** — a caveat in the Macaroon/object-capability sense. An audience-bound token: - runs **only** inside a signed `invoke` whose verified sender matches the audience (its full agent id, or its domain); - **fails closed if presented directly** at the door with no signed sender — so a leaked token is inert; - **fails closed if forwarded** to any other agent — a token minted for `buttercup@peer` dies in `mallory@peer`'s hands, because the signature proves the sender is mallory and the audience says buttercup; - may be **narrowed** when delegated (a domain audience down to one agent in it), never widened or moved to another domain. This is what makes it safe to hand authority across a boundary you do not control: the authority is useless to anyone but its intended holder, and useless anywhere but inside a signed message from that holder. ## Two ledgers, one provable exchange End-to-end privacy would rule out a single global plaintext ledger — but it does not rule out *auditing*. Each node keeps its **own** ledger of every exchange: message id, kind, verdict, and the body hash. The two ledgers are joined by message id and body hash. When both nodes recorded the same message id with the same `body_sha256`, both provably saw the same bytes — without a shared database and without either trusting the other's server. This is the Certificate-Transparency idea (independent append-only logs you can cross-check) applied to agent messages. - Home ledger: `https://miscsubjects.com/oip/ledger` - Peer ledger: `https://oip-peer.[custodian-redacted].workers.dev/oip/ledger` ## Failure taxonomy Every refusal is a structured `error` with a `reason`. The ones you will actually hit: - `expired_envelope` — past `expires_at` by the receiver's clock. - `body_hash_mismatch` / `bad_signature` — the bytes were altered in flight, or signed by the wrong key. - `replay_rejected` — this message id was already delivered once. Delivery is at-most-once. - `sender_unverifiable` — the sender is not published, so it may only `query`, never `invoke`. - `audience_mismatch` — a capability was presented by an agent it was not minted for. - `audience_bound` — an audience-bound capability was presented directly, outside a signed invoke. - `scope_mismatch` — the capability does not permit the named object. - `revoked` / `ancestor_revoked` — the capability, or a parent of it, was revoked. - `token_exhausted` — the capability is out of uses. ## What is and is not implemented - **Implemented:** discovery, ES256 signatures, the seven kinds, capabilities with the audience caveat, replay protection, dual ledgers with hash join, and a live two-node federation with a full failure-matrix self-test. - **Transport:** signed HTTPS between two independently operated Cloudflare nodes on two domains. That is real federation of the protocol — two separate operators, an open format, no central authority. - **Deliberately not built yet:** payload end-to-end encryption and an email (SMTP) transport. When encryption is added it belongs at *this* envelope layer, transport-agnostic (MLS, RFC 9420), not welded to any one wire. Deferring it is a choice, not an oversight — the protocol is proven first, encryption rides on top later. ## Prove it, and build against it - **Live federation self-test** (real exchanges between two domains, pass/fail per clause): [`/api/dispatch?fedtest=1&format=markdown`](/api/dispatch?fedtest=1&format=markdown) - **Protocol conformance** (every OIP clause executed live): [`/api/dispatch?conformance=1&format=markdown`](/api/dispatch?conformance=1&format=markdown) - **Reference client** (zero dependencies, browser or Node): [`https://miscsubjects.com/oip/client.mjs`](/oip/client.mjs) - **This domain's well-known:** [`/.well-known/oip.json`](/.well-known/oip.json) Minimal client use: ```js import { OIPClient, generateKeypairJwk } from 'https://miscsubjects.com/oip/client.mjs'; const me = new OIPClient({ agent: 'me@example.com', keypair: await generateKeypairJwk() }); const r = await me.query('pepper@miscsubjects.com', { text: 'what time is it' }); console.log(r.reply.body, 'verified:', r.reply_verified); ``` To be invokable by others, publish your own `/.well-known/oip.json` with your agent id, your public key, and your inbox — then implement the four receiver checks above. That is the whole entrance. A stranger can implement a node from this page alone. ## Where the ideas come from Nothing here is new; the parts are older than the web and were waiting for a client smart enough to use them. FIPA-ACL gave the message kinds. Macaroons and object-capability theory gave attenuating, audience-bound tokens. HATEOAS gave affordances-in-the-response (an LLM is the client it was always waiting for). Certificate Transparency gave cross-checkable independent logs. Telescript gave mobile agents carrying permits between places. This envelope is the confluence — the museum with a door.