---
slug: oip-message
title: oip-message/1 — the federation envelope
canonical: https://miscsubjects.com/a/oip-message
---

# 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://<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:

```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": "<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.

| 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.

