# wire protocol — v0.1
This document defines the wire format that two `wire` implementations must agree on to interoperate. The Rust implementation in this repository is the reference; this document is normative.
## Conventions
- All multi-byte integers are big-endian.
- All hashes are SHA-256.
- All signatures are Ed25519 (RFC 8032).
- All base64 is RFC 4648 standard alphabet, no line wrapping, with padding.
- All hex is lowercase.
- Times are RFC 3339 / ISO 8601 with `Z` suffix (UTC).
- "MUST" / "SHOULD" / "MAY" follow RFC 2119 semantics.
## 1. Identity — DID + agent-card
Every wire endpoint has a stable identity backed by an Ed25519 keypair. The DID is `did:wire:<handle>` where `<handle>` is `[A-Za-z0-9_-]+`.
The signed **agent-card** binds the DID to one or more public keys plus capabilities and policies. v0.1 schema (`schema_version: "v3.1"`):
```json
{
"schema_version": "v3.1",
"did": "did:wire:paul",
"name": "Paul",
"capabilities": ["wire/v3.1"],
"verify_keys": {
"ed25519:paul:b2e5aae7": {
"key": "<base64-encoded 32-byte Ed25519 public key>",
"alg": "ed25519",
"active": true
}
},
"policies": {"max_message_body_kb": 64},
"signature": "<base64-encoded Ed25519 signature>"
}
```
**Key id format:** `<handle>:<fingerprint>` where fingerprint = first 8 hex chars of SHA-256(public_key_bytes). Cards on disk prefix this with `ed25519:` to allow algorithm migration in v0.2+.
**Signing rule:** signature is Ed25519 over `card_canonical(card)` — see §3 below — with `signature` field absent. To verify, strip `signature`, recompute the canonical bytes, run `Ed25519_Verify(verify_keys[*].key, canonical_bytes, signature)`.
Cards with empty or malformed `verify_keys` MUST be rejected.
## 2. Events — kinds, structure, signing
Events are signed JSON objects. v0.1 mandatory fields:
```json
{
"timestamp": "2026-05-10T03:46:01Z",
"from": "did:wire:paul",
"to": "did:wire:willard",
"type": "decision",
"kind": 1,
"body": "ship the v0.1 demo",
"event_id": "<64-char hex SHA-256>",
"public_key_id": "paul:b2e5aae7",
"signature": "<base64 Ed25519 signature>"
}
```
### 2.1 Kind ranges (Nostr-compatible)
| 1000–9999 | regular | persistent — relays SHOULD store indefinitely |
| 10000–19999 | replaceable | latest-by-(`from`, kind) wins |
| 20000–29999 | ephemeral | best-effort — relays MAY drop after delivery |
| 30000–39999 | addressable | replaceable, with optional `d` tag for namespacing |
**Special-cased out-of-range kinds (Nostr / heartbeat compatibility):**
| 1 | decision | regular |
| 100 | heartbeat | ephemeral |
v0.1 ships these named kinds:
| 1 | decision | Nostr-compat short message |
| 100 | heartbeat | liveness ping |
| 1000 | decision | wire-native decision |
| 1001 | claim | assertion or proposal |
| 1002 | ack | acknowledgement |
| 1100 | agent_card | self-card or peer-card update |
| 1101 | trust_add_key | add a verify key |
| 1102 | trust_revoke_key | revoke a verify key |
| 1200 | wire_open | bilateral wire establishment |
| 1201 | wire_close | bilateral wire teardown |
Kinds reserved for v0.2+: `1900` (file_share), `1901` (file_revoke), `10500` (registry_revocation). v0.1 implementations MUST NOT send or accept these. See `ANTI_FEATURES.md`.
### 2.2 event_id and signing
`event_id = hex(SHA-256(canonical(event, strict=true)))` — see §3 for canonical, where `strict=true` excludes `event_id` itself.
Signing: `signature = base64(Ed25519_Sign(private_key, hex_decode(event_id)))`. The signature commits to the 32-byte raw event_id digest, which transitively commits to the canonical body. This is the Nostr NIP-01 sign-over-id pattern; it lets relays cite events by id without re-canonicalizing the body.
### 2.3 Verification rules
To verify a received event:
1. Recompute `event_id'` from the body. Reject if `event_id' != event_id`.
2. Resolve `public_key_id` to a public key in the trust state. Reject if unknown or marked `active: false`.
3. `Ed25519_Verify(public_key, hex_decode(event_id), base64_decode(signature))`. Reject on failure.
4. Reject if `to` is set and does not match the recipient's own DID.
The `from` field MAY be the bare handle (`paul`) or fully-qualified DID (`did:wire:paul`). Verifiers MUST accept both forms.
## 3. Canonical form
Canonical JSON serialization is the input to all hashing and signing. Rules:
1. Object keys serialize in lexicographic byte order.
2. No whitespace anywhere; separators are `","` and `":"`.
3. UTF-8 throughout. Non-ASCII characters are NOT `\u`-escaped.
4. **Top-level** fields `signature` and `public_key_id` are always stripped before serialization.
5. **Top-level** field `event_id` is stripped iff `strict=true`.
Strict mode is used when computing event_id (the field cannot reference itself). Non-strict mode is used everywhere else (verification, transport).
## 4. Trust state
Each agent maintains a local trust state, persisted to `~/.config/wire/trust.json`:
```json
{
"version": 1,
"agents": {
"paul": {
"tier": "ATTESTED",
"did": "did:wire:paul",
"public_keys": [
{
"key_id": "paul:b2e5aae7",
"key": "<base64 pub>",
"added_at": "<rfc3339>",
"active": true
}
]
},
"willard": {
"tier": "VERIFIED",
"did": "did:wire:willard",
"card": { ... full signed card ... },
"pinned_at": "<rfc3339>",
"verified_at": "<rfc3339>"
}
}
}
```
### 4.1 Tiers
| `UNTRUSTED` | initial pin | events ignored |
| `VERIFIED` | SAS confirm or `wire pin` of signed card | events accepted |
| `ATTESTED` | self-attestation only | self events accepted |
| `TRUSTED` | reserved for v0.2+ | reserved |
Promotion is **one-way**: `UNTRUSTED → VERIFIED → ATTESTED`. Reverting requires removing the agent record entirely.
## 5. Pairing — SPAKE2 + SAS + AEAD
### 5.1 Code phrase
Format: `NN-XXXXXX` where `NN` is two random decimal digits and `XXXXXX` is six random base32 characters from the RFC 4648 alphabet (`A-Z2-7`, no `0/1` ambiguity). Total entropy ~36.6 bits.
Operators read this aloud over a side channel they trust.
### 5.2 SPAKE2 handshake
Both sides instantiate `Spake2<Ed25519Group>::start_symmetric` with:
- `password = code_phrase.as_bytes()`
- `identity = pair_id_from_relay`
`pair_id_from_relay` is a 16-byte random hex string the relay assigns when the host opens a pair-slot keyed by `code_hash = SHA-256("wire/v1 code-phrase" || code_phrase)`. Including `pair_id` in the SPAKE2 identity prevents crosstalk between concurrent pairings on the same relay.
Both sides exchange SPAKE2 messages via the relay's `/v1/pair` endpoints (see §6.4) and call `finish()` on the peer's message to derive a 32-byte shared secret.
### 5.3 Short Authentication String (SAS)
Both sides compute identically:
```
```
Format displayed: `XXX-XXX` (split for readability). Operators verify by reading aloud.
If digits do not match, MITM is suspected. Operators MUST refuse confirmation; the implementation MUST NOT proceed with the bootstrap exchange.
### 5.4 AEAD bootstrap
After SAS confirmation, both sides:
1. Derive a ChaCha20-Poly1305 key: `aead_key = HKDF-SHA256(salt=code_hash, ikm=spake_key, info="wire/v1 bootstrap-aead", L=32)`.
2. Build a bootstrap payload: `{"card": <signed-card>, "relay_url": <url>, "slot_id": <id>, "slot_token": <token>}`.
3. Seal: random 12-byte nonce + ChaCha20-Poly1305 over canonical JSON of the payload. Wire format: `nonce || ciphertext+tag`.
4. POST to `/v1/pair/<pair_id>/bootstrap` with role=host|guest.
5. Poll `/v1/pair/<pair_id>?as_role=host|guest` for the peer's sealed payload.
6. Open with `aead_key`. AEAD failure → abort pairing; do not retry.
7. `verify_agent_card` on peer's card. Bad signature → abort.
8. Pin peer's card at tier `VERIFIED`. Save peer's relay coordinates.
## 6. Relay HTTP endpoints
The reference relay binds to an arbitrary host:port. All endpoints emit JSON responses; errors include `{"error": "<msg>"}`.
### 6.1 `GET /healthz`
Returns `200 OK` with body `ok\n`. Liveness check; no auth.
### 6.2 `POST /v1/slot/allocate`
Allocates an event-slot. Request body: `{"handle": "<optional>"}`. Response: `{"slot_id": "<32-hex>", "slot_token": "<64-hex>"}`. The token is a bearer for both reads and writes.
### 6.3 Event slots
- `POST /v1/events/<slot_id>` body `{"event": <signed-event>}`, `Authorization: Bearer <slot_token>` — stores or dedupes by `event_id`. Response: `{"event_id": "<id>", "status": "stored"|"duplicate"}`. Body cap: 256 KiB. Returns 401/403 on bad/missing token, 404 on unknown slot, 413 on body cap exceeded.
- `GET /v1/events/<slot_id>?since=<event_id>&limit=<n>`, bearer auth — returns `[<event>, ...]` from after `since` (exclusive). Default limit 100, max 1000.
### 6.4 Pair slots
Pair slots are ephemeral, in-memory only. A relay restart aborts in-progress pairings; clients MUST handle this by retrying.
- `POST /v1/pair` body `{"code_hash": "<hex>", "msg": "<base64-spake-msg>", "role": "host"|"guest"}`. Response: `{"pair_id": "<32-hex>"}`. Host registers first; guest finds the existing slot via `code_hash`. Same role registering twice for one slot returns `409 Conflict`.
- `GET /v1/pair/<pair_id>?as_role=host|guest`. Returns the OTHER side's data: `{"peer_msg": "<b64>"|null, "peer_bootstrap": "<b64>"|null}`. Returns 404 on unknown `pair_id`.
- `POST /v1/pair/<pair_id>/bootstrap` body `{"role": "host"|"guest", "sealed": "<base64>"}`. Stores the sealed bootstrap payload from our side.
The relay performs no Ed25519 verification, no PAKE arithmetic, no decryption. It is a dumb pipe. Trust is established and verified entirely client-side.
## 7. Persistence
The reference implementation stores events to `<state_dir>/slots/<slot_id>.jsonl` (append-only, one event per line) and tokens to `<state_dir>/tokens.json`. Pair slots are NOT persisted.
A relay MUST reload event slots and tokens on startup to provide restart-recovery. Pair slots MUST start empty.
## 8. Forward compatibility
- Unknown top-level fields in events MUST be preserved verbatim through canonicalization. Implementations MUST NOT drop fields they don't recognize.
- New `kind` ids in unused range slots are forward-compatible: an old verifier sees an unknown kind and routes by class (regular/replaceable/ephemeral/addressable). Application logic decides whether to accept or skip.
- New top-level fields in agent-cards are similarly preserved.
- Schema bumps (e.g. `schema_version: "v4.0"`) require a migration path documented at the time of bump.
## 9. What this protocol does NOT specify
- Discovery (pairings are out-of-band; no DHT, no registry in v0.1)
- Group rooms (mesh-of-bilateral only — see `ANTI_FEATURES.md`)
- Message encryption above the wire layer (events are signed-plaintext in v0.1; encryption pending NIP-44 v2 or DIDComm authcrypt in v0.2+)
- Spam control (relay accepts any signed event under the body cap; rate limiting is operator-side)
- File transfer above 256 KiB (deferred to v0.2)
- Federation between relays (each pair shares one relay; cross-relay roaming is v0.3+)