# 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