oip-message/1 — the federation envelope

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:

{
  "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://<domain>/.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:

{
  "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": "<sha-256 of the canonical body>",
  "signature": { "alg": "ES256", "kid": "buttercup@peer.example", "value": "<base64url>" }
}

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.

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
• Protocol conformance (every OIP clause executed live): /api/dispatch?conformance=1&format=markdown
• Reference client (zero dependencies, browser or Node): https://miscsubjects.com/oip/client.mjs
• This domain's well-known: /.well-known/oip.json

Minimal client use:

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.