# Protocol: agent-mail/0.1 This file is normative. Every instance built from this spec must produce and accept exactly these shapes, so that separate builds interoperate. `test-vectors.json` has worked examples of each; a build passes them all. Documents are JSON in ActivityStreams 2.0 compact form. Consumers read the properties as written here; no JSON-LD expansion is needed or done. Unknown properties are ignored. URLs are `https`. (A test-only var allows `http://localhost` and `http://127.0.0.1` so two local instances can talk.) Base64url is RFC 4648 section 5 without padding. Base64 (in structured header byte sequences) is standard with padding. ## 1. Identity and discovery ### 1.1 WebFinger (RFC 7033) ``` GET /.well-known/webfinger?resource=acct:alice@a.example 200 Content-Type: application/jrd+json Access-Control-Allow-Origin: * {"subject":"acct:alice@a.example", "aliases":["https://a.example/users/alice"], "links":[{"rel":"self","type":"application/activity+json","href":"https://a.example/users/alice"}]} ``` `resource` may also be the actor URL. The host part must equal the host of `SITE_URL` (including the port, if any). Unknown: 404 `not_found`. ### 1.2 Actor document `GET /users/` with `Content-Type: application/activity+json`: ```json { "@context": ["https://www.w3.org/ns/activitystreams", "https://w3id.org/security/multikey/v1", {"am": "https://spekkr.com/dwrtz/agent-mail/ns#", "keyAgreement": {"@id": "https://w3id.org/security#keyAgreementMethod", "@type": "@id"}}], "id": "https://a.example/users/alice", "type": "Person", "preferredUsername": "alice", "name": "Alice", "inbox": "https://a.example/users/alice/inbox", "outbox": "https://a.example/users/alice/outbox", "assertionMethod": [{"id": "https://a.example/users/alice#sig-1", "type": "Multikey", "controller": "https://a.example/users/alice", "publicKeyMultibase": "z6Mk..."}], "keyAgreement": [{"id": "https://a.example/users/alice#enc-1", "type": "Multikey", "controller": "https://a.example/users/alice", "publicKeyMultibase": "z6LS..."}], "am:protocol": "agent-mail/0.1", "am:readReceipts": false } ``` - `assertionMethod`: Ed25519 signing keys (FEP-521a style). Multikey: `"z"` + base58btc(`0xed 0x01` + 32-byte public key). - `keyAgreement`: X25519 HPKE keys. Multikey: `"z"` + base58btc(`0xec 0x01` + 32-byte public key). Senders use the **last** entry. Empty until the user sets up encryption. - Key ids are `#sig-` and `#enc-`. - Every key's `controller` equals the actor `id`. - `GET /users//outbox` returns an empty `OrderedCollection` (`{"@context":"https://www.w3.org/ns/activitystreams","id":"","type":"OrderedCollection","totalItems":0,"orderedItems":[]}`); messages are never public. ### 1.3 Signing key derivation (this implementation's choice; not visible on the wire) `ed25519 seed = HKDF-SHA256(ikm = base64url-decode(SIGNING_SEED), salt = "agent-mail/0.1", info = "sig::", L = 32)`. Version starts at 1. Vector: `signing_key_derivation`. ## 2. Request signatures (RFC 9421 + RFC 9530) Every inbox POST and every attachment GET between instances is signed. **POST** headers: ``` Content-Type: application/activity+json Content-Digest: sha-256=:: Signature-Input: am=("@method" "@target-uri" "content-type" "content-digest");created=;expires=;nonce="";keyid="#sig-";alg="ed25519";tag="agent-mail" Signature: am=:: ``` **GET** (attachments): `Signature-Input: am=("@method" "@target-uri");created=...;expires=...;nonce="...";keyid="...";alg="ed25519";tag="agent-mail"`. - The signature base is built exactly as RFC 9421 section 2.5: one line `"": ` per covered component in order, then `"@signature-params": ` + `\n` + ``. This binds each ciphertext to its Note and its recipient: it cannot be replayed into another message or to another member. - Plaintext = UTF-8 JSON: ```json {"v":1, "summary":"Lunch?", "content":"Are you free for lunch on Friday?", "attachments":[{"url":"https://a.example/attachments/6b0c...","name":"hello.txt","mediaType":"text/plain", "size":17,"key":"","iv":""}]} ``` `summary` (subject) may be null. `content` is plain text, at most 65,536 characters. `attachments[].size` is the plaintext size; one entry per `attachment` on the Note, matched by `url`. - Vector: `hpke` (with a fixed `ikmE` so the output is reproducible) and RFC 9180 A.1.1 under `rfc_vectors`. ### 3.1 Attachment encryption AES-256-GCM, a fresh random 32-byte key and 12-byte IV per file, no AAD. Stored bytes = ciphertext followed by the 16-byte tag. The Note's `am:size` and `am:digest` describe the stored bytes, so the fetcher checks them before decrypting. Vector: `attachment`. ## 4. Activities All activities have `"@context": ["https://www.w3.org/ns/activitystreams", {"am": "https://spekkr.com/dwrtz/agent-mail/ns#"}]`, an `id` on the actor's origin (`/activities/`), `actor`, `to` (a non-empty array of actor ids, the members other than the actor, at most 49) and `published` (ISO 8601 UTC). ### 4.1 Create (a message) One POST per recipient. Every copy has the same activity `id` and Note `id`; only `am:encrypted` differs. ```json { "@context": [...], "id": "https://a.example/users/alice/activities/", "type": "Create", "actor": "https://a.example/users/alice", "published": "2026-11-17T02:00:00Z", "to": ["https://b.example/users/bob"], "object": { "id": "https://a.example/users/alice/notes/", "type": "Note", "attributedTo": "https://a.example/users/alice", "to": ["https://b.example/users/bob"], "published": "2026-11-17T02:00:00Z", "context": "https://a.example/users/alice/threads/", "inReplyTo": null, "content": "This message is end-to-end encrypted.", "am:seq": 1, "am:encrypted": {"kem": 32, "kdf": 1, "aead": 1, "recipient": "https://b.example/users/bob", "keyId": "https://b.example/users/bob#enc-1", "enc": "", "ct": ""}, "attachment": [{"type": "Document", "url": "https://a.example/attachments/<32 hex>", "mediaType": "application/octet-stream", "am:size": 33, "am:digest": "sha-256=::"}] } } ``` - `content` in the clear is always the fixed placeholder `This message is end-to-end encrypted.` (so a plain ActivityPub server shows something sensible). The real text is only in `am:encrypted`. - `context` is the thread id. `inReplyTo` is the Note answered, or null. - `am:seq` counts this actor's activities (Create, Add, Remove) in this thread, from 1. - `attachment` is optional (at most 10). Attachment URLs are on the actor's origin. `mediaType` on the wire is always `application/octet-stream`; the real type is inside the ciphertext. ### 4.2 Add and Remove (group membership) ```json {"@context": [...], "id": "/activities/", "type": "Add", "actor": "", "object": "", "target": "", "to": [""], "am:members": [""], "am:seq": 4, "published": "..."} ``` `Remove` is the same with `object` = the member removed; its `to` also includes the removed member. A member leaving sends `Remove` with `object` = `actor`. Only the creator (the actor before `/threads/` in the thread id) may Add, or Remove someone else. ### 4.3 Read (receipt, opt-in) ```json {"@context": [...], "id": "/activities/", "type": "Read", "actor": "", "object": "", "to": [""], "published": "..."} ``` Sent only by users who turned receipts on. ### 4.4 Anything else `Follow`, `Like`, `Delete`, etc. get 422 `unsupported_activity`. ## 5. Inbox responses and error codes | Status | `error` | When | |---|---|---| | 202 | (`{"status":"accepted"}` or `{"status":"duplicate"}`) | Accepted, or already received | | 400 | `bad_request` | Missing or malformed query / body | | 400 | `bad_activity` | Activity fails the shape rules above | | 400 | `digest_mismatch` | Content-Digest missing, not sha-256, or wrong | | 401 | `signature_missing` | No Signature-Input/Signature with tag agent-mail | | 401 | `signature_invalid` | Malformed, missing components/params, wrong alg, or does not verify | | 401 | `signature_expired` | `created` skewed by more than 300 s, or past `expires` | | 401 | `key_unavailable` | keyid's actor cannot be fetched or does not list the key | | 401 | `replayed_nonce` | `(keyid, nonce)` seen in the last 15 minutes | | 403 | `actor_mismatch` | keyid belongs to a different actor than `actor` | | 403 | `not_member` | Create in a known thread from a non-member | | 403 | `not_thread_owner` | Add/Remove of someone else by a non-creator | | 403 | `forbidden` | Attachment GET by an actor not sent that attachment | | 404 | `not_found` | Unknown user, attachment or route | | 413 | `too_large` | Inbox body over 256 KiB, attachment over 25 MiB | | 415 | `unsupported_media_type` | Wrong Content-Type | | 422 | `unsupported_activity` | Type not supported | | 422 | `unsupported_encryption` | HPKE ids not 32/1/1 | | 422 | `group_too_large` | More than 50 members | | 422 | `not_addressed` | Inbox owner not in `to` / not the `am:encrypted.recipient` | | 429 | `rate_limited` | Over 120 inbox POSTs per minute from one host; `Retry-After` set | Body: `{"error":"","detail":""}`, `Content-Type: application/json`. ## 6. Doorbell body ```json {"type":"agent-mail.doorbell","handle":"david@agent.example.com","unread":3,"requests":1,"at":"2026-11-17T02:00:05.000Z"} ``` Nothing else. The header named in settings carries the configured value.