> Source file last changed: 2026-11-03. Dates inside the document record when each part was written, checked or submitted. > **Reading this document.** This is CHANNEL's working engineering specification, published as it is kept. It records design history as it goes: dates, work-item numbers such as `J1559`, and rulings by the project's owner. Where a section says it is superseded or reserved, it describes nothing in the app. What the app does today is on the help pages. # PROTOCOL.md — ChannelMessenger wire protocol, normative **WireProtocol v1 · Envelope v1 · Handshake v1 · CryptoSuite v1 · RoutingProtocol v1** Status: **draft complete, checkpoint 3** — §0–§9. Test vectors in `vectors/`. `THREAT-WALKTHROUGH.md` is the remaining Assignment 01 deliverable. **§6.5 (Handshake v1) was added on 2 September 2026.** The header above had named Handshake v1 as a v1 component since the first draft, and §4.2 had described its output, but no section defined the exchange — §4.2's cross-reference pointed at §6.2, which is the encounter sequence and contains no pairing step. `THREAT-WALKTHROUGH.md` predates §6.5 and does not yet cover packet types 11–13; §6.5.8 carries that analysis in the meantime. This document is normative. It must be sufficient for an Android engineer and an iOS engineer, working from it alone, to produce byte-compatible implementations. Where it is ambiguous, that is a defect in this document — record it in `SPEC.md` §6 rather than resolving it locally. Governing documents, in precedence order: `DECISIONS.md`, `SPEC-REVISION.md`, `SPEC-ORIGINAL.md`. --- ## 0. Conventions **Requirement levels.** MUST / MUST NOT / SHOULD / MAY per RFC 2119. Constants marked **[policy]** are tunable and appear in §9's policy table. They are SHOULD, not MUST, and are expected to change empirically (`DECISIONS.md` D1). An implementation MUST read them from configuration rather than hardcoding them, and MUST NOT reject a peer for holding different values. **Byte order.** All multi-byte integers on the wire are **big-endian** unless stated otherwise. **Byte strings** are written as lowercase hex. `‖` denotes concatenation. `len(x)` is the length of `x` in bytes. **Fixed-width means fixed-width.** Fields specified with an exact byte count are never length-prefixed, never variable, and never omitted. Absent optional values are encoded as their defined zero value, not skipped. **Hostile input.** Every parser MUST treat received data as hostile (`SPEC-ORIGINAL` §39). Length bounds are checked *before* allocation. No force-unwrapping, no `try!`, no `unwrap()` on network-derived or cryptographic input. A packet that fails any structural or cryptographic check is discarded immediately and silently — implementations MUST NOT return distinguishing errors to a peer, because doing so builds an oracle. --- ## 1. Canonical CBOR The wire format is CBOR (RFC 8949). Determinism matters because two implementations that encode the same data differently will fail to interoperate — and, before `DECISIONS.md` C1, would have failed *authentication* with no obvious cause. ### 1.1 Encoding rules — normative An ChannelMessenger encoder MUST produce, and a decoder MUST accept only, CBOR satisfying **RFC 8949 §4.2.1 core deterministic encoding**: 1. **Map key ordering: bytewise lexicographic on the encoded key.** Keys are sorted by comparing their encoded byte sequences directly. 2. **RFC 7049 canonical ordering is FORBIDDEN.** The older standard sorted by encoded length first, then bytewise. It produces a different order and some libraries still default to it. An implementation MUST NOT use length-first ordering. This is named explicitly because "canonical CBOR" is ambiguous between two incompatible standards, and choosing silently is the single most likely source of cross-platform divergence in this protocol. 3. **Shortest-form integers.** A value MUST be encoded in the smallest representation that holds it. `5` is `0x05`, never `0x18 0x05`. 4. **Definite lengths only.** Indefinite-length arrays, maps, byte strings and text strings MUST NOT be emitted, and MUST be rejected on decode. 5. **Integer map keys only.** Every map key defined by this protocol is an unsigned integer. Text string keys MUST NOT be used. This is both smaller and removes any question of collation. 6. **No floating point.** No half, single or double precision values appear anywhere in this protocol. A decoder MUST reject them. 7. **No tags** other than those this document defines. Currently: none. 8. **Canonical simple values.** `false`/`true`/`null` only; no undefined. > **Measured, not assumed.** `vectors/03-canonical-cbor.json` demonstrates that for canonically > encoded *unsigned integer* keys, the RFC 8949 and RFC 7049 orderings **always coincide** — CBOR's > uint encoding is monotonic in both value and encoded length, so bytewise and length-first sorting > agree. Rule 5 therefore does more than save bytes: it removes the 8949-vs-7049 hazard from every > map this protocol defines. Rule 2 stays normative anyway, because it must hold for any future map > that is not integer-keyed, and because an implementation should not be relying on a coincidence it > has not checked. > **`J1573`, 27 September 2026: an envelope with bytes after its item is refused.** Counted first > (`Envelopes with trailing bytes` in both reports) and refused only after the count read zero on > three devices over Bluetooth, the local network and the Internet. Attachment slices are refused > too. > > **28 September 2026: link-layer packets and group rosters are refused the same way.** A packet > frame whose item re-encodes to a different length than the frame, and a roster with bytes after > it, are refused and counted (`link packets and rosters` in both reports). Refused after that > count read zero on the owner's iPhone and Android on 2.872, counting since 27 September 04:48. > Every decoder in §1.1's list now accepts only the canonical encoding and nothing after it. ### 1.2 Unknown fields Forward compatibility (`SPEC-ORIGINAL` §35): - A decoder MUST ignore unknown **optional** map keys and MUST preserve nothing about them — they are not re-emitted on forward, because re-emitting attacker-chosen bytes would let a sender smuggle a covert channel through relays. - A decoder MUST reject a packet containing an unknown key in a **required capability** position (§ to be defined in checkpoint 2's CAPABILITY negotiation), failing negotiation gracefully rather than proceeding. - Unknown `protocolVersion` values are handled per §2.2. ### 1.3 What canonical CBOR is *not* responsible for Authentication does **not** depend on any of the above. The AAD is a fixed-layout byte concatenation (§3), constructed without CBOR. A CBOR disagreement between two implementations therefore produces a visible parse failure, not a silent universal authentication failure. See `DECISIONS.md` C1 for why this matters more than any single rule in §1.1. Compression, likewise, needs no canonical determinism: it sits inside the encryption boundary, so only the format must be pinned (`DECISIONS.md` C6). --- ## 2. Envelope v1 The Envelope is the unit of delivery. It is byte-identical regardless of the path it travels — direct, relayed, courier-carried, or across an internet gateway hop (`SPEC-ORIGINAL` §2). No transport re-encrypts or rewrites it. ### 2.1 Fields Encoded as a CBOR map with integer keys, per §1.1. | Key | Name | Type | Width | In AAD | Mutable in transit | |----:|------|------|-------|:------:|:------------------:| | 1 | `protocolVersion` | uint | 1 byte | yes | no | | 2 | `packetID` | bstr | 16 bytes | yes | no | | 3 | `destinationToken` | bstr | 16 bytes | yes | no | | 4 | `creationBucket` | uint | 4 bytes | yes | no | | 5 | `expiresAfter` | uint | 1 byte | yes | no | | 6 | `transitPolicy` | uint | 1 byte | yes | no | | 7 | `payloadLength` | uint | 2 bytes | yes | no | | 8 | `fragmentIndex` | uint | 1 byte | yes | no | | 9 | `fragmentCount` | uint | 1 byte | yes | no | | 10 | `totalLength` | uint | 4 bytes | yes | no | | 11 | `nonce` | bstr | 12 bytes | no | no | | 12 | `hopLimit` | uint | 1 byte | **no** | **yes** | | 13 | `ciphertext` | bstr | variable | no | no | Nothing else. In particular the Envelope carries no display name, device name, OS, model, build number, account identifier, or any permanent identifier of any kind (`SPEC-ORIGINAL` §13, §15). ### 2.2 Field definitions **`protocolVersion`** — `1` for this document. A node receiving a higher major version it does not implement MUST discard the packet and MUST NOT relay it, because it cannot validate the structure it would be forwarding. **`packetID`** — 16 bytes from a cryptographically secure random source. > **Duplicate suppression and inventory are keyed on `packetID ‖ fragmentIndex`, not on `packetID` > alone.** All fragments of one message share a packet id, so a message-granularity table marks the > whole message seen when its *first* fragment arrives and then rejects every sibling as a replay — > fragmentation and duplicate suppression cannot both work at message granularity. **The relayed and > suppressed unit is a fragment.** Reassembly happens only at the destination (§3.2). Found by an > end-to-end test after both mechanisms were separately correct. It MUST NOT be derived from the content, the sender, the recipient, or the time; a derived ID would be a linkable fingerprint. 128 bits makes collision negligible across any plausible mesh size. *Privacy note:* `packetID` is necessarily constant along a packet's whole journey — that is what makes duplicate suppression work. A global observer could therefore trace one packet across the network. This is accepted and is already excluded from the threat model (`SPEC-ORIGINAL` §32, global radio traffic analysis). **`destinationToken`** — 16 bytes, derived per checkpoint 2. Distinct from `presenceToken` (`DECISIONS.md` C3): a relay that heard a presence beacon MUST NOT be able to match it against an envelope it is carrying. **`creationBucket`** — the sender's creation time as `floor(unixTime / 600)`, i.e. in 600-second buckets, matching the token epoch length so it reveals nothing the token does not already. It exists because expiry alone is insufficient: if lifetime were measured only from each hop's receipt time, a packet could be kept alive indefinitely by repeated relaying. An absolute creation bucket bounds total lifetime regardless of path. **`expiresAfter`** — lifetime in 600-second buckets **relative to `creationBucket`**, not an absolute timestamp. Relative encoding avoids publishing the sender's clock. A packet is expired when `nowBucket > creationBucket + expiresAfter`. Range 1–255 (up to ~42.5 h). Relays SHOULD reject values above `MAX_RELAY_LIFETIME` **[policy]**, default 144 buckets (24 h). Note this bounds *relay* retention only; a sender holds its own undelivered outbound messages indefinitely (`DECISIONS.md` A4). **`transitPolicy`** — sender-declared routing restriction. | Value | Meaning | |------:|---------| | 0 | **Local only.** MUST NOT traverse an internet gateway hop. **Default.** | | 1 | Any transport permitted, including gateway. | Binary by design, not a bitfield: every additional bit is another feature relays can sort traffic by (`DECISIONS.md` D5). Default-restrictive so the bulk of traffic sits in the restrictive class and *permitting* gateway transit is the deliberate act, rather than the restrictive flag marking out exactly the traffic someone cared about. This field is **advisory**. Relays share no key with the sender and cannot be compelled to honour it. It is included in the AAD so that *tampering* is detectable end-to-end, but a relay that simply ignores it leaves no trace. Implementations MUST NOT present this to users as a guarantee. **`payloadLength`** — length of `ciphertext` in bytes, including the AEAD tag. MUST equal `len(ciphertext)`; a mismatch is a discard. Because of mandatory bucketed padding (§5.3) this takes one of a small set of values, not an arbitrary one. **`fragmentIndex`, `fragmentCount`, `totalLength`** — fragmentation, per `SPEC-ORIGINAL` §13. **Fragmentation is decided before sealing, and never afterwards.** `fragmentCount` is inside the AAD (§3.2), so a sender must know how many fragments there will be at the moment it encrypts. It follows that **a relay MUST NOT re-fragment** an envelope to fit a smaller transport MTU: it holds no key and cannot recompute the tag. Fragmentation is the sender's decision for the whole journey. Unfragmented envelopes use `fragmentIndex = 0`, `fragmentCount = 1`, `totalLength = payloadLength`. Fragmentation is the mechanism most likely to undo the size cap, so (`DECISIONS.md` C7): - `totalLength` MUST be validated against `MAX_ENVELOPE_BYTES` **[policy]** (default 65536; `J3748`) **before** any reassembly buffer is allocated. - `fragmentCount` MUST NOT exceed `MAX_FRAGMENTS` **[policy]** (default 16). - All fragments of one message MUST carry identical `packetID`, `destinationToken`, `creationBucket`, `expiresAfter`, `transitPolicy`, `totalLength`, **`fragmentCount` and `nonce`**. A fragment disagreeing with its siblings on any of these MUST cause the entire partially-reassembled message to be discarded — not merely that fragment rejected. A mismatch means someone is injecting, and keeping the partial buffer would let them keep trying. *`fragmentCount` was added to this list after implementation: `fragmentIndex` is meaningless except relative to it, and a reassembly slot table is sized from it, so disagreement is not survivable.* *`nonce` was added after an external review. The AEAD runs once over the whole plaintext (§3.2), so a message has exactly one nonce — but nothing checked that siblings carried the same one. A receiver would take the nonce from whichever envelope completed the set, so altering it on any single fragment silently destroyed a correctly reassembled message.* - A reassembly buffer MUST be bounded in count **[policy]** and MUST expire with the envelope. **`nonce`** — 12 bytes, unique per encryption under a given key (`SPEC-ORIGINAL` §11). Generated from a CSPRNG. A receiver MUST reject a `(key, nonce)` pair it has already accepted. It is **excluded from the AAD** because the AEAD already authenticates it: the nonce is an input to the tag computation, so altering it makes the tag fail (§3.1 gives the full reason; the test `altering_the_nonce_breaks_authentication` holds it). **`hopLimit`** — remaining hops. Decremented by one at each relay. A packet with `hopLimit == 0` MUST NOT be forwarded. **This is the only field mutable in transit, and it is therefore excluded from the AAD** (`DECISIONS.md` C4) — including it would break the authentication tag at the first hop. The security consequence must be stated rather than glossed: `hopLimit` is **unauthenticated and adversarially mutable**. A hostile relay can decrement it faster than it should (silently killing delivery) or raise it (amplifying network load). No pairwise key can prevent this, because relays share no secret with the sender. The defences are entirely local: each node enforces its own `MAX_ACCEPTED_HOP_LIMIT` **[policy]** and MUST clamp or reject anything above it — otherwise one permissive build injecting `hopLimit = 200` conscripts every honest node into carrying it. A receiver that wants to know whether a message was carried does not read `hopLimit` alone (a sender that forbids carrying seals 0, and so does one carried once with a limit of 1): the sender also writes the limit it sealed with inside the payload, `hopBudget` (§5.1f). The difference is a count of carriers, and a label only. **`ciphertext`** — the AEAD output, ciphertext ‖ 16-byte tag. Opaque to every party except the destination. Its plaintext structure is defined in checkpoint 2. ### 2.3 Size bound A complete encoded Envelope MUST NOT exceed `MAX_ENVELOPE_BYTES` **[policy]**, default 65536 (`J3748`: the code has held 65,536 since `J600`, the last size a `u16` `payloadLength` can describe; BLE carries at most 49,152). A receiver MUST check the framed length against this bound before allocating, and MUST abandon a transfer that exceeds it rather than truncating. --- ## 3. AAD construction **The AAD is a fixed-layout byte concatenation. It is NOT a CBOR re-encoding of the header.** This is `DECISIONS.md` C1, and it is the most important structural decision in this document. If AAD were "the canonical CBOR encoding of the header," two implementations disagreeing about map key ordering would compute different tags, and *every* message between them would fail authentication — surfacing as "authentication failed," which sends a developer to inspect the cryptography, where nothing is wrong. With a fixed layout, a CBOR disagreement produces a visible parse error instead, and the security-critical path contains no ambiguity at all. ### 3.1 Layout — exactly 47 bytes Constructed in this order, with no separators, no length prefixes, and no CBOR: ``` offset size field ------ ---- --------------------------------------------------- 0 1 protocolVersion uint8 1 16 packetID bstr 17 16 destinationToken bstr 33 4 creationBucket uint32 big-endian 37 1 expiresAfter uint8 38 1 transitPolicy uint8 39 2 payloadLength uint16 big-endian 41 1 fragmentIndex uint8 42 1 fragmentCount uint8 43 4 totalLength uint32 big-endian ------ ---- --------------------------------------------------- 47 bytes total, always ``` **Excluded and why:** - `hopLimit` — mutable in transit (§2.2). Including it would break the tag at the first hop. - `nonce` — **already authenticated implicitly, so including it would add nothing.** ChaCha20-Poly1305 derives its Poly1305 one-time key from the cipher keyed with (key, nonce). Alter the nonce and that key changes, so the tag cannot verify. An earlier version of this document said including the nonce "would be circular", which is simply wrong — an AAD is just bytes and the nonce could sit in it. The reason it need not is authentication, not circularity. Corrected after an external review flagged the rationale; `altering_the_nonce_breaks_authentication` in the test suite is the proof, and it fails loudly if this ever stops holding. - `ciphertext` — authenticated by the AEAD construction itself. The AAD length is constant at 47 bytes for every envelope, fragmented or not. There is no length-prefix ambiguity and no canonicalisation step. An implementation that produces 47 bytes in this order is byte-identical to every other conforming implementation, in any language. ### 3.2 Fragmented messages have exactly one AAD The AEAD is computed **once, over the whole plaintext**, before fragmentation. So a fragmented message has one AAD, not one per fragment, and it MUST be constructed canonically: ``` fragmentIndex = 0 fragmentCount = the real count, N payloadLength = totalLength (the whole ciphertext, not this fragment's slice) ``` Every other field is as normal. A receiver reassembles first, then builds this AAD, then verifies. **Consequence, and it must be stated rather than discovered.** A fragment's *own* `fragmentIndex` and its *own* `payloadLength` are therefore **not authenticated** — they are reassembly instructions, not protected content, in the same category as `hopLimit` (§2.2). An attacker who can inject fragments can therefore corrupt reassembly and cause the AEAD tag to fail, destroying the message. **This is a denial of service, not a break** — the content stays confidential and forgery remains impossible. And it grants no new capability: anyone positioned to inject fragments is already positioned to simply drop them, which is equally effective and simpler. Recorded in `THREAT-WALKTHROUGH.md` §8 rather than mitigated, because per-fragment authentication would cost bytes on every packet to defend against an attacker who has a cheaper attack available. ### 3.3 Construction is independent of parsing An implementation MUST build the AAD from the *decoded field values*, not from the received bytes. Two conforming encoders produce identical CBOR, so in practice these agree — but binding to decoded values means a non-canonical encoding from a buggy peer fails cleanly at the parse step rather than producing a valid-looking tag over malformed bytes. ### 3.4 Worked example Fully specified test vectors are in `vectors/`. Illustratively, an unfragmented envelope with: ``` protocolVersion = 1 packetID = 0102030405060708090a0b0c0d0e0f10 destinationToken = a1a2a3a4a5a6a7a8a9aaabacadaeafb0 creationBucket = 2934496 (0x002cc6e0) expiresAfter = 144 (0x90) transitPolicy = 0 (local only) payloadLength = 272 (0x0110) fragmentIndex = 0 fragmentCount = 1 totalLength = 272 (0x00000110) ``` produces the AAD: ``` 01 0102030405060708090a0b0c0d0e0f10 a1a2a3a4a5a6a7a8a9aaabacadaeafb0 002cc6e0 90 00 0110 00 01 00000110 ``` = `010102030405060708090a0b0c0d0e0f10a1a2a3a4a5a6a7a8a9aaabacadaeafb0002cc6e090000110000100000110` 47 bytes. Note `hopLimit` appears nowhere in it. *(Both values above were machine-computed, not written by hand — the first draft of this example had an arithmetic error in `creationBucket` and a dropped byte in the concatenation. Every vector in `vectors/` is generated, never transcribed.)* --- --- ## 4. Identity, secrets and token derivation ### 4.1 Primitives — CryptoSuite v1 | Purpose | Algorithm | |---|---| | Identity signing | Ed25519 | | Key agreement | X25519 | | Key derivation | HKDF-SHA256 | | Token derivation | HMAC-SHA256, truncated | | AEAD | ChaCha20-Poly1305, 96-bit nonce, 128-bit tag | | Hash | SHA-256 | No primitive outside this table appears anywhere in CryptoSuite v1's compositions; ML-KEM-768 (§4.9) is the one addition, in the v2 pairing and in the ratchet's per-session mix. Never invent cryptography (`SPEC-ORIGINAL` §11). A future CryptoSuite v2 replaces this table wholesale; it does not add alternatives to it, because negotiable cipher suites are a downgrade-attack surface. ### 4.2 Pairing output A completed Handshake v1 (§6.5) leaves both parties holding: ``` sharedSecret 32 bytes X25519(myEphemeralPriv, theirEphemeralPub) pairingSalt 32 bytes SHA-256(idPubLow ‖ idPubHigh ‖ pairingNonce) generation uint32 0 at first pairing, +1 on each re-pair idPubLow 32 bytes the lexicographically smaller of the two Ed25519 identity keys idPubHigh 32 bytes the lexicographically larger ``` `idPubLow` / `idPubHigh` give both sides an identical, canonical ordering of the pair without either having to be designated "initiator." This ordering is what makes §4.4's direction byte work, and it is also what lets both sides of §6.5's handshake build a byte-identical signed transcript without first agreeing a role. > **This section used to point at §6.2, which does not define a handshake.** §6.2 is the encounter > sequence and contains no pairing step. The exchange that actually produces the four values above is > §6.5, added later; until it existed, both platform apps filled the gap with a placeholder that set > `sharedSecret = idPubLow ‖ idPubHigh` — the two public keys, which travel in the clear in the pairing > code. A specification that names an output without defining the thing that produces it is a defect in > this document, and this is what one costs. ### 4.3 Routing secret ``` routingSecret = HKDF-SHA256( ikm = sharedSecret, salt = pairingSalt, info = "mesh/routing-v1" ‖ generation (uint32 big-endian) ) → 32 bytes ``` Bumping `generation` on re-pairing invalidates every previously derived token at once (`DECISIONS.md` C5), while conversation history — keyed separately — survives. Deleting a contact destroys `routingSecret`, after which anything still in flight to that contact is permanently undecryptable, including by us. ### 4.4 Presence and destination tokens Two tokens, derived from the same secret under **different labels**, so that no party can link a presence beacon to an envelope in flight (`DECISIONS.md` C3). ``` epoch = floor(unixTime / EPOCH_SECONDS) [policy] default 600 dir(P) = 0x00 if P's identity key is idPubLow 0x01 if P's identity key is idPubHigh presenceToken(P, epoch) = HMAC-SHA256(routingSecret, "mesh/presence-v1" ‖ dir(P) ‖ epoch)[0..16] destinationToken(P, epoch) = HMAC-SHA256(routingSecret, "mesh/destination-v1" ‖ dir(P) ‖ epoch)[0..16] ``` `epoch` is encoded as uint64 big-endian. Both tokens are the **first 16 bytes** of the HMAC output. 128 bits is ample against guessing and keeps the Envelope small. **The direction byte is not optional.** Without it both parties would derive the *same* presence token from a shared secret, and a relay hearing the same token emitted by two different devices would learn immediately that those two devices are a pair. `dir(P)` identifies the party the token *belongs to*: Carol beacons with `dir(Carol)`, and Alice computes Carol's expected token using `dir(Carol)`. An envelope addressed to Carol carries `destinationToken(Carol, epoch)`. **Consecutive tokens are unlinkable.** Distinct epochs produce independent HMAC outputs; an observer sees uncorrelated 16-byte values every ten minutes (`SPEC-REVISION` §1.7). ### 4.5 Message key Token derivation and content encryption MUST use **independent** key material. `routingSecret` is handled by relays' worth of machinery — it is the input to values that appear in the clear on every packet — and it must not be recoverable from, or a step toward, the key that protects plaintext. ``` messageKey = HKDF-SHA256( ikm = sharedSecret, salt = pairingSalt, info = "mesh/message-v1" ‖ generation (uint32 big-endian) ) → 32 bytes ``` Derived from `sharedSecret` directly, in parallel with `routingSecret` (§4.3) rather than from it. Compromise of a routing secret therefore discloses routing metadata only, and never content. `generation` participates identically, so re-pairing rotates both at once (`DECISIONS.md` C5). **AEAD binding.** `ChaCha20-Poly1305(key = messageKey, nonce = envelope.nonce, aad = §3 AAD)`. The nonce is carried in the Envelope and MUST be unique per key; a receiver MUST reject a `(key, nonce)` pair it has already accepted. **This is CryptoSuite v1's static composition, and on its own it has no forward secrecy.** §4.5a layers the Double Ratchet inside it for every contact both of whose phones advertise it; the static key remains the outer layer, which is what keeps the ratchet's headers away from relays. *(This paragraph used to say a ratchet would replace the derivation wholesale in a later suite. `J1559` chose to layer it instead, for the reason just given, and because every existing pairing keeps working without a new handshake.)* ### 4.5a Forward secrecy — the Double Ratchet (`J1559`, CryptoSuite v1) §4.5's `messageKey` is static for a pairing's generation: whoever later obtains it can read every message ever sealed under it. This section adds, **inside** the envelope, an independently developed Double Ratchet design based on Signal's published specification (*The Double Ratchet Algorithm*, Perrin and Marlinspike, Revision 4, 2025-11-04; section numbers here are revision 4's), with CHANNEL-specific session establishment, recovery and post-quantum extensions. It contains no Signal code. Stealing a phone's state today does not open messages it has already read, and the sessions in a ratchet state stolen once stop working for the thief after one round trip **against an attacker who only reads**. A phone's state also holds the pairing key, though, so the same passive thief reads the opener's first chain of every LATER session, until the opener's first DH step on it, for as long as the pairing lasts ("What it does not cover, stated", below). Implementation: `mesh-core-rs/src/ratchet.rs`, the only one. Where it departs from the specification, and why, is tabulated in `designs/J3812-double-ratchet-deviation-table.md`. > **Not against one who sends -- measured 27 September 2026 (audit round 2, `J1633`).** A new ratchet > session is accepted from anybody holding the pairing's `messageKey`, because that is how a > restored phone recovers. So a holder of the pairing key alone can START a session, and the > receiver then seals its replies into that session: one forged message takes over one direction > of the conversation until a new session replaces it. The sentence above held only for a passive > thief. Closing it needs the session start authenticated by something a thief of the pairing key > does not hold -- a decision put to the owner, and a staged wire change. > > **Being closed: signed starts (`J1633`, the owner's go-ahead 30 September 2026).** Header flag > `0x02` (`FLAG_SIGNED`) says a 64-byte Ed25519 signature by the sender's IDENTITY key follows the > header, before the nonce, over > > ``` > "channel/ratchet-start-v2\0" ‖ session id (16) ‖ sender's ratchet public in this header (32) > ‖ sender identity (32) ‖ recipient identity (32) > ‖ SHA-256(header 58 ‖ nonce 12 ‖ ciphertext and tag) (32) > ``` > > The last field is the message itself (`J1837`, outside review N4): version 1 of the statement > stopped at the identities, which made the signature the same bytes for every message on the > opener's first chain -- and that chain's keys derive from the pairing key, so a holder of it > could seal a forgery there and copy a genuine signature onto it. Binding the sealed message makes > a signature good for exactly one ciphertext. No build ever signed with version 1 (stage 2 has > been off everywhere), so there is nothing to keep reading. > > The flag is in the header and the header is in the AEAD's associated data, so it can be neither > stripped nor added. The signature itself is not in the associated data: it authenticates the > ratchet key it names and the one sealed message it was made over, and changing it can only make > the message fail. > > **Which messages are signed (stage 2).** A phone signs every message it seals on a sending chain > that the pairing key alone keys, or whose ratchet key will make the other phone's FIRST step -- > because a holder of the pairing key can produce exactly those, as either phone: > > - **the initiator: its whole first sending chain**, which is exactly the messages that carry > `INITIAL`. Forging one is OPENING a session as the initiator; > - **the responder: its whole first sending chain** -- the chain the step that created the session > gives it -- however long it lasts. Whichever of those messages reaches the initiator first makes > the initiator's first step, so every one of them must be signed, or a reordered burst strands. > Forging one is ANSWERING an opening as the responder with a key of the forger's own, after which > the initiator's next chain is one the forger can derive (the external review of stage 1). > > A phone stops signing on a session at its next DH step: the initiator at its first, the responder > at its second. Every chain after that comes from a DH between two keys made fresh on the two phones, > neither derivable from the pairing key, so a message on it cannot be forged by a thief of the > pairing key at all, signed or not. > > **Authenticated sessions.** A session is *authenticated* on a phone once the other phone's > establishing message for it -- the opening that created it here, or the reply that made its first > step -- carried a signature that verified against the other phone's identity key. The book keeps > this per session (stored state, below). > > - **Stage 1 (built 30 Sep 2026):** every reader accepts the flag on any message and checks a > signature whenever one is present, refusing a wrong one before anything is kept. Unsigned > starts are still accepted, because no build signs yet. > - **Stage 2 (`SIGN_SESSION_STARTS`, ON since 8 Oct 2026):** writers sign as > above. > - **Stage 3 (`REQUIRE_SIGNED_SESSION_STARTS`, ON since 12 Oct 2026, the owner: builds before 2.950 are not waited for):** an unsigned > opening or first step is refused, and **sending never moves to a session that is not > authenticated** (the sending rule, below). Sessions accepted unsigned before stage 3 stay in the > book and are read, and are **no longer sent on**: when the session a phone would send on is not > authenticated -- other than its own session not yet answered -- its next message begins a new, > signed session. And **a contact that has spoken through the ratchet is no longer heard without > it** (below). > - **Per contact, before the global stages (`J1633b`, 3 Oct 2026; nobody waits for every phone).** > A phone signs its session starts to a contact whose card carries capability **`dss`** ("reads > signed session starts", advertised from 2.951), or to one it has already heard signing (a build > that signs reads). And once a signed start from a contact has opened, the book latches > `heard_signed` (book version 4) and stage 3's two refusals apply **to that contact**: an unsigned > opening or first step from it is refused -- the pairing-key thief's start -- and sending never > moves to an unauthenticated session with it. Deliberately left to the global stage 3: the > static-message refusal and the ratchet kill switch, so no contact is silenced who turned its > ratchet off. A contact never heard signing keeps today's rules exactly. > > **Static messages from a contact that ratchets (the external review, 1 October 2026).** §4.5's static > composition rests on the pairing key alone, which never changes. So whoever holds it can write > "from" a contact -- any payload type, device lists (§5.8) included -- for as long as the pairing > lasts, however far the ratchet has moved. Each phone therefore records, per contact identity and > kept in that contact's book, that the contact has spoken through the ratchet; **at stage 3 a static > message from such a contact is refused**, and the host can no longer switch ratcheting off for it > (only a new pairing resets it); a phone that loads such a book sends to that contact ratcheted > without waiting for its host. The local-network proof (`J1571`) is sealed static whatever the > switch says and is read without `receive`, so it is unaffected. A linked device is its own contact > identity with its own sessions, so it is judged by its own ratchet, not its phone's. Every delivery > also says whether it came through the ratchet. **Before stage 3 that bit carries no authentication > meaning** (`J1837`, outside review R1): a holder of the pairing key can open an unsigned session, > and every message on it is delivered as ratcheted. A host MUST NOT accept a device list, a card or > anything else security-sensitive on the strength of it until stage 3 is on. At stage 3 it means the > message was opened on a session whose establishing message carried a verified signature, on a > chain the pairing key cannot derive -- that is, the session is `authenticated` (N6). A session > accepted unsigned BEFORE stage 3 stays readable past its first step and is never sent on, and a > delivery on it is reported NOT ratcheted at stage 3; its opener's first chain is refused unsigned > at stage 3 like any other. > > **What it does not cover, stated.** The signature binds the ratchet key and the sealed message; it > does not make the opener's first chain unreadable to a holder of the pairing key. Until stage > 3 is on, a holder of the pairing key can **read** the opener's first chain (its keys are derived > from the pairing key), can **forge** unsigned messages on it "from" the opener and spend the real > ones' keys, can **take over** either phone's sending by opening an unsigned session, and can > **send static messages as either phone, indefinitely**, as the paragraph above describes. The > record that would refuse static messages is kept from now, and the refusal switches on with stage > 3. At stage 3 (`J1837`, R2) a receiver also refuses an UNSIGNED message on the opener's first > chain -- stage 2 writers sign that whole chain, each message over its own ciphertext (N4), so a > genuine signature cannot be copied onto a forgery -- and the forgery window closes with the > takeover; what remains is that the thief can still READ that chain until the opener's first DH > step -- on every session, including each new one that a restart (`J1842`, `J2535`), a restore or > crossed openings begin, for as long as the pairing lasts. A session decoded from a version-1 book has no opener key (N5); at import the key is > recovered where the book can prove it -- the opener's first receiving chain is derived from the > pairing key and the session id, so a session still receiving on that derivation for the key the > other side uses has its opener key put back, whether or not this phone has replied; once the > opener has stepped nothing is derivable and nothing is guessed. A > backup restore drops the books, and with them the static-refusal record -- so (R4) the host keeps > "has spoken through the ratchet" on the contact record as well, which a backup carries, and > re-asserts it into the core after a restore (`set_ratchet_latched`, monotonic); a book imported > over a slot that had already heard the contact keeps the latch. A phone restored from a backup > made before the contact ever ratcheted is still open until the contact's next ratcheted message. **Primitives** — §4.1's table, plus ML-KEM-768 for the one post-quantum mix per session (`J1901` phase 2, §4.9.5); KDF chains as the specification's §7.2 recommends, with application-specific labels. X25519 for the DH ratchet; `KDF_RK(rk, dh) = HKDF-SHA256(salt = rk, ikm = dh, info = "channel/ratchet-v1/kdf-rk")` → 64 bytes (new root ‖ chain); `KDF_CK(ck)`: message key `HMAC-SHA256(ck, 0x01)`, next chain key `HMAC-SHA256(ck, 0x02)`; message AEAD ChaCha20-Poly1305 under `HKDF-SHA256(salt = ∅, ikm = messageKey_n, info = "channel/ratchet-v1/message-key")` with a **random 12-byte nonce carried beside the header**. A message key is used once, so the nonce is not needed for uniqueness; it is random so that a state rolled back by a restore still never repeats a (key, nonce) pair. **Sessions.** Either phone may start one. The initiator picks a random 16-byte `sessionId` and: ``` root0 = HKDF-SHA256(salt = sessionId, ikm = pairing messageKey (§4.5), info = "channel/ratchet-v1/root") responderSecret0 = HKDF-SHA256(salt = sessionId, ikm = pairing messageKey, info = "channel/ratchet-v1/responder-key") initiator: DHs = fresh key pair; DHr = X25519-public(responderSecret0); (RK, CKs) = KDF_RK(root0, DH(DHs, DHr)) responder: created on receiving an INITIAL-flagged message for an unknown sessionId; DHs = responderSecret0; RK = root0; then the ordinary receive step ``` Both phones can compute `responderSecret0`, and so can anyone who obtains the pairing key, so the opener's **first chain of every session is only as secret as the pairing**. This is weaker than X3DH's first messages: there the responder's first key is a signed prekey whose private half only the responder holds, while here it is derivable from the pairing key. What the two share is only that the responder has not yet contributed a fresh DH key. From the first reply on every chain comes from X25519 keys generated fresh on one phone. Each phone keeps at most **6** sessions per contact. It remembers the last **256** retired `sessionId`s so a replayed initial message cannot recreate one (the envelope's own ±1 epoch window limits a replay to thirty minutes, and late mail, §4.6, is accepted only while the opened-envelope table still remembers every envelope opened since it was sealed). Only a message carrying the INITIAL flag may create a session. **Where a phone sends -- one rule (`J1559`, `J1633`, `J1826a`).** A phone sends on the session it most recently **received** on, as Signal does, so a phone that lost its state and starts a new session is answered on it at once -- where "most recently" is by the SENDER's clock, the payload's `sentAt` (§5.1), because arrival order is exactly what a late or reordered envelope gets wrong. Each session keeps the newest `sentAt` received on it (`any`), and the newest received on a chain the pairing key cannot derive (`trusted`; every chain but the opener's first, on the responder's side). Receiving a message that opens on session X, with clock t, moves sending there from the current sending session Y when (with no Y, or X = Y, it does): 1. **Y has a `trusted` clock:** t is not earlier than it. A session start sealed before the contact's latest message on Y is stale -- the contact may have lost that session in a restore since (`J1826a`), and answering on it would send into a session nobody holds. It is still read. A late message on an older session is older than Y's evidence and moves nothing. 2. **Y has none yet:** t is not earlier than Y's `any`, **and** X was created on this phone no earlier than Y **or** the message is itself on a chain the pairing key cannot derive. The first keeps a stale start from replacing a session whose opener wrote later; the second brings a phone back from a stale start it moved to before the contact's answer on its own session had arrived. 3. **At stage 3, X is authenticated** -- in every case. Equal clocks move. A message whose clock cannot be read moves sending by the order this phone created the sessions in. A phone starts a new session only when it has nothing to send on (or, at stage 3, when what it would send on is not authenticated). **A sender's clock is held to this phone's own plus twenty minutes** (two epochs) before any of this reads it: an envelope from a sender further ahead would not open (§4.6 accepts one epoch either side), so no honest clock is changed. A contact whose clock went backwards across a restore is answered on its new session once its clock passes its last message on the old one. A thief of the pairing key who can inject a message on an opener's first chain can give it a future clock; once that session has a `trusted` clock this moves nothing (rule 1 reads only `trusted`), and before then it holds sending where it is (rule 2) for at most twenty minutes past the moment it arrived -- a delay, never a diversion onto a chain the thief can read. The same thief can, with a well-timed message on an older session it can still forge on, move sending there until the contact's next message moves it back (the external review of this rule, 1 October 2026, C2) -- intermittent loss while the attack lasts, never a readable chain. A version-1 book has no opener keys, so its clocks all count as `trusted` until its sessions are replaced; the twenty-minute ceiling bounds what that can cost. **Not healed by that rule, measured (`J1826a`):** a session start the contact sealed BEFORE this phone's own restore, opened AFTER it. The restored book is empty, so there is no Y to compare with; the phone answers on a session the contact has moved past, and both directions fail until a re-pair. **Wire** — the ratchet's output, which becomes the plaintext of the envelope's own AEAD (§4.5): ``` prefix = version 0x01 ‖ flags ‖ sessionId 16 ‖ DHs public 32 ‖ PN uint32 BE ‖ N uint32 BE = 58 bytes header = prefix ‖ [ek 1184, only when PQ_OFFER] ‖ [ct 1088, only when PQ_CT] (58, 1242, 1146 or 2330 bytes) flags : 0x01 INITIAL, 0x02 SIGNED, 0x04 PQ_OFFER, 0x08 PQ_CT (J1901 phase 2); every other bit MUST be zero (the message is refused) message = header ‖ [signature 64, only when SIGNED] ‖ nonce 12 ‖ ChaCha20-Poly1305(plaintext) ‖ tag 16 AEAD key = HKDF-SHA256(salt = ∅, ikm = messageKey_N, info = "channel/ratchet-v1/message-key") AEAD aad = the WHOLE header, extensions included ‖ "channel/ratchet-v1/ad" ‖ sender identity 32 ‖ recipient identity 32 ‖ packetId 16 signature = Ed25519(sender identity key, "channel/ratchet-start-v2\0" ‖ sessionId 16 ‖ DHs public 32 ‖ sender identity 32 ‖ recipient identity 32 ‖ SHA-256(whole header ‖ nonce 12 ‖ ciphertext ‖ tag) 32) ``` `J3748` (core review, 1 November 2026): this block named only the 58-byte prefix and two flags until then, although `ratchet.rs` has carried the J1901 phase 2 extensions since October. `ek` is the sender's ML-KEM-768 encapsulation key, `ct` a ciphertext for the peer's offered `ek` (`designs/J1901-phase2.md`); the order is `ek` then `ct`, and a reader takes each length from its flag, never from the message. Both the AEAD and the signed digest cover the extensions. The associated data binds the message to its envelope: the sender, the recipient, and the envelope's `packetId` (§3), none of which is carried inside the ratchet message. The signature is between the header and the nonce and outside the AEAD; `vectors/12-ratchet-signed.json` has one signed opening, byte for byte, and `vectors/13-ratchet-kdf-and-trace.json` each derivation above on its own plus an unsigned trace with out-of-order delivery, a key kept at a DH step, and PN on both sides (`J1833`). **The DH step in two halves (`J3765` stage 1).** A message bringing a new ratchet key `DHr'` runs only the receive half when it is opened: `(RK, CKr) = KDF_RK(RK, DH(DHs, DHr'))`, and the ML-KEM decapsulation if it carries a ciphertext. Opening draws no randomness, so every copy of a profile that opens the same messages ends in the same state. The send half is owed, and runs at the next encrypt (or reserve): a fresh `DHs'` is drawn ahead of that encrypt's nonce, `(RK, CKs) = KDF_RK(RK, DH(DHs', DHr'))`, and the encapsulation to the peer's offer kept from the opening. While a step is owed, a second new ratchet key is refused, since an honest peer cannot send one before it has heard `DHs'`. The wire, the derivations and their order are what they were; only when `DHs'` is drawn moved. `vectors/70-ratchet-two-copies.json` has two copies opening the same trace and agreeing. A relay sees none of this: it is inside the envelope's existing encryption, so a ratchet key or a counter can never link two envelopes. Someone who later steals the pairing secret can read the headers of recorded envelopes. What else they can read depends on how far the session has ratcheted: messages sent after the first DH step has completed stay unreadable to them, but the opener's first chain is derived from the pairing key and so stays readable to a holder of it (see "What it does not cover, stated" above). Confidentiality after the first step, forward secrecy and recovery after a compromise are separate properties and are claimed separately. **Out of order, bounded.** The mailbox and the radios are parallel routes, so a message may overtake many older ones. A receiver derives and keeps the skipped message keys, **at most 2,000 ahead in one chain** — checked before a single key is derived, because a header is hostile input — and **at most 4,000 kept per contact**, oldest dropped first. A kept key is deleted when used. When a new ratchet key arrives and the old chain is further behind than 2,000, its missing messages are **given up** and the step still happens; refusing the step would strand every later message on that session. **State changes only on success,** on both sides. A receiver works on a copy and keeps it only if the message authenticated; a sender likewise, so a seal that fails (the random source refusing) leaves no gap in the chain. A forged message, a replay, a counter out of bounds or a low-order ratchet key (all-zero X25519 output, refused) leaves the state exactly as it was. **Stored state** is an opaque, versioned byte string (`Book::encode`) the app keeps per contact, sealed at rest like the rest of its store. It is **excluded from backups**: a restored phone begins new sessions rather than resuming stale ones, and the other phone heals onto them as above. **Version 2** (`J1633`) adds, per session, whether its current sending chain is signed, whether it is authenticated, the opener's first ratchet key (on a session this phone responded to) and the two newest sender clocks (`trusted`, `any`); and, for the whole book, whether the contact has spoken through the ratchet. A version-1 book still decodes: its sessions read as not authenticated, with no clocks, no opener key (so every chain's clock is `trusted`), and signing on until each session's next DH step -- signing a message that did not need it costs 64 bytes, while leaving a responder's first chain unsigned would have it refused at stage 3 -- and the contact counts as having spoken through the ratchet when any session has a receiving chain, which only its ratcheted message makes. Every count is bounded before anything is allocated, as in version 1. **A rolled-back book is retired, not resumed (`J1837`, outside review M2).** The book's logical clock (`Book::clock`, advanced by every key-consuming operation: begin, respond, encrypt, decrypt) is its generation. The app records it on the contact record each time it stores the book -- the record is in every backup, the book in none -- and hands it back at import (`Node::ratchet_import_checked`). A book whose clock is below the record is a restored or stale copy, and every session in it is retired before it can re-seal under a message key the newer copy already spent or re-open a message already delivered: the next send begins a fresh session, which the contact heals onto as above, and a replay on a retired session is refused. The latch survives, and the clock is raised to the record's so the next export agrees with it. A book stored by a failed save and a relaunch is the case this guards; a phone restored from a backup made before any book existed has no record and no book, and begins afresh as before. **What the record carries, and what it does not close (`J1837`, N12/N13).** The clock alone retires only the sessions the stale copy knew, so the app records the live session ids beside the clock (`Node::ratchet_session_ids`; as the union of every read, newest first and bounded, since a book prunes past six live sessions) and hands them back after a rollback, or when the record is present and no book is (`Node::ratchet_retire_sessions`): a replay of the opening of a session the newer copy created after the copy was made is then refused instead of re-creating it. An attachment key already held when a book is upgraded from version 1 or 2 reads as unauthenticated, since the older book cannot say which session carried it. **Healing a double break (`J1842`).** When this phone's own-mailbox envelopes from a keyed contact open under no key, the host stops SENDING on the current session for that contact (`Node::ratchet_restart_sending`), keeping every session readable; the next message is then an opening, which the contact can read with the pairing key alone, and `received_on` moves the contact's sending onto it as the newest session it has heard. Two books that each seal on a session the other lacks -- a lost book on one side, a restored older copy on the other -- heal without a re-pair. Bounded as the card re-send it accompanies: own mailbox only, keyed contacts only, once an hour per contact. **A ratcheting contact who writes static (`J2535`).** The same restart, reached by a second signal: an envelope from a contact's OWN session that opens STATIC (not through the ratchet, and not a `LinkRenewal` carrier), from a contact this phone has heard through the ratchet before (the record's latch), while this phone seals ratcheted to them. That contact holds no book for us -- it lost it, and the card that would switch its ratchet on cannot open for it -- so every message on our session is refused there, while its static ones open here; nothing else on either side ever moves (a static message does not touch our book, nothing fails to open here, and its own `J1842` restart has no slot). The opening the restart produces is a RATCHET message, not static, so it is read with the pairing key alone and is not subject to stage 3's static refusal; the contact keeps a book from it and answers through it. Once an hour per contact, shared with `J1842`'s clock. At stage 3 a latched contact's static never opens, and `J1842` covers the same state. A kept message key of a session whose opener key the book does not hold (one this phone began, or one upgraded from version 1 after the opener stepped) is, when about to be spent unsigned at stage 3, re-derived from the pairing key and the session id exactly as a forger would derive the opener's first chain -- `KDF_RK(root0, DH(responder, opener))` walked to the key's index -- and refused if it matches; a key from any other chain mixes a random secret and cannot match, so it is spent as before. **Version 3** of the stored book adds, after the latch, the ids of received attachment keys whose chunk 0 came on a session that was not established under a verified signature (N11), so a later chunk reports as its chunk 0 did; a version-2 book reads every held key as authenticated. **Version 4** (`J1633b`) adds, for the whole book, `heard_signed`: a session start from this contact has opened under a verified signature (the per-contact stage-3 latch above); older books read false. **Version 5** (`J1901` phase 2) adds, per session, the seed of this phone's offered ML-KEM-768 key pair, the other phone's offered `ek` not yet answered, the ciphertext the current sending chain carries, and whether the session has mixed; and, for the whole book, `heard_pq` (some session with this contact has mixed), a record for reports rather than a switch. **Version 6** (`J3765` stage 1) adds, per session, whether a send half is owed and the peer `ek` that send half will encapsulate to; every older book reads as owing nothing. `Book::decode` reads versions 1 to 6 and `Book::encode` writes 6. **Reserved slots (`J1964b`).** `Book::reserve` (`Node::ratchet_reserve`) sets aside 1 to 8 sending indexes on the session the book sends on, so that a process holding no book (the iOS notification extension) can seal one message per index, a delivered receipt. A slot is that index's frozen header plus its message key and the book's clock, nothing else; it seals with a fresh random nonce, no signature and no post-quantum fields, and a stored slot whose header carries any flag is refused. The chain moves past the reserved indexes, so an unused slot looks to the receiver like a lost message. Reserving completes an owed send half first, and is refused, leaving the book unchanged, when nothing is sending, or the sending session is still unanswered (`INITIAL`), or its sending chain must be signed, or it has no receiving chain, or its chain carries a post-quantum ciphertext. The host MUST save the book before it stores the slots: the reverse order is the one way an index could be used twice. Until used, up to 8 message keys live outside the book, wherever the host stores the slots; the host is expected to drop a slot whose session is no longer the one the book sends on (`Book::reserved_slot_is_current` is the check). **Not everything a phone seals is a message.** The local-network handshake (§7, `LANPeerAuthenticator`) seals a fresh random nonce to every contact on every connection, to prove the sender holds that contact's key. It is sealed under §4.5's static composition, **never through the ratchet** (`J1571`): ratcheted, each handshake would advance the chain to every contact by a message none of them receives (most of them are not on that network), leave each a gap of skipped keys, and change every stored book. The proof carries nothing to protect, and a static seal proves possession of the key as well. The ratchet's switch for that contact is off for that one seal only; the next message sets it by the ordinary rule. **The proof answers this connection's key agreement (`J2517a`, hello v2; replaces `J1572`'s challenge).** Every local-network and Wi-Fi Direct connection begins with a fresh X25519 key agreement, the proof signs its transcript, and every frame after it is sealed under the agreed key -- so a proof belongs to one connection and the connection belongs to whoever made the proof. *Threat model.* A stranger M on the same network, able to open sockets to any phone and to read, drop, delay and rewrite everything on its own sockets; every phone answers any socket's hello. Under `J1572` the challenge was plain bytes, so M passed Bob's challenge to Alice's phone on a socket of its own, passed her answer back, and Bob bound **M's socket** to Alice (`J2517a`): M then received Alice's mail, which it cannot read, and dropped it, while Bob's newest-proved rule (`HelloBindings.choose`) preferred M's socket to Alice's own. Out of scope: an on-path party that carries a connection's bytes and can stop carrying them -- any router can, and so can anyone on the LAN who spoofs ARP. What this closes is M being **bound with traffic of its own**. *The exchange* (`mesh-core-rs` `lan_hello`, the only implementation; vector `33-lan-hello`): 1. **Hello key** (frame kind `5`): each side draws an ephemeral X25519 key pair for this connection only and sends the 32-byte public key, first, in the clear. Only the first is read; any other length drops the connection. A key equal to this side's own (reflection) or one whose shared secret is all zero (a low-order point) is refused and the connection dropped. 2. **Transcript and keys**, the same on both sides because the two keys are sorted (no initiator or responder role -- both phones may dial each other): ``` e_lo, e_hi = the two public keys, lowest first (bytewise) th = SHA-256("channel/lan-hello-v2/transcript" ‖ e_lo ‖ e_hi) okm = HKDF-SHA256(salt = th, ikm = X25519(mine, theirs), info = "channel/lan-hello-v2/frame-keys", L = 64) key sent with by the holder of e_lo = okm[0..32]; by the holder of e_hi = okm[32..64] ``` 3. **Proof**: one per contact, sealed exactly as before (§4.5's static composition, never the ratchet, `J1571`), whose plaintext is ``` "\0chm-lan-auth-v1\0" ‖ "t:" ‖ hex(th) (exactly 83 bytes) ``` and a verifier accepts a proof only when it opens under the key of the contact it names (`Node::probe_proof`) and the plaintext is exactly that, `th` being **this connection's** (constant-time compare). The v1 marker stays the prefix, so every message store keeps dropping it from message traffic. Proofs are answered at most thirty a minute across all connections, once per connection, as before -- each answer is one seal per contact. 4. **Every frame after the hello key is sealed** (frame kind `6`): ``` payload = ChaCha20-Poly1305(sendKey, nonce = 0x00000000 ‖ u64be(counter), aad = "channel/lan-hello-v2/frame", innerKind ‖ innerPayload) ``` with one counter per direction from zero, advanced by one per frame. The proof (inner kind `1`), envelopes (`2`) and encounter frames (`3`) travel ONLY this way; a cleartext frame of any kind after the hello key is ignored. A sealed frame that does not open -- tampered, injected, replayed, reordered, or one before it dropped -- ends the connection and every later call on its session refuses, so a desynchronised connection cannot be nursed along. The counter nonce is the standard construction for a key used in one direction of one connection (Noise's transport phase): it never repeats under a key, and `J898k`'s "bind the nonce to the complete input" rule is for DERIVED nonces under a long-lived key, which this is not. A sealed frame is at most `maxFrameBytes + 17` (the inner kind and the tag), so the inner limit is unchanged. *Why the relay now fails.* M has a socket to Bob and one to Alice. If M sends its own hello key to each, the two transcripts differ (each contains one of M's keys and only one of theirs), so Alice's proof -- which M can carry, re-sealed under its own frame key with Alice -- answers the wrong transcript and Bob refuses it. To make the transcripts equal M must send Alice's key to Bob and Bob's to Alice, and then M knows neither private half and cannot derive the frame keys: it cannot read a frame, write one, or drop one without the next failing to open, which ends the connection. At that point the socket is a pipe between Alice and Bob -- the out-of-scope router above -- and not a peer of M's. **Reflection still fails** two ways: a reflected hello key is refused, and a seal TO a contact does not open as FROM that contact. *What stays.* A pipe that stops carrying stalls rather than lies, which is why `J2517`'s tick rule stays: a local-network write earns no tick until the receipt, and the 8-second rescue moves an unanswered one to the Internet. *Compatibility: a clean break* (the owner, 8 Oct 2026: backward compatible "when you can be ... without much problem", and never waiting on testers). Speaking both versions would let M strip the hello key and force the old, relayable hello -- a downgrade -- unless the old one bound nobody, and then it buys nothing. So a build with hello v2 sends no challenge (kind `4`), ignores one, and accepts only transcript proofs; with a build before it the two phones have no local-network or Wi-Fi Direct link and use Bluetooth and the Internet until both are updated. ### 4.5b Forward secrecy for large attachments (`J1559` stage 4) A streamed attachment's chunks (§5.6a) must re-seal byte for byte, and a ratchet spends a fresh key on every seal -- so the chunks cannot each go through §4.5a. Instead, for a contact who is sent ratcheted: - **Chunk 0 is ratcheted** and carries the attachment's own key ahead of its payload. Inside the ratchet message: `0x02 ‖ attachmentId 16 ‖ attachmentKey 32 ‖ padded payload`. - **Every later chunk is sealed under that key**, and the result is what the envelope's AEAD seals: ``` 0x01 ‖ attachmentId 16 ‖ nonce 12 ‖ ChaCha20-Poly1305(attachmentKey, nonce, aad = "channel/attachment-v1/aad" ‖ 0x01 ‖ attachmentId, padded payload) nonce = HMAC-SHA256(attachmentKey, "channel/attachment-v1/nonce" ‖ padded payload)[0..12] ``` The key is 32 random bytes, made the first time any of the attachment's chunks is sealed and kept in the sender's ratchet book, so a re-seal after a relaunch uses the same one. **The nonce is a function of the complete AEAD input** -- the plaintext, and an AAD that is fixed for the key, because the key belongs to one attachment and the AAD names it -- as §5.6a's is: identical bytes re-seal identically, and two different plaintexts -- the sender's clock moves between re-seals (`J898k`) -- can never share a nonce. A receiver recomputes it and refuses a chunk whose nonce does not match. A receiver believes a carried key **only when the ratchet message's payload is chunk 0 of that same attachment**, and keeps nothing -- not the advanced ratchet, not the key, not the switch to sending ratcheted -- unless the whole message is good. It keeps received keys apart from the keys of attachments it is sending, so a contact cannot replace a key this phone is using (at most 256 of each per contact, least recently used dropped, and a dropped received id is remembered). A second chunk 0 naming a different key for an attachment already keyed is refused. **Chunk 0 takes a fresh packet id on every seal**, because it is ratcheted and no two seals of it are the same message; a derived id would make a retry look like a duplicate of a first copy that failed to open. **A later chunk that arrives before chunk 0 cannot open yet.** It is refused and, for this cause only -- not for a key that was dropped -- the receiver forgets having seen the packet, so the sender's retransmission, byte-identical by design, opens once the key has arrived. A contact who is not sent ratcheted gets exactly what every earlier build sealed. *This section's first version had five defects, found by an adversarial review the same day and each fixed with a test that reproduces it.* > **Design note for a later version -- not built (`J1833`, outside review I2).** One key does two jobs > here: `attachmentKey` is the HMAC key for the nonce and the ChaCha20-Poly1305 key for the seal. > That is not exploitable with these two primitives, but §5.6a separates the same two jobs with > HKDF, and this layer should match it. The next version of this layer would expand two keys from > the carried one -- `sealKey = HKDF-Expand(attachmentKey, "channel/attachment-v2/seal", 32)` and > `nonceKey = HKDF-Expand(attachmentKey, "channel/attachment-v2/nonce", 32)` -- under a new marker > byte, so a receiver tells the versions apart before it opens anything. The same version would also > bind this layer's AAD into its nonce, as §5.6a now does: today the nonce covers the plaintext only, > which is safe solely because the AAD is fixed for the key (the key belongs to one attachment, and > the AAD is that attachment's id) -- a variable field added to it would reopen M1 here. Unlike §5.6a's nonce, this > one IS recomputed and checked by the receiver, so the change is a wire change: readers first, > gated on the contact's capability, as every change of this kind here. ### 4.6 Epoch acceptance and clock skew A receiver MUST accept tokens for the **previous, current and next** epoch — a ±1 window. With the default 600-second epoch this tolerates just under 10 minutes of skew in either direction, and gives a token a maximum useful life of 30 minutes. Implementations MUST NOT depend on network time, which is unavailable by definition in the target environment. Device real-time clocks are the only source. A device whose clock has drifted more than one epoch will silently fail to be found; §7's diagnostics surface this rather than leaving it as a mystery. Precomputing three epochs for every contact is 3N HMAC operations per epoch — negligible at any plausible contact count. **Late mail: the envelope's own sealing epoch (`J1950`).** A destination token outside the window MAY still be accepted if it equals the receiver's destination token for the envelope's `creationBucket` (§3.2), under ALL of these conditions: 1. `creationBucket` lies in the past beyond the window: `creationBucket + 1 < nowEpoch`. A sealing epoch in the receiver's future beyond the window is never matched — a fast clock is the window's job. 2. `nowEpoch − creationBucket ≤ MAX_RELAY_LIFETIME` (144 buckets, one day), whatever `expiresAfter` the envelope claims; an expired envelope (§3.3) is refused before any match. 3. The receiver's opened-envelope table (§7.3), which remembers what it opened for `MAX_RELAY_LIFETIME`, **can answer for everything recorded since one epoch before `creationBucket`**: it was already recording then (a table that has recorded nothing vouches for nothing), and it has pushed no live entry recorded since then out to stay within `MAX_SEEN_ENTRIES` (judged by the earlier of the table's own latest time and the current one). The instant from which it can answer is stored with the table; a table stored before that existed answers only from when it was loaded. Otherwise the window alone decides. `creationBucket` is inside the AAD, so trusting it before the AEAD decides only which ONE extra token to derive; a false value fails to match or fails to open. Condition 3 is the reason this is safe: the ±1 window used to be a replay bound as well as a skew allowance (nothing older than thirty minutes matched), and late mail moves the whole of that job onto the opened table — so it is accepted only while the table can still answer for every envelope opened since it was sealed. Why it exists: §8's mailbox is addressed on a six-hour clock precisely so that mail deposited while a phone sleeps can be FOUND, and the relay deletes what a phone collects. Without this rule a phone that collected after an hour asleep found its mail, could not match it, and lost it. A node that carries mail for others (§7.7a) treats an envelope as its own — never to be carried — when its token matches at `creationBucket` under conditions 1 and 2, whatever the table remembers. **Replay is possible and accepted.** An observer can record and rebroadcast a presence token within its 30-minute window, making peers believe a contact is nearby. The cost is a wasted route query; delivery still requires the real holder to respond. Presence tokens are hints, never authorisation. ### 4.7 Service identifier ``` ChannelMessenger service UUID: FB985D30-F439-4BD2-90F8-6C1BA2A23394 Payload characteristic: F9BF4B77-F212-4B11-B04C-90CDE4B5CA5F ``` Protocol-level, not an application detail. A background BLE scan on iOS cannot use a wildcard — it must name the service UUIDs it is interested in — so every node has to look for this exact value. **Changing it partitions the network** into two populations that cannot see each other, which is why it is pinned here rather than left to each platform. It carries no information: it is a fixed random value, identical on every device, and reveals only that a device runs this protocol. That is already disclosed by participating at all (`THREAT-WALKTHROUGH.md` §2). ### 4.7a What travels on the payload characteristic (`J1779`) Below the packet layer, and never seen by it. A packet frame larger than one ATT write or notification is split into **chunks**, each with an 8-byte header: ``` transportPacketID 4 bytes, big-endian random per send; unrelated to §2's packetID fragmentIndex 2 bytes, big-endian fragmentCount 2 bytes, big-endian 1 ..= 4096 payload the rest ``` A receiver reassembles by (link, `transportPacketID`, `fragmentIndex`) and discards anything under 8 bytes unread. **Reassembled ack.** When a transport packet has reassembled and been handed on, the receiver writes exactly 5 bytes back on the same link — a notification from the peripheral side, a write without response from the central side: ``` 0xAC transportPacketID (4 bytes, big-endian, as in the chunk it answers) ``` It is distinguished from a chunk by its length (every chunk is at least 8 bytes), not by its first byte, which a random `transportPacketID` shares one time in 256. A 5-byte frame with any other first byte is discarded. A sender waits for the ack only from a peer whose contact card carries the capability `bak`, and treats none within 1.5 s of its last chunk being accepted as a failed send on this link. Builds without the capability discard the 5-byte frame as a too-short chunk. ### 4.7b The L2CAP data path (`J1771` (4), prototype, off by default) An alternative to §4.7a for **sealed envelopes only**, behind a switch that ships off on both platforms (`BLEL2CAP.isEnabled`, `BleL2cap.IS_ENABLED`). Discovery, PRESENCE, encounter frames, pairing frames and the reassembled ack stay on the payload characteristic. Delivery receipts and chunk-zero acknowledgements are sealed envelopes and ride the channel like any other, with their mechanisms unchanged; an envelope that arrives on the channel is not answered with a reassembled ack, and a sender on the channel does not wait for one. **The PSM.** A phone with the switch on publishes an unencrypted LE credit-based channel listener (iOS `publishL2CAPChannel(withEncryption: false)`; Android `listenUsingInsecureL2capChannel()`, API 29 and up) and adds one readable characteristic to the §4.7 service: ``` PSM characteristic: ABDD3056-28FA-441D-A470-55A75A52553A (Apple's CBUUIDL2CAPPSMCharacteristicString) value: the PSM, 2 bytes, little-endian, 0x0001 ..= 0x00FF ``` A reader treats any other length or value as no PSM. Unencrypted is deliberate: there is no Bluetooth pairing between these phones, and every envelope on the channel is already sealed end to end. **Who opens.** Only a central, only on a link whose payload characteristic is already up, and only when every contact bound to the peer (`J595`) has a card carrying the capability `l2c` — which a build advertises only while its switch is on. A peer bound to nobody is not tried; the PSM is read again when a binding is learned on a link already up. An open that has not completed in 5 s is given up. A channel, once open, is used in both directions; where both phones open one at once, the first stays. **Framing.** ``` length 4 bytes, big-endian 1 ..= 65,536 (MAX_ENVELOPE_BYTES) body length bytes one sealed envelope ``` A receiver checks the length the moment its four bytes arrive, before waiting for or sizing anything for the body; zero or anything over 65,536 closes the channel. So does a stream that ends inside a frame. A frame whose body is a pairing flight or an encounter frame is discarded, not demultiplexed. **Failure.** A frame the sender's stack has not taken within 5 s closes the channel (a half-written frame cannot be withdrawn). Whatever the cause, the envelope that did not go is sent by §4.7a instead, and the fallback is counted. A stream write completing means the sender's stack took the bytes, not that the receiver's app filed them, so the app-level acknowledgements are unchanged. ### 4.8 The beacon fan-out problem, and why beacons carry no tokens Presence tokens are **pairwise**. Carol with fifty contacts has fifty distinct presence tokens per epoch. Broadcasting all of them would be a battery and airtime problem, and the *cardinality* of the set would itself be a fingerprint even though each value is opaque. So beacons carry no tokens at all. Discovery splits in two: - **Advertisement** — service UUID plus a **random ephemeral ID**, rotated per `ADVERT_ROTATE` **[policy]** (default 900 s). It says only "a node running this protocol is here." It is not derived from any secret, identity or contact, and it is unlinkable across rotations (`SPEC-ORIGINAL` §15). - **After connection** — the two nodes exchange presence tokens in a `PRESENCE` packet (§6.3), where the payload is a unicast frame rather than a broadcast and size is far less constrained. This keeps the broadcast channel constant-size regardless of contact count, and confines pairwise material to connections that already happened. --- ### 4.9 CryptoSuite v2 — hybrid X25519 + ML-KEM-768 (`J1901`) **Status (3 Oct 2026): bundle v2 and invitation v5 are on the wire from 2.950, and handshake v3 from 2.951, on both platforms** -- v3 sent only to a displayer whose code's attempt nonce carries the 3b marker (`pairing_code::nonce_answers_v3`, vector 24, `designs/J1901-v3-negotiation.md`) or an identity already known to speak post-quantum, because an initiator of v3 never falls back. Rollout step 3 is live; step 4 is not. In the core: `pq.rs` (the ML-KEM door, cross-checked against RustCrypto's FIPS 203), bundle v2 (`prekey.rs` `sign_bundle_v2` / `verify_bundle_v2`) the v3 agreement (`as_sender_v3` / `as_recipient_v3`) and invitation v5 (`pairing_code.rs` `encode_v5`, `decode`, and `recipient_keys_with` as the one picker, driven per record by the prekey ring: v5 is opened with v3 and nothing else; `J3752` removed the bare-secret export, ABI 5). Vector 21 (`vectors/21-pq-prekey.json`) pins all of it, its ML-KEM values computed by `vectors/mlkem768.py`, a third implementation written from FIPS 203; libcrux, RustCrypto's `ml-kem` and it agree byte for byte. It replaces §4.1's table wholesale when it ships, as §4.1 requires: the suite itself has no negotiation and no optional PQ. The ratchet's in-session mix (`J1901` phase 2, §4.5a, §4.9.5) is the one exception: it is offered only to a contact whose card carries capability `pqr`, and a session with a contact whose card lacks it mixes no post-quantum secret. **The threat it answers is "record now, decrypt later".** Every secret in this protocol descends from one X25519 agreement at pairing (§4.2, §6.5, §6.7). Somebody who records a pairing today and holds a quantum computer later recovers `sharedSecret`, and with it every key under it: routing, message keys, and the Double Ratchet's first chain (§4.5a). The ratchet does not save the later messages, because each ratchet step mixes an X25519 output into the root key, and the root key starts from `sharedSecret`. **Mixing a post-quantum secret into `sharedSecret` protects the whole tree**: the root key then starts from a value the recording cannot recover, and every later ratchet step only adds to it. It does NOT give post-quantum authentication: Ed25519 still signs identities and transcripts, so an attacker who has a quantum computer *at pairing time* can still impersonate. That is a different, later threat, left to a CryptoSuite v3. #### 4.9.1 The table | Purpose | Algorithm | |---|---| | Identity signing | Ed25519 (unchanged) | | Key agreement | X25519 **and** ML-KEM-768 (FIPS 203), always both | | Key derivation | HKDF-SHA256 (the combiner too) | | Token derivation | HMAC-SHA256, truncated | | AEAD | ChaCha20-Poly1305 | | Hash | SHA-256 | ML-KEM-768: encapsulation key `ek` 1184 bytes, ciphertext `ct` 1088 bytes, shared secret 32 bytes. The implementation is `libcrux-ml-kem` (already in `Cargo.lock` through OpenMLS), whose portable code is formally verified (hax/F*) and which takes the caller's randomness, so `vectors/` stay deterministic. Its Arm NEON path is not verified; the core uses the portable path only, and a build check proves which one is linked. HKDF-SHA256 is the combiner even though ML-KEM uses SHA-3 inside: SHA-3 stays inside the primitive and does not join the suite. **The combiner rule, everywhere:** the input keying material is always the classical secret(s) then the KEM secret, and the HKDF `info` always carries **`ek` and `ct` in full**. Binding both is what stops a substituted ciphertext from producing a secret one side can predict while the X25519 half stays honest. Neither half is ever used alone, and a failure of either aborts. #### 4.9.2 Prekey bundle v2 `[0x02 ‖ 32 Ed25519 identity ‖ 32 X25519 prekey ‖ 1184 ML-KEM ek ‖ 64 signature]` = 1313 bytes. The signature is over a **labelled** statement, `"channel/prekey-bundle-v2\0" ‖ X25519 prekey ‖ ek` (its own label: `channel/prekey-v2` is already the v2 invitation's HKDF `info`), never the bare prekey (which also closes `J1833`'s cross-protocol signing note). The ML-KEM decapsulation key pair is generated from a **64-byte** seed (FIPS 203's `d ‖ z`). For a prekey made before the prekey ring (a LEGACY record, §6.7.4) that seed is HKDF-SHA256 of the stored prekey secret under `channel/prekey-mlkem-seed`. A record a rotation makes (INDEPENDENT, `J2895`) carries **its own 64 random bytes** instead, stored beside its X25519 secret: the X25519 prekey is published, a quantum computer recovers its secret from it, and a seed derived from that secret gives up the decapsulation key with it (outside audit of 15 Oct 2026, H-2). A verifier never checked how `ek` was made, so the wire is the same for both. `prekey_ring::legacy_kem` is the one place the core still derives the seed (preflight `kem seed independent`); `vectors/54-prekey-ring.json` pins both kinds. `verify_bundle` reads both versions. The relay's `prekey.mts` accepts 129 bytes (versions 1 and 3) and 1313 (version 2), and since 22 Oct 2026 (relay audit run-1, `relay/prekey-claim-copied-identity`) it also verifies the signature with this same `verify_bundle` / `verify_bundle_v2`, through the core's wasm build (`prekey_bundle_verified`), before the `J1036` value claim: the claim owner is the identity that signed the prekey, not 32 public bytes copied from a GET. A bundle that fails is refused exactly as a misshapen one is (400 `{ok:false}`). #### 4.9.2a Prekey bundle version 3 -- the 129 bytes, labelled (`J2895`, outside audit M-3) `[0x03 ‖ 32 Ed25519 identity ‖ 32 X25519 prekey ‖ 64 signature]` = 129 bytes, every stride and bound of version 1 (rosters, device lists v1 and v2, invitation v4, the card's `pkb`, the relay's row). The signature is over `"channel/prekey-bundle-v3\0" ‖ prekey` (57 bytes), never over the bare 32-byte prekey, so the identity key signs no bare 32-byte value for this bundle. It is signed only through `meshcore_prekey_ring_bundle`, which takes the ring (the prekey SECRET) and derives the public half, so it cannot sign a caller's bytes. `prekey::verify_bundle`, the core's one verifier of a 129-byte bundle, reads version 1 and version 3 and refuses either one relabelled as the other; `meshcore_prekey_verify_bundle` (JNI `prekeyVerifyBundle`) is the apps' door to it. `vectors/55-prekey-bundle-v3.json` pins the bytes. Readers ship first (§4.9.6): a version-3 roster entry or v4 sent to a build that reads only version 1 is dropped silently. #### 4.9.3 Invitation v5 (§6.7) v4's layout, the sender's bundle v2, and the recipient-directed `ct` (1088) after the X25519 ephemeral. Agreement: ``` dhStatic = X25519(senderPrekeySecret, recipientPrekey) dhEphemeral = X25519(ephemeralSecret, recipientPrekey) ssKEM = ML-KEM.Encaps(recipient_ek) / ML-KEM.Decaps(recipient_dk, ct) okm(64) = HKDF-SHA256(salt = none, ikm = dhStatic ‖ dhEphemeral ‖ ssKEM, info = "channel/prekey-v3" ‖ ephemeral ‖ recipientPrekey ‖ senderPrekey ‖ senderIdentity ‖ recipientIdentity ‖ recipient_ek ‖ ct) sharedSecret = okm[0..32]; pairingNonce = okm[32..64] ``` The sender's own `ek` is in its bundle (one bundle shape everywhere) and is NOT in this KDF: the recipient never encapsulated to it. Every v2 check stays (self-invitation, own prekey offered back, ephemeral equal to a prekey, non-contributory X25519), plus: `ct` exactly 1088 bytes, recipient `ek` not equal to the sender's. **A v5 is never derived with the v1 or v2 agreement**, the rule §6.7.3 already states for v4. Size: about 2.6 KB plus the sealed first message, inside the relay's 64 KB. #### 4.9.4 Handshake v3 (§6.5): v2's commitment plus one KEM Built on Handshake v2 (§6.5.9), not v1, so the commitment survives. New packet types; types 11-13 and 16-18 stay exactly as they are. - **OFFER** (initiator): v2's commitment, nonce, generation. Unchanged in shape. - **ACCEPT** (responder): v2's fields plus a **fresh, per-attempt** ML-KEM `ek` (never the published prekey's), signed in the transcript. No decapsulation key work for a forged offer: generating `ek` is the only PQ cost, the same order as v2's X25519 key. - **CONFIRM** (initiator): v2's reveal and signature plus `ct = Encaps(ek)`, with `ct` inside the signed transcript. - The responder checks the reveal against the commitment and the signature over the transcript (which binds `ek ‖ ct`) **before** decapsulating. ML-KEM's implicit rejection means a decapsulation that "succeeds" proves nothing; the signature is the authentication. ``` dh = X25519(myEph, theirEph) // abort if non-contributory, as today ssKEM = Encaps(ek) / Decaps(dk, ct) sharedSecret = HKDF-SHA256(salt = none, ikm = dh ‖ ssKEM, info = "mesh/handshake-pq-v1" ‖ idPubLow ‖ idPubHigh ‖ ephLow ‖ ephHigh ‖ nonceLow ‖ nonceHigh ‖ generation(u32 BE) ‖ ek ‖ ct)[0..32] ``` **The confirmation code is computed over the X25519 secret alone, exactly as in v2 -- never over the hybrid `sharedSecret`.** The initiator chooses `ct` in its LAST flight, after seeing the responder's; had the code covered the KEM half, a man-in-the-middle could grind `ct` (about 10^12 encapsulations) until the two legs' codes matched, which is the grind v2's commitment exists to stop (external review 00102975, 3 Oct 2026). Committing to the encapsulation randomness instead cannot work: revealing it would reveal the KEM secret. With the code over the committed X25519 secret, matching codes mean no man-in-the-middle, so the signed `ek ‖ ct` are the two honest parties', and the KEM half of `sharedSecret` is theirs. **That argument holds only where somebody compares the codes, and since `J348` nobody does** (§6.5.8): against a pairing code substituted in a single channel, the KEM half is the attacker's on each leg exactly as the X25519 half is. The rule stays as built; it costs nothing and protects nothing a user can see. **The transcripts** are new, fixed-length objects under their own label, `mesh/handshake-v3/transcript`, never v2's extended in place. There are two, because the responder signs before the ciphertext exists: `transcript_v3(role) = label ‖ v2's fields in v2's order ‖ ek ‖ role byte`, which the responder signs with role `0x01` in ACCEPT, and `initiatorSigned_v3 = transcript_v3(0x00) ‖ initiatorEph ‖ ct`, which the initiator signs in CONFIRM. Compile-time length assertions hold both. Per-attempt KEM randomness is a separate 64-byte `KemEntropy` beside v2's `Entropy`: the responder's key pair is generated from all 64 bytes, the initiator encapsulates with the first 32; neither is ever reused. Built 3 Oct 2026 (`handshake.rs` `initiate_v3` / `respond_pq`, frames 21-23). One KEM, not two: the threat is recording, and one bound KEM secret in the agreement already puts `sharedSecret` out of a recording's reach; a second would double the bytes on the radio for contributory PQ that this suite does not claim. `pairingNonce`, `pairingSalt` (§4.2) and the confirmation code keep their v2 definitions (the code over the X25519 secret, above). Frame bounds: ACCEPT about 1,350 bytes, CONFIRM about 1,250. Every pairing transport already chunks opaque packets (BLE's 20-byte unnegotiated writes included), so no new fragmentation is needed, only the new bounds in `PacketType::max_bytes`. #### 4.9.5 What stays classical, said plainly - **Contacts paired before v2.** Their `sharedSecret` came from X25519 alone and stays so; nothing re-derives it. A re-pair upgrades a contact. The in-session upgrade (one ML-KEM-768 secret mixed into the ratchet's root per ratchet session) is `J1901` phase 2 (`designs/J1901-phase2.md`), on the wire from 2.952 (answering) and 2.954 (offers, `ratchet.rs` `PQ_OFFERS`, sent to a contact whose card says `pqr`). It protects the CONTENT of messages after the mix against a recording; the outer envelope stays under the pairing key. - **Group rosters.** A roster carries each member's 129-byte bundle, 24 × 161 bytes under a 4,200-byte cap. 1313-byte bundles would make it about 32 KB, against a 32,768-byte decompressed payload limit, and ML-KEM keys do not compress. Rosters keep the v1 bundle; a pairing introduced through a group is classical until rosters carry identities only and members fetch bundles from the relay. - **MLS groups** use OpenMLS's own ciphersuite, which is classical; changing it is OpenMLS's suite choice, not this one. - **Authentication** (Ed25519) everywhere, as above. - **Recovery after a later theft.** Each ratchet step's fresh secret is X25519 alone, so a phone stolen after pairing, together with a quantum computer, reads the messages that follow. Phase 2 (`designs/J1901-phase2.md`, one ML-KEM mix per ratchet session) protects RECORDED traffic; it does not change this. Continuous re-mixing would, and is not designed. - **Invitations v5 sealed to a LEGACY prekey record** (§4.9.2): its ML-KEM key is derived from the published prekey's secret, so a recording of such an invitation has no protection against a quantum computer. A v5 sealed to an INDEPENDENT record has it. A rotation (§6.7.4) supersedes the LEGACY record, and pruning (when on) deletes it 30 days later. - So, plainly: CryptoSuite v2 protects **new one-to-one pairings** against recording. Groups, MLS and contacts paired earlier stay as they are. #### 4.9.6 Rollout, readers first (as §6.7.5) 1. The relay accepts 1313-byte bundles beside 129. 2. Both apps read bundle v2, invitation v5 and handshake v3, and answer v3 as responders; nothing sends them. 3. Once builds that read are what contacts run (measured, as `J1634` measures), apps publish bundle v2 and send v5 and v3. 4. A switch then refuses classical-only invitations and handshakes for new pairings. **Steps 2 and 3 are where a downgrade lives**, so two rules hold from step 3 on, not only at step 4. An app that sends v3 never falls back to v2 or v1 for that attempt, whatever arrives or fails to arrive (§6.5.9 already says the same of v2). **The relay keeps a bundle v2 BESIDE the v1, not instead of it** (3 Oct 2026). Every build older than the readers needs the v1 to invite at all, and group rosters carry 129-byte v1 bundles. So during step 3 a classical invitation to a v2 publisher can be entirely legitimate -- an older sender -- and the recipient cannot refuse it without stranding that sender. Downgrade resistance in step 3 is therefore the SENDER's: - **PQ capability is sticky per identity.** Once a sender has verified a bundle v2 for an identity, it never again sends that identity a classical invitation; a later fetch without a valid v2 fails the invitation rather than falling back. A relay that strips `bundleV2` can then only cause a failure, never a classical pairing, for anyone already seen with v2. - **At step 4 the recipient refuses too:** a device that publishes v2 stops publishing v1 and refuses any invitation agreed against its classical prekey alone (v4 and older), as the switch for new pairings requires. **Step 3b, in-person pairing (`J1901` 3b, 2.951).** A displayer that answers Handshake v3 draws six random bytes for its 8-byte attempt nonce and sets the last two to `SHA-256("mesh/pairing-answers-v3" ‖ displayedIdentity ‖ nonce[0..6])[0..2]`. The scanner starts v3 if and only if that marker verifies for the code's identity (asked of the core, never computed in an app) or the identity is already marked post-quantum, and the flag is on. The nonce is hashed whole into both rendezvous slots and the beacon, so stripping or forging the marker sends the scanner where nobody listens: the attempt fails rather than pairing classically. An older displayer's random nonce matches once in 65,536 attempts; that attempt times out and the next draws a new nonce. A trailing tag on the code was rejected because a single texted code could simply be cut short (an external reviewer 74886299). A first contact whose very first fetch is stripped is the residual window until step 4; it is the same window any readers-first rollout has, and step 4 closes it. Vectors first: bundle v2, invitation v5 and handshake v3, each from fixed randomness, and a test that strips `ct` or swaps it for another valid one and is refused. #### 4.9.7 Sender stamps: a first-contact request may carry two relay-signed stamps (`J2587`) A pairing code (§4.2, versions 1 to 5) may end with a **trailer** carrying up to two stamps. Both are optional; an older reader ignores trailing bytes (`J72a`), so a sender that attaches them costs no older build anything, and a code without them is exactly what it was. ``` trailer [0xB1][flags u8][born: t u64 BE | signature 64] present when flags bit 0 (value 1) is set [verified: t u64 BE | signature 64] present when flags bit 1 (value 2) is set ``` The trailer starts at the byte after the last field the code's version defines (v1: the nonce; v2: the name; v3: the sealed message; v4: the sender's bundle; v5: the ML-KEM ciphertext), and each present stamp is 72 bytes, `born` first. A trailer that is shorter than its flags say, has a flag bit other than 1 or 2, has no flag set, or does not begin with `0xB1` is **absent** (never an error, never a lost request). Nothing authenticates the trailer as a whole and nothing needs to: each stamp is bound to the identity key in the code by its hash, so a stamp pasted onto another profile's code verifies for nobody, and stripping one only makes a sender look unverified. **What each stamp is** (all signed by the relay's `TIME_SIGNING_KEY`, the key `RELAY_TIME_KEY` pins; the signed message is UTF-8, `t` is decimal Unix seconds with no leading zeros, hex is lowercase): | stamp | the hash | the relay signs | obtained from | |---|---|---|---| | `born` | `N = SHA-256("channel-age-v1|" ‖ identity)[0..16]` | `channel-time-v1||` | `GET /v1/time` with `X-Channel-Time-Nonce: `; `J1817` unchanged | | `verified` | `A = SHA-256("channel-verified-v1|" ‖ identity)[0..16]` | `channel-verified-v1||` | `POST /v1/verify/check` and `/v1/verify/renew` with `"attest": ""`; the answer gains `"att": {"t", "sig"}` | (`‖` is concatenation; each label ends with the byte `|`.) The two signed messages differ in their first label, so **a time stamp is never a valid attestation and an attestation never a valid time stamp**, even over the same 32 hex digits (relay test `verify-attest`, vector 39). `attest` is ignored unless exactly 32 lowercase hex digits. The relay stores and logs nothing for either: it sees `attest` beside the value for the length of one call, as it already sees the value and the slot. `verified` says only that this identity key completed a code check at `t`; it names neither the value nor its kind. **The reader** (`sender_stamps::read`, one function in the core, FFI `meshcore_pairing_read_stamps`, JNI `pairingReadStamps`): decode the code; recompute `N` and `A` from the code's own identity key; verify each signature strictly under the relay key. `born` counts when `t` is not more than 86,400 s ahead of the reader's clock; `verified` counts when, in addition, `now - t` is at most 365 days (the proof's own life, `verify.mts` `PROOF_TTL_MS`). A stamp that fails any of these is absent. The reader judges by its own clock; `t` is shown, never trusted for anything but this window. **The sender** (`meshcore_pairing_append_stamps`, `pairingAppendStamps`): the core places the trailer after the code's last field and replaces any it had. Each profile holds its own `born` (fetched once, never replaced, so an existing profile's age counts from its first stamp) and its newest `verified` (exchanged for a fresh one when a month old, paid for by a still-live proof of a value on that profile's card). Vector `vectors/39-sender-stamps.json` carries the hashes, both signed messages, and 18 trailers with what each must read as; the Rust, Swift and Kotlin suites hold to it. **Use** (`DECISIONS.md` `J2587`): the request card shows "Profile made N days ago" (or "age unknown") and "Verified sender"; a per-profile switch, Only Verified Senders (off by default), sets aside a first-contact request without a valid `verified` stamp from anyone who is not already a contact, unseen and unnotified. It does not prove who a sender is: anyone who can receive a code at some number can be verified. **Rollout, readers first.** Both apps read and judge the stamps and obtain their own; the switch that puts them on an outgoing code (`SenderStamps.sendsStamps` on iOS, `SENDS_STAMPS` on Android) is off in the build that adds the reader, and is flipped once that build is what contacts run. ## 5. Payload structure, padding and compression ### 5.1 Plaintext layout The plaintext encrypted into `ciphertext` is: ``` plaintext = canonical-CBOR( PayloadMap ) ‖ zeroPadding ``` `PayloadMap` keys: | Key | Name | Type | Notes | |----:|------|------|-------| | 1 | `senderIdentity` | bstr 32 | Ed25519 identity public key. **Sealed sender** — visible only to the destination. | | 2 | `sequence` | uint | Monotonic per sender per conversation (`SPEC-ORIGINAL` §21). | | 3 | `sentAt` | uint | Sender's wall clock, seconds. Safe here; never in the Envelope. | | 4 | `payloadType` | uint | 1 text · 2 delivery receipt · 3 read receipt · 4 policy update · 5 fragment continuation · 6 attachment chunk (§5.6) · 7 contact card (§5.7) · 8 device list (§5.8) · 9 profile sync (§5.10) · 10 device hello (§5.9) · 11 wipe (§5.11) · 12 reaction (§5.12) · 13 group message · 14 left · 15 thread ended · 16 removed · 17 roster request (all §5.2) · 18 attachment missing · 19 contact share request · 20 contact share disposition (both §5.13) · 21 location request (§5.14) · 22-25 call signalling (§5.15) · 26 thread history (§5.16) · 27 history attachment request · 28 history attachment unavailable (both §5.17) · 29 screen capture (`J1399`; no section yet) · 30 call request (§5.20) · 31 delete for everyone (§5.21) · 32 direct link signal (§5.22) · 33 update, retired (§5.23) · 34-37 formal groups (§5.24) · 38-43 formal groups on MLS (§5.25) · 44 group invitation · 45 invitation accepted · 46 invitation declined (all §5.2.7) · 47 group introduction (§5.2.8) · 48 view-once text (§5.27) · 49 message edit (§5.30) · 50 typing and chat-open (§5.31) · 51 poll create (§5.32) · 52 poll vote (§5.33) · 53 poll close (§5.34) · 59 start fresh (§5.39) · 60 command key grant (§5.40) | | 5 | `compressed` | uint | 0 none · 1 Brotli with `CompressionDictionary v1`. | | 6 | `policy` | map | Sender's current settings (§5.5). | | 7 | `body` | bstr | UTF-8 text, or a receipt structure, per `payloadType`. | | 8 | `groupId` | bstr 16 | *Optional.* Present for group messages (§5.2). | | 9 | `groupDigest` | bstr 8 | *Optional.* Membership digest, so divergence is detectable (§5.2). | | 10 | `messageId` | bstr 16 | *Optional.* The sender's own identifier for this message, stable across re-seals (§5.1a). | | 11 | `groupCreator` | bstr 32 | *Optional.* Present on group payloads; the identity that established the thread (§5.2). | | 12 | `groupRoster` | array | *Optional.* The full roster, when §5.2.4 requires it. | | 13 | `groupName` | tstr | *Optional.* At most 48 bytes, cut on a character boundary (§5.2). | | 14 | `groupRemoved` | bstr 32 | *Optional.* The identity removed, on `payloadType` 16 (§5.2). | | 15 | `replyTo` | bstr 16 | *Optional.* The `messageId` (§5.1a) of the message this one answers (§5.19). Only beside key 10. | | 16 | `aiAuthor` | uint | *Optional.* An AI wrote this message's text; the value is the colour its owner chose for it, `0xRRGGBB`, at most `0xFFFFFF` (§5.28). | | 17 | `linkPreview` | map | *Optional.* The sender's preview of the first link in the text: title, summary, site and a small JPEG (§5.29). | | 18 | `attachmentGroup` | bstr 16 | *Optional.* On chunk 0 of a group attachment (`payloadType` 6) only: the `groupId` (key 8's value) of the thread it was sent to (§5.6e). | | 19 | `sentAtMillis` | uint | *Optional.* 0 to 999: the milliseconds of the send time whose whole seconds are key 3, so a receiver can order messages sent within one second (§5.1b). Never on `payloadType` 6. | | 22 | `intro` | uint | *Optional.* `1` on chunk 0 of a video attachment (`payloadType` 6, media type 4) only: the sender's statement that this is their intro video (§5.6f). Absent means not. Key 21 is unassigned. | | 23 | `command` | bstr 24 | *Optional.* A command key's counter (u64 BE) and 16-byte tag over this message's text and its recipient, written only by a device holding a key an AI's profile granted it, on `payloadType` 1 and 13 only (§5.40). Absent otherwise. | | 20 | `urgent` | bool | *Optional.* The CBOR simple value true, written only when the sender marked this message urgent (§5.1c); absent otherwise. On `payloadType` 1, 13 and 48 only. | | 24 | `forwarded` | bool | *Optional.* The CBOR simple value true, written only when the sender marks this message as a copy of one written for somebody else and sent on (§5.1e); absent otherwise. On `payloadType` 1 and 13, and on chunk 0 of an attachment (`payloadType` 6), only. | #### 5.1a `messageId`, and why it is a map key rather than a body prefix A sender re-seals an unconfirmed message after a relaunch with fresh nonces (`J291`), so the same message reaches a receiver as a different envelope and the envelope-hash guard cannot see it. `J294` fixed that for pictures by deriving the attachment id from the message id; **text had no inner identifier at all**, so a receiver could not tell *hello* re-sent from *hello* typed twice. `messageId` is that identifier: 16 bytes minted by the sender when the message is created and unchanged by every later seal. A receiver that has already filed a message with the same `(senderIdentity, messageId)` drops the repeat. It is also what a **reaction** (§5.12) names, and it must be, because each side's own local identifier for a message is its own and never travels. **Why a map key.** An unknown map key is skipped by a v1 decoder (§1.2), so a sender that includes this reaches an older receiver unharmed. A 16-byte prefix on the `body` of a text payload would instead be rendered as part of the message by any build that did not expect it — a silent, user-visible corruption, which is the failure mode this protocol is written to avoid. **Not a secret and not a nonce.** It is inside the AEAD like everything else in the map, it is never reused for a different message, and nothing about it is derived from the message's content — a receiver must not treat two messages as equal because their ids match without also checking the sender. #### 5.1b `sentAtMillis` (key 19): ordering messages sent within one second (`J2512`, 7 October 2026) **Problem.** Key 3, `sentAt`, is the sender's wall clock in whole seconds, and a receiver files a thread by it. Two messages written in the same second tie, and a tie falls back to arrival order -- which is not send order, because routes and mailbox fetches reorder (`J522`). Five messages sent by an AI in 0.17 seconds arrived and were shown as 4, 3, 2, 1, 5. **The field.** Payload key 19, `sentAtMillis`, uint 0 to 999: the millisecond part of the same instant whose whole seconds are key 3. Inside the sealed payload, authenticated like every other key. - **Sender.** Takes ONE stamp in milliseconds since 1970 and writes `stamp / 1000` as key 3 and `stamp % 1000` as key 19, so the two keys always describe one instant. Each device keeps its last stamp and never issues one less than or equal to it: `stamp = max(now_ms, last + 1)`. A clock stepped backwards therefore cannot reorder that device's own messages, and a burst faster than the clock's resolution still gets distinct stamps; the cost is that a stamp may run ahead of the clock by one millisecond per message in a burst. Written on messages a receiver files in a thread (`payloadType` 1, 13 and 48); a sender MUST NOT write it on `payloadType` 6, whose chunks must stay identical in size (§5.6), and `Payload::encode` refuses it there and above 999. - **Receiver.** Two inbound messages that BOTH carry key 19 and whose key 3 is equal are ordered by key 19, lower first; in every other case -- either one lacks it, or their seconds differ -- the rule is exactly what it was without the field. A receiver that clamps a claimed `sentAt` because it is too far in the future (`J522`) ignores key 19 for that message too. A value above 999 is malformed and the payload is refused, as an over-wide key 16 is. - **Older builds.** Skip key 19 as an unknown key (§1.2, present in every decoder since the first), and keep ordering by key 3 alone -- what they do today. So the field is safe to send to any build, and needs no capability; the sending apps hold it behind a switch until the reading build is installed (`CLAUDE.md`: readers first). **Why milliseconds and not a sequence.** Key 2, `sequence`, already exists and cannot do this: the core keeps one counter per process for every payload type (receipts and chunks included), and it starts again from 1 at each launch. A new per-sender sequence could be made monotonic, but it would order only what ONE device sent -- a profile on several devices (§5.8) has several counters that cannot be compared -- and it must be persisted per contact through relaunch, reinstall and restore from a backup, each of which can rewind it. A wall-clock stamp needs no stored state, compares across the sender's devices exactly as well as key 3 already does, and the `max(now, last + 1)` rule gives it a counter's one property that matters inside a device: it never goes backwards. It tells the recipient nothing new beyond the sub-second part of a send time it already sees to the second. #### 5.1c `urgent` (key 20): the sender's urgent mark (`J2651a`, 11 October 2026) **The field.** Payload key 20, `urgent`, the CBOR boolean true, written only when the sender marked this message urgent and omitted otherwise. Inside the sealed payload, authenticated like every other key. A sender writes it on `payloadType` 1, 13 and 48 (the messages a person reads) and `Payload::encode` refuses it elsewhere; a decoder reads it on any type and the receiving app decides it means something only on a message. The value false is read as not urgent; any value that is not a boolean is malformed and the whole payload is refused, as an over-wide key 16 is. - **Receiver.** The core only reports it. The app decides what it is worth: a receiver whose own switch lets urgent messages through quiet hours shows the alert; one whose switch is off treats the message as any other. The sender's mark is a request, never an override of the receiver's settings. - **Never a deposit flag.** The relay's `urgent`/`ring` deposit flag is the VoIP push that rings a CALL OFFER (`J1055`, `J1066`); a message that set it would ring as a call, and the platform kills a delivery path that does so without presenting one. The mark lives only inside the seal, and a deposit for a message never sets that flag. The relay therefore learns nothing from it. - **Older builds.** Skip key 20 as an unknown key (§1.2, present in every decoder since the first) and show an ordinary message. Safe to send to any build; needs no capability. - **Capability `urg` (`J3265`, 22 October 2026).** A receiver tells ONE contact, in the capability list of the card it sends that contact, that it will honour an urgent mark from them: its master switch is on, that contact is allowed, and the operating system permits a break-through. A sender offers Send as Urgent only toward a card that carries `urg`, checked when the message is sent; a missing, older or tagless card offers nothing. The tag is one more string in the existing `caps` list (no layout change; a reader that does not know it keeps it, §1.2), and it is said per contact, so it is not in the list every build advertises. A receiver treats a mark from a contact it does not allow as an ordinary message regardless of what the sender saw. Android does not write or read the mark yet and never says `urg`. `compressed` lives **inside** the encryption boundary, never in the header — otherwise it would be one more bit for relays to sort traffic by (`DECISIONS.md` C6). ### 5.1e `forwarded` (key 24): the sender's forwarded mark (`J2876`, 15 October 2026) **The field.** Payload key 24, `forwarded`, the CBOR boolean true, written only when the sender forwarded this message: the words or the file were written for somebody else and this copy sends them on. Omitted otherwise. Inside the sealed payload, authenticated like every other key. It lets the receiving app draw *Forwarded* so nobody reads forwarded words as words written to them. - **One bit, nothing else.** The mark names no original sender, no time and no conversation, and the copy carries nothing of the original (`DECISIONS.md` J228). A receiver learns only that it is a forward, never from whom. The mark rides in the sealed message like every key; the relay learns nothing from it and it is never a deposit flag. - **Where it is written.** A sender writes it on `payloadType` 1 and 13 (a text, in a conversation or as a group copy) and on chunk 0 of an attachment (`payloadType` 6): the file's other chunks stay byte-identical to what every earlier build sealed, so a streamed send's retry identity (§5.6a) is untouched and the first chunk stays in its padding bucket. `Payload::encode` refuses it on any other type and the core's public seal entry points refuse it on any chunk but chunk 0. - **Where it is believed.** A decoder reads key 24 on any type (§1.2: it must not refuse a key it is required to ignore), and the core reports it to the app only on a text and on chunk 0 of an attachment (`Reception::Delivered { forwarded }`, `out_forwarded`), so the one place a receiver reads it is the one place a sender writes it. A value that is not a boolean is malformed and the whole payload is refused, as for key 20. - **An attachment keeps the mark with its set.** A receiver notes it from chunk 0 and applies it to the message it files when the set is whole, whatever order the chunks arrive in. A caption that travels as a text beside the chunks carries the same mark, and either one marks the filed message. - **Older builds.** Skip key 24 as an unknown key (§1.2, present in every decoder since the first) and show an ordinary message; a build reading an older sender's message reads it as not forwarded. Safe to send to any build; needs no capability. `vectors/53-forwarded-payload.json` pins the bytes, the older build's reading, an unknown key beside it, the false and the integer forms, and chunk 0. - **Not carried.** A forward into an MLS group or a formal group's submission is a different message (an MLS application message, a submission to the admin) with its own wire; those carry no key 24. ### 5.1f `hopBudget` (key 25): how many nearby devices carried a message (`J3509`, 27 October 2026) **The field.** Payload key 25, `hopBudget`, an unsigned integer `1..=MAX_ACCEPTED_HOP_LIMIT` (§2.2): the `hopLimit` the sender put on the envelope when it sealed it, written only when that value is above zero (a sender never writes a value above `MAX_ACCEPTED_HOP_LIMIT`; it writes the maximum). Omitted when the sender did not permit carrying, and by every build before `J3509`. It follows key 24 in canonical order and is inside the sealed payload, so it is authenticated like every other key and is never a deposit flag. - **What a receiver computes.** `hopsSpent = hopBudget - hopLimit of the envelope as it arrived`, saturating at 0 and never above `hopBudget`. Each carrier spends exactly one hop (§7.7a: the hop limit is first clamped to `MAX_ACCEPTED_HOP_LIMIT`, then one is spent), so it counts any number of carriers: 0 is a message that arrived direct, 1 one carried once, and so on. With no `hopBudget` the count is **unknown**, which a receiver MUST NOT show as 0 (an older sender, or one that forbade carrying). - **Where it is written and read.** Written on every `payloadType` the sender seals with a limit above zero. A decoder reads it on any type (§1.2). The core reports it as `Reception::Delivered { hops_spent }`, `out_hops_spent` (255 means unknown) and, in the JNI bridge, byte 2 of `outForwarded`. A value that is not an unsigned integer in `1..=MAX_ACCEPTED_HOP_LIMIT` (0, 9 or more, a negative, a boolean, a byte string) is malformed and the whole payload is refused. - **It is a label, not evidence.** The arriving `hopLimit` is outside the AEAD (§2.2) and a carrier may change it, so a hostile carrier can make the count read higher or lower, and can make a carried message read as direct. It cannot forge content, a sender, or a time: those stay authenticated. An app uses the count to draw how a message travelled and for nothing that trusts it. The count names no carrier. - **Older builds.** An older decoder skips key 25 as an unknown key (§1.2) and shows an ordinary message; a build reading an older sender's message sees no budget. Safe to send to any build; needs no capability. `vectors/63-hop-budget-payload.json` pins the bytes, the older reading, an unknown key beside it, the refusals and the arithmetic. - **Streamed chunks.** A later chunk of a streamed attachment must re-seal byte-identical (§5.6a), so a sender uses the same hop limit for every chunk of one message. ### 5.1d Receipt bodies and the batched read receipt (payload types 2 and 3, `J2528` R3, 11 October 2026) A delivery receipt (type 2) and a read receipt (type 3) carry a fixed-layout body, not CBOR. It is **not** in `mesh-core-rs`: it is one pure codec in `channel-algo` (`delivery_state`, ops 10 decode, 11 encode and 12 batch, `J3317` item 7b), called by `Receipt.swift` and `Receipt.kt` through the same wrapper on each platform, and held to the same bytes by `vectors/50-batched-read-receipt.json` and by `vectors/algo/receipt.json` (written by an independent Python reference). The id it names, `SHA-256(envelope)[0..16]`, is still computed in the apps. A receipt time past one day ahead of the receiver's clock is clamped to now plus one day, as an unsigned value on both platforms. ``` body = id(16) x k | seconds(8, big-endian) | route(1, optional) 1 <= k <= 8 ``` - Length is `16k + 8` or `16k + 9`. The two families never overlap (their lengths differ mod 16), so the length alone says how many ids there are and whether a route byte follows. For k = 1 these are exactly the 24 and 25 bytes every build already reads, so an old body is unchanged. - A body of any other length, k above 8, or the same id twice is refused whole. - `seconds` is the moment it happened on the reader's device; a time more than a day ahead is clamped to a day ahead, as for a single id. One timestamp and one route cover every id in the body. - The route byte is the table in §5.16b (1 Bluetooth, 2 Wi-Fi Direct, 3 local network, 4 Internet, 5 SMS bridge, 6 direct IPv6); an unknown byte names no route and the receipt still counts. - A reader applies the receipt to each id it names. A body naming ids it does not hold changes nothing for those. **Capability `rcb`**: a build that decodes `k > 1` says so on its card. A sender puts more than one id in a **read** receipt (up to 8, one body per writer and route) only to a card that carries `rcb`; to any other card it sends one read receipt per message, as before. A **delivery** receipt always names one id. An older build refuses a `k > 1` body at decode, which is why the sender waits for the tag: opening a thread with 20 unread costs 3 deposits to a card with `rcb` and 20 to one without. ### 5.6c Size padding for attachments (`J1455`, 29 September 2026) -- NOT ADOPTED **Decided by the owner the same day: not built.** The existing rule -- every chunk full length, the last one zero-padded -- already means an observer learns an attachment's length only to within one chunk (16,000 bytes), so nobody can identify a particular document from its size without knowing it to the byte. PADMÉ would widen that window for large files at up to ~12% extra data; the owner judged the current window sufficient (*"the mission has been accomplished"*). Kept below as the design to reach for if that judgement ever changes. The caveat stands: a matching chunk count is consistent with, not proof of, a suspected transfer. **Threat.** Somebody watching the network (a relay operator, a Wi-Fi owner, a state) holds a particular file -- a leaked document -- and knows its exact byte length. They must not be able to tell from what CHANNEL puts on the wire whether that file was sent. (The owner, 29 Sep 2026: *"do whatever is necessary to make sure no one can identify a particular leaked document based on packet sizes."*) **What an observer sees today.** An attachment's real length (`total_bytes`) travels inside the seal. On the wire there are only `n` envelopes of one fixed size, so the observer learns `n = ceil(total_bytes / CHUNK)` -- the length to within one chunk. For a file of a few megabytes, that narrows the candidates to files within 16,000 bytes of each other, which is enough to confirm a known document. **The rule: pad the chunk count to PADMÉ.** A sender sends `n_padded = ceil(padme(total_bytes) / CHUNK)` chunks, where `padme` is `mesh-core-rs`'s existing function (Nikitin et al., PETS 2019). The first `ceil(total_bytes / CHUNK)` chunks carry the file exactly as today. The rest are **padding chunks**: full-size, with the same fields, and `data` all zero. Every chunk keeps the fixed wire size, so the observer sees only `n_padded`. Chunks carry `total_chunks = n_padded`. - **What that buys.** PADMÉ rounds a length to a bucket about 1/2^(S) of its size (S grows slowly with the length), so a file hides among every file whose padded size lands in the same bucket. The overhead is at most about 12% and far less for large files; the information leaked about the length falls from ~log2(length) bits to ~log2(log2(length)). Below 16,000 × 16 bytes, PADMÉ's bucket is smaller than one chunk and nothing changes: a small file already hides among every file of the same chunk count. - **Never worse than today.** Every chunk stays full length, so no size leaks through a short last chunk. The observer's anonymity set is `max(today's, PADMÉ's)` at every size. - **Receiver.** Accepts `total_chunks` in `ceil(total_bytes/CHUNK) ..= ceil(padme(total_bytes)/CHUNK)` and **refuses anything above that bound** (a peer cannot make a phone wait for, or store, more than 12% extra). A chunk whose `index >= ceil(total_bytes/CHUNK)` must be all zero; it is acknowledged and discarded, never stored. The attachment is complete when its data chunks are complete; padding chunks are not waited for and are not asked for as missing. - **Capability `padm`** on the card says the build reads this. A sender pads only for a peer that advertises it, so an older build is never sent a chunk count it refuses. Readers ship first. - **Every other path that exposes a length pads the same way**: a bundled relay upload (its object is the sum of padded envelopes), a large Welcome or group photo sealed once and uploaded (§5.23a, §5.25.9 -- pad the sealed object's plaintext to `padme`, with the true length inside the sealed reference so the reader truncates), and streamed sends (§5.6a) likewise. - **What this does not hide.** When a transfer happens, and between whom, is visible to anyone who can see the traffic itself. Size padding answers "which file", not "whether". ### 5.6d Chunk-zero acknowledgement (`J1771`, 1 October 2026) **Problem.** A radio write proves only that some phone took the bytes (§4.7a covers Bluetooth's own ack, and only for a peer bound to the contact). A message whose radio claim is not followed by a delivery receipt within the receipt window (8 s) is sent again by the Internet (`J1618`). An attachment has no such rule for its first slice, and the receiver cannot repair it either: the missing-list (type 18) is sent only for an attachment the receiver knows exists, and with the ratchet on (§4.5b) no later slice opens until chunk 0 has. A chunk 0 lost on a radio therefore leaves the receiver holding slices it cannot open and nothing that will ever ask for the one it lacks. **The acknowledgement.** An ordinary delivery receipt (payload type 2, the 24-byte receipt body in §5.1 key 7: 16 bytes of id, 8 of big-endian seconds) whose id is ``` ackID = SHA-256( "CHANNEL chunk-zero ack v1" (UTF-8, 25 bytes) || chunk-0 envelope )[0..16] ``` over the envelope exactly as transmitted. A message's own receipt id is `SHA-256(envelope)[0..16]`, so the label keeps the two from ever naming the same thing. **Receiver.** When an attachment chunk (type 6) opens and it is the FIRST slice of that attachment id this process has opened, and it arrived by Bluetooth, Wi-Fi Aware or the shared LAN (or by a route the transport cannot name), and the sender's contact card carries the capability `c0a`, the receiver sends that receipt with `ackID` computed over the envelope it received. It is sent as any receipt is (it follows the message: the radio first, the mailbox when no radio takes it). Under the ratchet the first slice to open is chunk 0. Without it, a first slice that is not chunk 0 yields an id the sender does not hold, which the sender treats as no acknowledgement -- correct, since chunk 0 has not arrived. **Sender.** When chunk 0 of a pass is taken by a radio rung (not a `J1804f` catch-up, not a `J252` rescue) and the recipient's card carries `c0a`, the sender holds chunk 0's envelope and waits the receipt window. If by then no receipt naming `ackID` has arrived, the attachment has no delivery receipt, and the message has not been rescued, it sends the SAME envelope once more by the contact's own route (a direct link, else the mailbox). When the mailbox may NOT carry this attachment -- in particular when the contact's card currently refuses the Internet, which also refuses the direct link -- the watch is still armed, and the same envelope goes once more by the radio peers chunk 0 was offered (`J2501`, 6 October 2026: without this, a chunk 0 a radio claimed and lost to a contact with the Internet off was never sent again). At most once per pass; the watch is in memory and a restart inside the window drops it. The "photos direct only" setting is asked again when the window ends. A resend does not move a message's route mark away from a radio -- that mark is what the `J252` rescue keys on to resend every slice a radio may have lost -- it is added to the route trail instead. A receipt naming an `ackID` is never applied to a message, matched or late. **Readers first.** A build without `c0a` never receives an acknowledgement (the receiver gates on the sender's card) and never causes a resend (the sender gates on the receiver's card). An older sender that did receive one would find no message with that id and ignore it. ### 5.6e Which group an attachment belongs to (`attachmentGroup`, payload key 18, `J2470`, 6 October 2026) **Problem.** A group attachment is sealed pairwise to each member, like every group message (§5.2: there is no group key), as ordinary attachment chunks (`payloadType` 6). Nothing in a chunk said which group it was for. The group announcement is a text envelope (type 13) sent only when there is a caption, so a caption-less photo -- the usual case -- reached each member as bare chunks: a sender who is also a direct contact had it filed in the one-to-one chat, and one met only through groups had it filed in whichever shared group came first. **The field.** Payload key 18, `attachmentGroup`, bstr of exactly 16 bytes: the `groupId` -- the same 16 bytes key 8 carries on the thread's own messages -- of the thread the attachment was sent to. It is inside the sealed payload, authenticated by the AEAD like every other key, and never on the wire in clear. - **Sender.** Written on **chunk 0 only** of an attachment sent to a group thread (informal or formal), on both the held and the streamed path; every later chunk is byte-identical to what a build without this field seals. A sender MUST NOT write key 18 on any other `payloadType` (`Payload::encode` refuses it) or on a chunk other than 0 (`Node` refuses it). It costs nothing an observer can count: the padded size of chunk 0 is the same bucket with or without it (measured in `node.rs`), and on the streamed path the §5.6a nonce is derived from the complete plaintext, which includes it. - **Receiver.** The core reports key 18 only when the payload is an attachment chunk whose index is 0; on any other payload, or a later chunk, it is decoded for length and ignored. The app treats it as a claim: it files the whole set (every slice of that attachment id) in the named thread only when this device holds that thread, it is not an MLS thread (§5.25 posts never travel pairwise), its charter accepts the sender if it is formal (§5.24), and it lists the sender as a participant if it is informal. Otherwise the set is routed exactly as without the field. A receiver never creates a thread because of key 18. - **Order of arrival.** Slices may arrive before chunk 0. They are filed where routing put them without the field; when chunk 0 names a thread, the slices of that attachment already held for this sender elsewhere are moved to it. Later slices follow the set: the receiver remembers where each attachment id is being assembled, and after a restart reads it from where its pieces are stored. **Why key 18 and not key 8.** Every build's decoder refuses key 8 (and keys 9, 11-14) on a `payloadType` that is not a group type (`check_group`: "group fields on a non-group payloadType"). Chunk 0 carrying key 8 would be refused by every receiver -- and with it the whole attachment. **Readers first, and no gate.** Every decoder since the first (1 September 2026) skips an unknown payload key (§1.2), so an older receiver reads chunk 0 with key 18 exactly as one without it and files the attachment where it always did. This was measured, not assumed: the decoder as it stood at the change's merge base decoded a chunk 0 with key 18 spliced in and returned it intact, and refused the same id under key 8. So the writer needs no capability gate. Vector: `vectors/30-attachment-group-payload.json`. ### 5.6f The intro video (`intro`, payload key 22, `J2646b`, 11 October 2026) **What it is.** An ordinary video attachment (media type 4, §5.6) with one authenticated mark: the sender's statement that it is a live recording of themselves, at most 10 seconds, sent with a first contact request (`J2646`). The mark lives in the sealed payload, so only the holder of the pairwise key can write it; it proves who SAYS it, never that the video shows who it claims. **The field.** Payload key 22, `intro`, uint, the value `1` or absent. Any other value is malformed (one fact, one encoding). Key 20 is not assigned and stays skipped as unknown (vector 31 uses it for that). - **Sender.** Written on **chunk 0 only** of a video attachment, held or streamed. `Payload::encode` refuses it on any `payloadType` but 6; `Node::seal_streamed_attachment_chunk_in_group` refuses it on a media type but 4. Every later chunk is byte-identical to what a build without the field seals. On the streamed path the §5.6a nonce is derived from the complete plaintext, which includes it. - **Receiver.** The core reports `intro` only when the payload is chunk 0 of a media-type-4 attachment; anywhere else it is decoded and ignored. The app treats it as a claim and applies its own bounds (length before opening, size after, duration) -- those are app rules, not the core's. **Readers first, no gate.** Every decoder since the first skips an unknown payload key (§1.2), so a build that does not know key 22 reads the chunk as an ordinary video. No capability is needed. Vector: `vectors/48-intro-video-payload.json`. ### 5.6a Sealing an attachment too large to hold — IMPLEMENTED (`Node::seal_streamed_attachment_chunk`; both apps send large videos this way) > **Built, and called by both apps** (`J1554`). It was written before the code, as this project's > order requires (Assignment 01: the protocol leads the implementation). > > **Revised 14 September 2026 after an adversarial review**, which found the first draft wrong in > two ways and improvable in a third. The review and what it changed are recorded at the end, because > a design whose corrections are invisible invites the same mistakes back. #### The problem, stated exactly A sender can already slice an attachment off disk without holding it — `J663`'s `sliceForChunk` reads chunk `i` at its offset and pads `J605`'s short tail so the object's true length does not leak. That half is built and tested. What stops it being used is **sealing**: 1. Every envelope's nonce is **12 random bytes** (`Node::next_nonce`, `getrandom`), so a re-seal produces different ciphertext. 2. `J255` exists because of (1): a message is sealed once per (message, epoch) and the whole sealing is **cached**, so a retry puts byte-identical envelopes on the air. `J581`'s skip-what-already-landed rests on that — indices are only stable while the bytes are. 3. A 3 GB sealing cannot be cached. So a streamed send needs a nonce it can **recompute** rather than remember. #### What a recomputable nonce must satisfy The requirement is not "deterministic". It is **never the same (key, nonce) pair over two different plaintexts**. The AEAD here is **ChaCha20-Poly1305** (`mesh-core-rs/src/aead.rs`), where reuse gives an attacker the XOR of two plaintexts *and* the Poly1305 key for that (key, nonce), hence forgeries. - **Unique per chunk within a message** — the index supplies this. - **Unique per message within a key** — the key is per PAIRING GENERATION (`messageKey`, §4.5), not per epoch; `messageId` (§5.1a) is `SHA-256(uuid)[0..16]`, locally generated. - **Stable across a retry of the same bytes** — the whole point. - **Never reused across two different plaintexts** — the one the others do not give, and the one that decides the design. #### The hazard that decides it, and why a whole-file hash does not fix it *The same (messageId, index) sealed twice with different plaintext.* It is not hypothetical: a streamed send reads a file it does not own — that is what streaming is for — and a file can change under a message that has not finished sending. (A small attachment is copied into the app's own store first, `attachmentsDirectory`, and is immutable once filed. The multi-gigabyte case is precisely the one where it is not.) The obvious answer — hash the whole file once, bind the nonce to that hash — **does not work**, and the reason is a time-of-check/time-of-use gap the first draft of this section missed. The hash pass happens before the first chunk goes out; the reads happen later. If the file changes in between, the sender derives `nonce_i` from the *old* hash while sealing the *new* bytes. A later retry of the original bytes under the same stored hash is then the exact reuse this section exists to prevent. Deriving a per-attachment key from the whole-file hash instead has the same gap: same key, same counter, different plaintext. #### The derivation **Bind each nonce to the complete AEAD input it is about to seal — the AAD and the plaintext — and to nothing that can go stale.** ``` nonce_key = HKDF-Expand(prk = sending_key, info = "mesh/att-nonce-key-v1", L = 32) nonce_i = HKDF-Expand(prk = nonce_key, info = "mesh/att-nonce-v2" || messageId(16) || u32_be(i) || SHA-256(aad_i(47) || plaintext_i), L = 12) ``` where **`aad_i` is the envelope's 47-byte AAD (§3.1) and `plaintext_i` is the ENCODED PAYLOAD** — the exact two byte strings handed to the AEAD, not a file, not a promise about a file, **and not the raw slice either**. The AAD is fixed-length, so `aad ‖ plaintext` is unambiguous. > **v2, 1 October 2026 (`J1833`, from an outside review, finding M1).** v1 bound `SHA-256(plaintext)` > under the label `mesh/att-nonce-v1`. The epoch reaches the AAD — the destination token and the > creation bucket — without reaching the plaintext, and a later chunk's packet id is derived, so a > re-seal with the same `sentAt` in another epoch sealed **one (key, nonce) under two AADs**. Two > Poly1305 tags under one one-time key give that key away, and with it forgeries of the chunk. The > review demonstrated equal nonces and two different tags; no shipped caller is known to have passed > an old clock into a new epoch, because both apps read a fresh clock for every seal. > > **Not a wire change.** The nonce travels in the envelope (§3.1) and a receiver opens with the one > it is given; nothing recomputes it on the receiving side. So the sender changed the derivation with > no capability gate, and every receiver, old or new, opens what it seals. > **Corrected 16 September 2026, after an adversarial review found a nonce reuse.** This sentence > already said "the bytes that `seal` is about to receive", and it was right; the first > implementation still fed it the raw slice. The plaintext is strictly larger than the slice — it > also carries `sentAt` (§5.1 key 3, the sender's wall clock) and `sequence`. So two seals of one > slice a second apart produced **the same nonce over two different plaintexts**, which under > ChaCha20-Poly1305 gives up the XOR of them and the Poly1305 key for that pair. > > Nothing failed. Every test passed, because each happened to pass the same clock value twice, while > a real sender reads a clock and would have moved it on every attempt. > > The lesson is why the wording is now explicit rather than merely correct: *"the bytes `seal` > receives"* and *"the chunk plaintext"* read as the same thing to somebody who has the slice in > front of them. **Bind the nonce to the complete input to the AEAD.** Then every field that can > distinguish two plaintexts is inside the digest by construction, including fields nobody has > thought of yet, rather than by a list somebody has to keep complete. Four properties follow, and the third is the one the whole-file version could not give: - **Retry-identical while the AEAD input is.** The same plaintext under the same AAD hashes the same, so `nonce_i` reproduces. **What moves it is any byte of either**: the slice, `sentAt`, `sequence` and the chunk's metadata in the plaintext; the packet id, the destination token and the creation bucket (both from the epoch) and the lengths in the AAD. So a retry in the same epoch with the same recorded `sentAt` and `sequence` reproduces the whole envelope, and a re-seal in a later epoch is a different envelope with a different nonce — which is correct: it is a different AEAD input, and sharing a nonce with the first would be the reuse above. Two inputs need the sender's help to stay put: - **`packetId`** is in the AAD (§3.1), so a fresh one per attempt changes the envelope and, from v2, the nonce with it. Settled by §5.6b, which derives it. - **`sequence`** is inside the payload (§5.1), so the same applies. On the ordinary path both are settled by `J255`, which caches the finished sealing. A streamed send has no cache, so **a sender MUST reuse the same `packetId` and `sequence` for a given `(messageId, index)` across every attempt**, or `J581`'s skip-what-already-landed compares against a seal identity that has moved and re-sends everything. `mesh-core-rs` takes both as parameters rather than drawing them, and `a_streamed_chunk_is_only_retry_identical_while_packet_id_AND_sequence_HOLD` demonstrates each half rather than describing it. `packetId` is answered by **§5.6b below**. `sequence` is not derived: it is the sender's own counter, and a streamed sender MUST record the value it used for a chunk and reuse it. - **Key-separated.** The sending key is the AEAD key; a nonce is derived under a *different* key expanded from it, so one key material is not doing two jobs. - **No window.** The hash is of the bytes in hand. There is no interval during which the input could become untrue, because the input is not a claim about anything else. - **Cheaper.** No whole-file pass before the first byte leaves, which also removes a second reason a 3 GB send would appear to stall before starting (`J762`). Two rules an implementation must not omit: - **`J255`'s cache must not be consulted for a streamed send.** Half a sealing from the cache and half recomputed is two nonce schemes in one set, which is how a reuse is produced. - **Every field in `info` is fixed-length.** `messageId` is 16 bytes, the index 4, the digest 32. If any becomes variable, it needs a length prefix or the concatenation becomes ambiguous. - **The labels carry the protocol's name, never the product's.** `mesh/…`, matching `tokens.rs`, whose own comment records why: the labels were `OfflineMesh/…` until the product was renamed on 2 September 2026, which silently changed every derived key and every token and was caught only because the conformance vectors failed. A label embedding the brand makes any future rebrand a silent wire-format break. The first draft of this section used `chan-att-…`; it is corrected here rather than discovered later. #### The bound, stated rather than implied The nonce is 96 bits (`envelope.rs: NONCE_LEN = 12`). Collision becomes non-negligible around 2^48 chunks under one pairing-generation key — hundreds of petabytes at this chunk size, so it does not bind in practice, but it is the same bound random nonces have and this construction does not improve it. A deterministic scheme also cannot resample its way out of a collision the way a random one theoretically could. Worth knowing before anyone proposes raising the ceiling again. #### What the review changed, and what it did not Reviewed adversarially on 14 September 2026 against this section, `aead.rs` and `envelope.rs`: - **The primitive was named wrong.** The draft reasoned about AES-GCM. It is ChaCha20-Poly1305, and the consequence of reuse differs — corrected above, in a section about nonce reuse, where naming the wrong cipher is not cosmetic. - **The whole-file hash did not close its own hazard.** The time-of-check gap above. This is the finding that changed the design rather than the prose. - **Key separation.** The draft used the sending key directly as the HKDF PRK for a nonce used under that same key. Now a derived `nonce_key`. - **Not taken:** a suggestion to derive a per-attachment content key from the whole-file hash and use a counter nonce. It is a good construction and it inherits the same time-of-check gap, which is the problem being solved; per-chunk binding does not. #### Status, 1 October 2026 - `vectors/07-streamed-attachment-nonce.json` is **generated**, never transcribed, and carries six cases plus two separation checks. The cases are the argument: the same bytes under the same AAD reproduce the nonce; **one edited bit moves it**; the same bytes at a different index differ; **the same bytes one epoch later — a different AAD — differ** (`J1833`); and a different key or a different message differ, so an implementation that dropped a field from `info` fails at the vector rather than in the field. It holds v2 only: no receiver ever recomputes a nonce, so v1 has nothing left to be read by. - `mesh_core_rs::attachment::streamed_chunk_nonce` implements it and `conformance::streamed_attachment_nonce_matches_the_vector` holds it to the file; `a_streamed_chunk_resealed_in_another_epoch_never_reuses_its_nonce` holds the caller to handing it the AAD it really seals under. - **Both apps call it** through `Node::seal_streamed_attachment_chunk` for large attachments (`J1554`); the send path seals one chunk at a time from disk and bypasses `J255`'s cache, so one set never mixes two nonce schemes. ### 5.6b — The packet id for a streamed chunk **Status: built and in use.** Implemented in `mesh-core-rs` (`attachment::streamed_chunk_packet_id`), held against `vectors/08-streamed-attachment-packet-id.json`, which is generated, and called by the node when it seals a streamed chunk (`seal_streamed_attachment_chunk_in_group`), which both apps use. Chunk 0 of a ratcheted attachment is the exception: it takes a fresh id per seal (`J1559` §4.5b). #### Why a derivation is needed §5.6a makes the *nonce* recomputable. It does not make the envelope recomputable, because `packetId` is in the AAD (§3.1) and a sender drawing a fresh one per attempt produces different ciphertext every time with a perfectly stable nonce. `J581`'s skip-what-already-landed then compares against a seal identity that has moved and re-sends everything — a large transfer that never converges, with nothing failing anywhere to say so. On the ordinary path `J255` settles this by caching the finished sealing. A streamed send has no cache, by design. #### Why it is derived from a secret The obvious answer is a public derivation from `(messageId, index)`. **It leaks.** A packet id travels in clear in the envelope header; if it were a published function of a message id and a counter, anybody who can see two envelopes could tell they belong to one attachment and count its slices. Random ids give that away to nobody, and a replacement has to keep the property. Expanding under a key only the two ends hold keeps the ids indistinguishable from random for everybody else while the sender can reproduce them exactly. ``` packet_key = HKDF-Expand(sending_key, "mesh/att-packet-key-v1", 32) packetId_i = HKDF-Expand(packet_key, "mesh/att-packet-v1" ‖ messageId(16) ‖ be32(index), 16) ``` Every field fixed-length, so the concatenation is unambiguous. A variable-length field added here would need a length prefix. #### Properties - **Retry-identical.** The same `(sending_key, messageId, index)` reproduces the id, which is what makes the whole envelope reproduce once §5.6a supplies the nonce. - **Unique per chunk.** `index` is in the info, so two slices of one attachment never share an id — which matters because `packetId` is the receiver's duplicate-suppression key, and a collision would silently drop a slice. - **Unlinkable.** Indistinguishable from random without the pairwise key, so the header reveals no more than a random id did. - **Key-separated.** A different label from §5.6a's, so the packet-id stream and the nonce stream are not the same stream. The vector carries both derived keys side by side, so an implementation that reused one label fails there rather than in the field. #### What this does NOT settle `sequence` (§5.1) is still the sender's own counter and is sealed inside the payload. A streamed sender must record the value used for a chunk and reuse it on every retry. Deriving it was considered and rejected: it is a payload field with ordering meaning of its own, and overloading it with a second job is the kind of double duty §5.6a's key separation exists to avoid. ### 5.7 Contact card (`payloadType 7`) The sender's own card, for the receiver to show beside their messages (`DECISIONS.md` J84 §4). `body` is UTF-8 JSON: ``` { "v": 1, "name": "", "stock": "" | absent, "jpeg": "" | absent, "routes": { "b": bool, "l": bool, "i": bool } | absent, ... } ``` Every field after `name` is **optional and appended** (`DECISIONS.md` J72a): a decoder ignores keys it does not know and treats absent keys as absent rather than as an error, which is what lets a card cross between builds and between platforms. `routes` is the sender's **delivery policy** (`DECISIONS.md` J8): which pathways they will accept being reached on — `b` Bluetooth, `l` the local network, `i` the Internet mailbox. The three are independent (J11: *"individually chosen preferences as to what pipes are available"*, never a bundle). Two rules about it are load-bearing: - **Absent means undeclared, not denied.** A receiver leaves any policy it already holds untouched when a card carries no `routes`. An older build says nothing, and treating silence as a retraction would shut every pathway the moment one un-upgraded peer sent a card. - **No expiry travels.** A declaration is trusted for a bounded window (14 days), and that window is stamped by the **receiver** at the moment the card arrives. A sender therefore cannot declare itself trusted indefinitely, and the freshness that matters — *how long since we heard this* — is the only thing either side can actually measure. Past the window the policy routes as **all pathways false**, which is J8's fail-closed rule. `pkb` (`J1688p`) is the sender's own signed prekey bundle, 129 bytes, base64. A receiver keeps it only when it verifies and its identity is the sender's -- the same test `J852` applies to a fetched bundle -- and uses it for one thing: the roster (§5.2.1), so that other members can be introduced to this contact (§5.2.8). Absent means none offered; a receiver keeps any bundle it already holds. Distinct from `caps` (`DECISIONS.md` J621), which is on the same card and answers a different question: a **capability** says what the software can receive and changes with a release; a **route** says what the person allows and changes with a toggle. Sent once after a pairing completes and again whenever the card changes; a receiver that already holds the same card (same bytes) ignores it. The picture, when present, is a square JPEG no larger than 128 px and 16 KiB, so the whole payload fits the largest padding bucket (32 KiB, §5.3). A card is never filed as a message and never notified. The receiver keeps its own local name for the contact; the card's name is shown only where the receiver has not chosen one, and the picture is shown unless the receiver picked their own. ### 5.8 Device list (`payloadType 8`) The sender's linked devices, so the receiver can address each one (`DECISIONS.md` J98, J382, J383, J385). `body` is UTF-8 JSON: ``` { "v": 1, "devices": [ { "id": "", "prekey": "" }, ... ] } ``` At most **ten** devices (`DeviceSession.maxDevices`, both platforms; linking itself stops at six until revocation is built, `J1866`); an empty list is valid and means every device was removed. Each `prekey` is a signed bundle whose identity **must equal** `id`, or the whole list is refused — a sender may not hand out a prekey for a device it does not hold. A receiver opens one session per device (`PrekeyAgreement` as sender, then contact derivation §6.8), sends the device a hello **through the sender's phone** (§5.9), and from then on seals **one envelope per device** for everything it sends, each under that device's session and destination token. A device omitted from a later list is dropped immediately. Sent after a device is linked or removed and again whenever the list changes; never filed, never notified. **`again` (`J2197b`).** A phone may send ONE contact its current list with a top-level `"again": [ "", ... ]` (at most ten), naming devices that list carries whose session with this contact must be made anew -- because the device says it holds no keys for the contact (§5.16b). A receiver acts on it only when the list opened under the person's own session (the rule above) and only for identities the same list carries: it drops that device's session and opens a fresh one, with a fresh hello (§5.9), exactly as for a newly listed device -- unless the session's hello was first sent less than an hour ago, which is left to its own retries. A session with no stored hello (made by a build before `J2100`) is always remade. Malformed or unlisted entries are ignored, never a reason to refuse the list. A reader that predates the key ignores it, as it ignores any key it does not know; the phone never stamps this list as the one announced (`deviceListSentHash`). A policy update (§5.5) may also carry `"linkedBy": true`, sent by a phone to a device it has just paired in person, meaning *you are now one of my devices*. **A receiver ignores it** (`J1561a`). A device becomes linked only on its own owner's action: the person holding it chooses Receive a Profile, and on that screen's pairing completing the device records the other side as its phone and answers with a one-entry device list of its own bundle. The claim is still sent, for builds that predate that screen. Honouring it let any recent contact claim the link, and a linked phone may erase the device (`J925`). ### 5.8a Device list, version 2 -- a signed chain (`J1866` step 3; core `device_list.rs`; READERS FIRST) Version 1 above is unsigned and only the person's first phone can send it. Version 2 lets every device of a person keep the list, and lets a contact check it, without the person's identity secret `P` ever leaving the phone it was made on. **No build writes version 2 yet; this section is the readers' rule.** **Body** (signed; big-endian; every length checked before allocation; trailing bytes refused): ``` "channel/device-list-v2\0" | P (32) | seq (u64) | prev (32) | u16 n<=10 | n x ( id (32) | u16 129 | PrekeyBundle (129, §6.8) | u16 a<=64 | hello address (a) ) -- sorted by id | u16 g<=64 | g x tombstone id (32) -- sorted | u16 s 1..10 | s x signer id (32) -- sorted then: u16 s | s x Ed25519 signature (64) over everything above, in signer order ``` **Genesis**: `seq` 1, `prev` all zero, no tombstones, at least one device, signed by `P` alone. **Every later link**, accepted only against the link the reader holds: 1. the same `P`; `prev` = SHA-256 of the held body; `seq` greater by 1 to 16; 2. each bundle verifies (`verify_strict`) and names its own `id`; no listed id is tombstoned; 3. tombstones only grow; **a device leaves only by being tombstoned in that link** -- never by omission; 4. signed by `max(1, min(2, n_previous - 1))` devices **of the previous link**, none of them a device this link removes; this holds for an add, a removal and a changed bundle alike; 5. **or** signed by exactly one device that removes only itself and changes nothing else (self-removal; the last device may empty the list this way and no other way). The same `seq` with a different body is a **conflict**: refused, shown to the person, settled only by a higher `seq` that meets rule 4. A reader that missed links asks any session of the person for them and applies them in order. **With two devices rule 4 asks one signature, so a stolen unlocked phone can remove the other before it is removed** -- stated, not protected; the PIN lock and the distress code are the defence there. **Readers, before any writer:** a version-2 list never deletes by omission; "my own bundle" (a device to its phone) and "the person's membership" are different payloads; hellos do not require a session with `P`'s key; the chain state (`P`, `seq`, the held hash, devices, tombstones) is stored with the sessions; a list naming an id already on another card, or this device's own, is refused whole; once a person has sent `dl2`, unsigned version 1 from them is refused. Writers ship only once the readers are installed. **Superseded by §5.8b**, which applies the 5 October 2026 review (`DECISIONS.md` `J1866`, "step 3 reviewed again"): every membership change co-signed, two devices disputed rather than one-signer, `seq` by exactly 1, no tie-break, no lone self-removal. This section describes `device_list.rs` and vector 19, which stay only until both apps call §5.8b's verifier instead. ### 5.8b Device list, version 2 -- the verifier (`J1866b`; core `device_list_v2.rs`; vector 29) The rule every reader applies to a person's chain of device lists, implemented once in the core (`device_list_v2::verify_next`, `verify_pair`, `verify_listing`; FFI `meshcore_device_list_v2_verify`, `_pair`, `_listing`, `_body`, `_encode`). Where `DECISIONS.md` was open to two readings, the stricter one is taken and named below as **stricter reading**. **Wire** (big-endian; the whole list at most **5,062** bytes, checked before anything is read; every count checked before allocation; trailing bytes refused): ``` body = "channel/device-list-v2\0" (23) | seq (u64) | prev (32) | issued_at (u64, seconds since 1970) | u16 n<=11 | n x ( key (32) | since (u64) | u16 129 | PrekeyBundle v1 (129, §6.8) ) -- sorted by key, unique | u16 g<=64 | g x tombstone key (32) -- sorted, unique list = body | u16 s 1..11 | s x ( signer key (32) | Ed25519 signature (64) over body ) -- sorted by signer, unique ``` - `prev` is **SHA-256 of the parent's body** -- signatures excluded, so the same body carrying a different set of valid signatures is the same parent and cannot split readers (*chosen over hashing the signatures too, which would let one signer make two readers disagree on a parent*). - `issued_at` is inside the signed bytes because a published listing expires 7 days after it. - `since` is the `seq` a device was admitted at (0 for genesis devices). It is signed so every reader applies "admitted at n cannot co-sign n + 1" from the list alone (**stricter reading**: the decisions name the rule but no field; carrying it is the only way two readers agree without a second store). - At most **11** devices (ten linked plus the one they were linked from), **64** tombstones (every slot of a full person replaced five times over; a removal past that is refused), **11** signatures. - Bundles are v1, exactly 129 bytes, each verifying (`verify_strict`) under its own entry's key. **Genesis** (the reader holds nothing for `P`): `seq` 1, `prev` all zero, no tombstones, at least one device, every `since` 0, and **exactly one signature, by `P`** (**stricter reading**: no co-signers at genesis). **A child** of the held list `H`, checked in this order (the first failure is the refusal code): | rule | refusal (code) | |---|---| | `issued_at` <= now + 600 s | FromTheFuture (7) | | `seq` <= `H.seq`: same `seq` and `prev`, other body = sibling; otherwise replay | Sibling (4), Replay (3) | | `seq` = `H.seq` + 1 exactly | SeqSkip (5) | | `prev` = SHA-256(`H` body) | WrongParent (6) | | `issued_at` >= `H.issued_at` | ClockBackwards (8) | | every bundle verifies and names its own key | BadBundle (9) | | no listed key is tombstoned | Tombstoned (10) | | every signature verifies over the body | BadSignature (11) | | every signer is a device of `H` (the newcomer never signs) | SignerNotHeld (12) | | every device of `H` that is gone is tombstoned here | OmittedWithoutTombstone (13) | | tombstones = `H`'s plus exactly the removed (**stricter**: none pre-emptive) | TombstoneMismatch (14) | | a new device's `since` = `seq`; a kept device's `since` unchanged | SinceMismatch (15) | | a kept device's bundle changes only with that device signing (**stricter**) | BundleSwap (16) | | no devices left only from a one-device `H` | Empty (18) | | **membership change** (anyone added or removed): at least `min(2, devices of H)` signers of `H` with `since` < `H.seq` | Quorum (17) | | **no membership change** (a refresh): one signer of `H`, any `since` | -- | - **Two devices is a disputed state.** If `H` has two devices and a list only REMOVES, signed by one signature, the verdict is **Disputed**: the reader keeps `H`, and the person is told. This holds when the signer removes itself too (**stricter reading**: no lone self-removal path survives the 5 Oct rule that any removal needs two). An add or a swap at two devices with one signature is **Quorum**. - **Admitted at n, signs at n + 2.** A device admitted at `seq` n does not count toward a membership change at n + 1. A refresh (signed by any held device) moves the chain on, after which it counts; that is also how a person whose only device was admitted in the last list continues. - **A fork** is two different children of one parent, each of which would be accepted or disputed on its own (`verify_pair`); the reader keeps `H` and tells the person. Never tie-broken. A refused candidate cannot manufacture a fork. - **Signers in a refresh need not be eligible** (**chosen**, not stricter): otherwise a person whose every device is newly admitted could never move again, and a refresh changes nobody's membership. **Find me by -- a published listing**: `u16 count<=128 | count x (u16 len | list)`, the chain from what the fetcher holds (from genesis when it holds nothing). Every link must be **accepted** in order (a disputed or forked link refuses the listing, LinkNotAccepted 20); the head must have `now - issued_at <= 7 days` (Stale 19) and no more than 600 s ahead. Nothing held and no links is NoChain (21). To stay findable, any device signs a refresh within the week. **Superseded for a person's hosts by §5.8c** (`J1866e`): its co-signing quorum contradicts the owner's decision that the two devices in a share are the whole approval. The verifier stays until nothing calls it. **Measured in `judge` (8 Oct 2026), for `J1866d`:** the eligible signers of a membership change are counted without excluding a device the link removes, so a removal at two devices signed by both (the leaving device consenting) is accepted, and only a one-signature removal there is Disputed. **Proposed, not in the verifier** (`designs/J1866-onward-sharing.md` Q4, the owner's call): a one-signature removal at two devices taking effect after 7 days unless the removed device signs a newer link meanwhile. **Host status codes (`J2586d`).** A seal refused because the payload does not fit one message (a length bound, the core's `TooLarge`) is `MESHCORE_ERR_PAYLOAD_TOO_LARGE` (-14), distinct from `MESHCORE_ERR_PROTOCOL` (-5), which every other compose failure still answers; it is deterministic, so a host does not retry it unchanged. The codes live in `meshcore.h`. **Malformed bytes** are not refusals; the FFI reports them as `MESHCORE_ERR_PROTOCOL` with a code from 101 (TooLarge) to 111 (TooManyLinks). Vector `29-device-list-v2.json` covers genesis, a refresh, a valid add, the refused clone add (alone and co-signed by the clone), the n + 1 exile, wrong `prev`, `seq` skip, replay, a tombstoned key re-added, an unsigned bundle, Disputed, Fork, and a listing at exactly seven days and one second past. ### 5.8c The host roll -- a profile's hosts, written by any host alone (`J1866e`; core built, step 1; hosts READ it, step 3; contacts READ it, step 4; the origin WRITES it, step 5, behind a switch that is off) Design: `designs/J1866-travelling-profiles.md`. **No build sends any of this yet.** The core implements it (`host_roll.rs`, vector `34-host-roll`; no FFI yet, that is step 2). It replaces §5.8b and §5.10a (and the origin's sole authority in §5.8, §5.9 and §5.10) once built; until then those sections describe what ships. Why §5.8b's chain does not carry over: under `J1866e` the giver alone writes an add and a host alone leaves; §5.8b refuses both at two or more devices (Quorum, Disputed), and without its quorum its never-tie-broken forks would be routine. The roll is order-free instead. **Statement** = `body | Ed25519 signature (64) over body by author`. Body, big-endian, each kind exactly its own size (with the signature: root 164 + 163 per host, at most 1794; add 326, or 462 stamped; leave 162, or 298 stamped; bundle 293; distrust 199; Master Key set by the only host 362, with its stamp; change 226; evict 198; re-root 325; set by one of several hosts 362, refusal 330, both with their stamp; this line said *at most 256 bytes* until step 1 measured that no add or root fits in it): ``` "channel/host-roll-v2\0" (21) | P (32) | author (32) | seq (u32) | at (u64) | kind (u8) | payload [| stamp] kind 0 root: u16 n 1..10 | n x (key 32 | u16 129 | PrekeyBundle v1 129) -- author P, seq 0; sorted, unique; P listed kind 1 add: key (32) | u16 129 | bundle (129) | flags (u8, bit 0 transfer) kind 2 leave: (empty) -- the author leaves kind 3 bundle: u16 129 | bundle (129) -- names the author kind 4 distrust: subject (32) | cut (u32) | flags (u8, bit 0 erase asked) -- only if the owner adopts option B kind 5 (withdrawn: the joint removal; refused as unknown, never reused) kind 6 Master Key, set by the only host: R (32) | RS (32) | stamp -- J1866f, stamped since J3280(b) kind 7 (withdrawn: the set by two hosts side by side; refused, never reused) kind 8 change: R' (32) | RS' (32) -- J1866f; author is the old R kind 9 evict: subject (32) | cut (u32) -- J1866f; author is R kind 10 re-root: key (32) | u16 129 | bundle (129) -- J1866f; author is R kind 11 Master Key, set by one of several hosts: R (32) | RS (32) | stamp -- J1866f; waits 48 h (rule 9) kind 12 refusal: set (32, SHA-256 of a kind-11 statement's body) | stamp -- J1866f; any host, within the 48 h stamp: proof (64) | relay time (u64) | relay signature (64) -- kinds 6, 11 and 12 always; 1 and 2 by bit 7 ``` **Bit 7 of the kind byte** (`J3280`(b), 31 Oct 2026; 0x81 an add, 0x82 a leave) says the add or leave carries a stamp. It is in the body, so the proof and the signature cover it; on any other kind it is refused (205). A writer stamps every add and leave it can. One it could not (an in-person share with no route to the relay) is valid and ranks last; its giver adds the key again, stamped, when it next can. **v2** (`J1866f`, 9 Oct 2026): kinds 5 and 7 withdrawn, 11 and 12 added. No v1 roll was ever written outside tests (the writer has shipped off), so v1 is simply not read. The **Master Key** (in code the recovery key; `R` its Ed25519 public key and `RS` its X25519 seal key, §5.8f, §5.8h) is what removes a host: no host removes another, alone or with a second host side by side (the owner, 9 Oct 2026: removal or setting by two devices side by side is a game the real owner could lose; the Master Key is what makes the owner king). The R seed (`recovery_key::derive`) signs kinds 8-10 here, and a recovery lift in §5.8d, through the same signers and nothing else. Refused as malformed (code 225, `BadSigners`): a Master Key equal to the key that signs it; an eviction, change or re-root naming its own author. A re-root's bundle verifies under its key. **Stamps** (kinds 6, 11 and 12, and a stamped add or leave). A stamp is `J1817`'s relay time (§5.8e) for the nonce `SHA-256("channel/host-roll-nonce-v1\0" | proof)[0..16]`, where `proof` is the author's Ed25519 signature over `"channel/host-roll-stamp-v1\0" | the body before the stamp`; the stamp sits at the end of the body, so the statement's own signature covers it. The proof makes the nonce one only the holder of the author's key can ask for, and binds the stamp to this one statement (seq, clock, payload): it cannot be fetched in advance by anybody who does not yet hold the key, nor moved into another statement. A writer asks the core for the proof and nonce (`roll_stamp_request`), fetches the relay's `{ t, sig }` for the nonce, then builds the body with the stamp. A statement whose proof is not its author's is refused (code 226, `BadStamp`) both as it arrives and in evaluation; one whose RELAY signature does not verify under the relay key the reader trusts is refused as it arrives (227, `BadRelayTime`) and **ignored** in evaluation, as if absent, so a relay key the reader no longer trusts cannot stop it reading the roll. **A stamp is the only time a rule may trust** (`J3280`(b)): it proves a statement was signed at that relay time. `seq` and `at` are the author's own word and a thief holding the key can write any value; `seq` still orders one author's statements (rules 1 and 2), `at` orders unstamped adds among themselves, and neither decides who is a host ahead of a stamp. A stamp proves when a statement was signed, **never when it was shown** (see the limits below). `seq` counts the author's own statements from 1 and is persisted before signing. Only the root has `seq` 0. Flag bits not listed are refused, as is a distrust naming its own author. Every bundle verifies (`verify_strict`) under the key it names. A roll is `u16 count <= 512 | count x (u16 len | statement)`, at most one entry of a root's size; bounds are checked before anything is read. Two statements with one body are one statement. An author may sign at most 256 statements (the root counts as one of `P`'s); one that signs more is not refused but removed (rule 0 below). **Hosts** (one function in the core; the same statements give the same answer in any order): 0. Bounds (`J1866f`, 9 Oct 2026), in this order, and never a refusal: a. A statement whose author is not reachable -- listed by the root, or added (by any add, counting or not) by a reachable author -- is dropped before anything is counted. It could never count, and many keys nobody added must not be able to push the set past its bound. b. Over the cap: an author with more than 256 distinct statements (the root counting as one of `P`'s) is removed, and none of its statements counts -- not its first 256, since which those are would depend on arrival order. Statements count toward an author only if they verify under its key, so only the holder of a key can put it over. c. Past the bound: while what remains, the root included, is more than 512, the author with the most remaining statements (the root counting as one of `P`'s), then the lower key bytes among equals, is removed the same way. Several keys one thief holds, each near the cap, go before honest hosts with a few statements. An author removed by b or c is flagged *over the cap*. The held root always stays and still lists the first hosts. 1. Two different statements with one author and `seq`: nothing by that author at or after the lowest such `seq` counts, and the author is removed (equivocation). No other ordering among statements is used. 2. Nothing by an author with a `seq` above its own `leave` counts. 3. Ever admitted: the root's keys, then every key added by an ever-admitted author. 4. A distrust counts when its author is ever admitted. A distrusted key's adds and bundles above the lowest cut given to it do not count. Distrusts are never cut. 5. Admitted: the root's keys, then every key added, by a statement still counting, by an admitted author. 6. Removed, for ever: every key that left, was distrusted, equivocated, or was removed by rule 0 -- or (`J1866f`) by the Master Key (rule 9). 7. A key's admission is the root if it lists the key (after a re-root, the re-root for its key), else the counting add of it by an admitted author: a stamped add before an unstamped one, then the earliest stamp (for unstamped, the lowest `at`), then the lowest SHA-256 of its body. So a thief's adds, signed after he took a host, rank behind every add stamped before him, whatever `at` they claim (`J3280`(b)). `admitted_at` is that time. 8. Hosts: admitted minus removed, ordered by admission (root keys first, then rule 7's order); the first 10 are hosts, the rest wait. A host's bundle is its counting `bundle` with the highest `seq`, else its admission's. **The Master Key** (`J1866f`, 9 Oct 2026; design "Recovery key", "Ruling: the Master Key, set by one host"). Rules 0a, 1 and 2 apply to every author, a Master Key included. In rule 0a a key is also *named* -- and so reachable -- when a reachable author sets or changes to it as R (kinds 6, 8, 11) or re-roots to it (kind 10). In rules 4 and 9 "its adds and bundles above the cut do not count" is the same rule; only adds and bundles are cut. 9. **The Master Key**, read on the profile as the root began it: a. What *sets* it is read from the set as rule 0a leaves it, before rule 0b removes anything, and is never cut afterwards: a thief holding a setter cannot take the key away by flooding or equivocating with it. *Host keys* are the root's keys and every key any add from them names (uncut). **A leave silences a host key only for what came after it** (`J3280`(b)): a set or refusal at or above the leave's `seq`, or stamped at or after a stamped leave. What it signed before stands, so a set in effect survives its author's later transfer. b. A set by **the only host** (kind 6) counts when its author still speaks and the roll proves it was the only host **at its stamp**: following every add from the root keys, except an add stamped at or after that time and the author's own unstamped adds at or above the set's `seq`, reaches the author and no key but keys with a leave stamped before that time. (So the owner sets it on a new profile, as the author's first statement, and shares afterwards; an unstamped leave proves nothing and that host uses (c).) c. A set by **one of several hosts** (kind 11) by a host key takes effect once **48 hours** (172,800 s, `MASTER_KEY_WAIT_SECONDS`) of relay time have passed since its stamp -- judged against the reader's latest accepted relay time `now` (§5.8e) -- **unless a host key signed a refusal** (kind 12) naming it whose stamp is earlier than the set's stamp plus 48 hours. A refused set never takes effect, whenever the reader looks; a refusal at or after the 48th hour is too late and ignored. Any host may refuse, the set's own author included. **Once a key is in effect, only that key changes it** (the owner, 9 Oct 2026): taking the kind-11 sets in order of stamp, a set whose stamp is at or after the moment an earlier standing set took effect (its stamp + 48 h) is void and never in effect, if that earlier set is unrefused, or was refused only by this set's own author (`J3280`(b), so a refusal held back cannot bring its signer's own hidden set to life; void for ever). A void set voids nothing. Two sets stamped while neither was yet in effect still contest. Sets still within their 48 hours and unrefused, a void one included unless void for ever, are listed (`Hosts.pending_recovery`: when each takes effect, the hash a refusal names, its author, R and RS), so a host can show its person a set they did not make in time to refuse it. A reader with no relay time, or one the relay key does not verify, holds every kind-11 set pending. The app requires the profile's PIN before signing a set or a refusal; the core does not see it. d. If any (b) counts, the (b)s at the earliest stamp are the anchors and every (c) is ignored (none is pending). Otherwise every (c) in effect is. Each distinct `(R, RS)` among them starts a chain. **One chain: settled. More than one: contested.** e. A chain: a key's statements count while below its own equivocation (a leave means nothing to it). Its change is its counting kind 8 with the lowest `seq`, unless that names a key already in the chain; then nothing the old key signs at or above that `seq` counts, and the chain goes on with the new key. The last key is current. `Hosts.recovery` lists each chain's current `(R, RS)`, sorted. f. An **eviction** (kind 9) by a counting key of any chain removes its subject (flag *evicted*); the subject's adds and bundles above the lowest cut given to it do not count. g. A **re-root** (kind 10) counts only when there is one chain: the one with the highest (place in the chain, `seq`). Contested keys can remove, never take. 10. **The world** after a re-root to `N`: admission starts from `N` alone (rule 7: its admission is the re-root, its bundle the re-root's); an add counts there only when its author is `N` or a key the old roll never reached (*old*: the host keys, and every key reachable by any add from an earlier counting re-root's key). So `N` and what `N` adds onward are the hosts; a key the old roll held that `N` adds again is a host, and what it added before does not come back with it; an old host's add of `N`'s new device changes nothing. Every key the roll ever held, or the old roll reached, that is not admitted in the new world is removed (*evicted*). Without a re-root the world is the root's. (Rule 11, the joint removal, and the probation by relay time briefly built for kind 7 are withdrawn with those kinds.) **What this gives against a thief holding ONE host.** No statement any host signs, alone or beside another, removes anybody. The thief can set a Master Key of his own (kind 11): it does nothing for 48 hours, and any of the owner's hosts refuses it in that time; refused, it never takes effect. He can refuse the owner's kind-11 set the same way -- a stand-off in which neither key takes effect -- but **a Master Key set while the profile had one host (kind 6) outranks every kind-11 set, refused or not, so the owner who made the key at creation wins outright.** If the owner sees nothing for 48 hours, the thief's set takes effect; if the owner's set had already taken effect, the two contest (each evicts, neither re-roots). A thief holding two hosts is not otherwise covered, as for freezing (§5.8d). **Limits of rule 9, stated (`J3280`(b), all on kind 11; none reaches a key set by the only host).** A stamp shows when a statement was signed and nothing shows when it was published, so three things stand: (1) a refusal stamped in the window and held back still refuses when it arrives, unseating a key already in effect and undoing its evictions. No rule on statements can tell it from a refusal sent in time, because the thief's refusal of the owner's set and the owner's of the thief's are the same bytes. It gives the signer the stand-off an open refusal would have, and not the key. (2) A set held back past its own 48 hours is in effect the moment it arrives, with no window to refuse it. (3) A host that refuses a set and later signs its own after that set's 48 hours is void under the rule above: set from another host, or within the 48 hours. So a profile should get its key by kind 6, at or before its first share; only a profile shared before the Master Key existed needs kind 11. **Two hosts.** Neither host can remove the other. The owner who keeps one of two devices uses the Master Key (evict the other, or re-root), or the other host leaves on its own. Ties: root keys among themselves by key. The core's `evaluate_roll(root, statements, relay key, now)` reads at most 1024 statements (twice a roll, so a full roll fits beside one author's statements past its cap), checks every input first and refuses the whole call on any statement that is malformed, unsigned, with a proof that is not its author's, for another `P`, or a second root; once those pass it never refuses on counts (rule 0). `now` is the one input that differs between readers holding the same statements, and only while a kind-11 set is within its 48 hours. A reader filters with `check_roll_statement(bytes, P, relay key)` as statements arrive. Its `removed` lists only keys the roll ever held (or, after a re-root, that the old roll reached), so a stranger's own `leave` names nobody. While option B's switch (`DISTRUST_ENABLED`) is off, a distrust parses but has no force and the core will not sign one. **Root**: a reader holds one root per `P`, the first it accepts, and refuses any other. The origin (the host whose key is `P`) writes it, listing itself and its linked devices; a device takes it only from its linking device (opened under that device's own identity, root `P` equal to it, this device listed with the bundle it sent); a contact takes it only signed by the card's own `P`. **Spreading**: a host sends what it writes, and passes on what it learns, to every host and contact it holds a session with; a duplicate is dropped. Readers summarise what they hold as `[{"a": author hex, "s": seq}]` (`rollHave`, at most 64) and ask for the rest (`rollFrom`). Between hosts these travel as profile-sync keys (§5.10) `roll`, `rollHave`, `rollFrom`, `intro`, `caps`; to contacts as payload type 8 `{"v":3,"roll": base64,"have":[...]}`, taken from any session of the card (older readers refuse `v:3`). A statement's route is never a reason to trust it. Until a reader has caught up it may still send to a removed host; every host passes on every statement at once to keep that short. **Contacts** seal to every host of the roll they hold a session with; make a session with a new host from its listed bundle and send it a §5.9 hello through any host they hold a session with, which forwards it only to a host of its own roll; drop a removed host's session at once, `P`'s main session included; and, once they hold a root for a card, refuse §5.8 v1 for it (before that, v1 only from `P`'s own session, as §5.10 says). While the `P` host is a host it still sends v1, projected from the roll, to contacts that do not advertise `roll1`. **Contacts, as built (step 4; readers only).** A contact keeps one roll per CARD, by the card's `P` (the pairing key), in a sealed side file `person-rolls.json` (a map from `P` in hex to a roll book: root, verified statements). It never writes a root, a statement or a summary of its own. - *Wire.* A device list (payload type 8) with `"v":3` is read by its own function, never by the version-1 reader. Keys, all optional but at least one required: `roll` (base64 of a roll encoding, at most 16,384 raw bytes and 40 statements), `have` and `from` (`[{"a": 64 hex author, "s": seq}]`, at most 64, authors unique, `s` a u32), and `again` (`J2197b`, at most ten hex identities). The whole body is at most 32,768 bytes, checked before parsing; one value out of bounds refuses the whole message. `{"v":3,"from":[...]}` is the only version-3 body a contact sends: it asks a session of the card for what it lacks, when a `have` it just read is ahead of its own, at most once a minute per card. Hosts answer such an ask in step 5; a contact answers nobody. - *Who may deliver.* Any session of the card: the person's own or a device's. With no root held, a root is taken from any of them when it is signed by the card's own `P` (it proves itself; the first root taken is the only one held, any other is counted and dropped). Once a root is held, only a session whose key the roll lists as a host may deliver, and a statement is kept only when the roll already knows its author (the host function's bounds, 512 statements and 256 per author, apply). - *Sessions.* A contact holds a session with every host the roll lists (made from the bundle in the roll, hello stored with it) and with no other key. A key the roll removes, or lists only as waiting, loses its session at once, `P`'s own included (nothing new is sealed to it, whoever asks, and nothing it sends is read); the card stays keyed by `P`. A removed key is never given a session again. An identity that is on another card, or is the card's own key, never becomes a session (the version-1 rules `J437`, `J2568`). - *Hellos.* A new host's hello (§5.9) goes first through the session of the statement's author (that of `P` for a key the root lists), then the person's own session, then the other hosts, hosts that have answered before those that have not. The retry sweep (`J1979`) takes the next of them on each attempt. A host forwards a hello only to a host of its own roll (a profile with no roll forwards to any link end, as before), and a device accepts a hello from any link end its roll lists, not only the phone that linked it. - *Downgrade.* Once a root is held for a card, a version-1 list for it is refused, whoever sealed it. - *`again`* (`J2197b`) is read from any host's session, for a key that is a host; the session is made anew by the version-1 rule (a hello first sent under an hour ago is left to its retries). - *Not a change of the wire for older builds.* A contact on a build without this reads `v:3` as malformed and keeps what it holds; the version-1 list is still what it learns from (§11.3, step 5 projects it from the roll). **The writer, as built (step 5; `HostRollWriter`, `MessageStore+RollWriter.swift` / `MessageStoreRollWriter.kt`).** - *The switch.* `HostRollWriter.enabled` / `ENABLED` is **false** in every shipped build. The root is written once and kept for ever (§4a.3), and from then on a contact on this build reads the roll alone (a version-1 list for its card is refused). Under today's flows the origin can drop a linked device from ITS OWN list but cannot sign that device's `leave` (the core signs a statement only for the author of the seed) and `distrust` is off, so a device the person removes would stay a host for every contact on this build: the lost-device question of the design (section 10) decides. Reading a root, answering an ask and the version-1 projection are on regardless; they act only once a root is held. - *When the root is written.* On the origin only (a profile that came from another device never writes one, §11.2), with the switch on, when no root is held and at least one linked device has answered with its bundle. The first share therefore writes it; an existing shared profile writes it at the next announcement (launch, the retry sweep, a device answering). It lists this device with a bundle signed now, then each answered linked device with the bundle it sent (at most ten in all; the core sorts them), at the origin's clock in seconds. - *Adds.* For each answered linked device the roll does not know at all (not a host, not waiting, not removed) the origin signs an `add` (transfer flag 0) with its next `seq`. That `seq` is **reserved in the roll book (`ownSeq`) and saved before the statement is signed**, so a crash leaves a gap, never two statements at one `seq`. A removed key is never added again. Nothing is written for a removal: see the switch. - *To the profile's devices.* The root, then each statement, as profile sync `roll` with `rollHave` on the last message and `caps` `["roll1"]` (§ above); and the whole roll again when a device answers its giver with `caps` containing `roll1` and the root lists it (a device the root does not list cannot take a root, §11.1, and is sent none by this path; it receives the adds and answers its asks as any host). - *To contacts.* A card capability tag `roll1` (`CardCapability.hostRoll`, in every card from this build) says a contact reads the roll. To such a contact the host sends the whole roll, the root first, as payload type 8 `{"v":3,"roll":base64,"have":[...]}`, in as many messages as the 40-statement / 16 KiB bounds need, `have` on the last only; when the summary (`rollHave`) it last sent that contact is not the current one (the hash is kept in `deviceListSentHash`, stamped when the mailbox copy landed). A host sends this for every statement it writes or passes on (§7.1). A contact whose card does not say `roll1`, or has not arrived yet, is sent the version-1 list, never a version-3 body. - *The version-1 projection (§11.3).* While a root is held the version-1 list is `{"v":1,"devices":[{"id":hex, "prekey":base64}...]}` over the origin's answered linked devices **in link order, kept only if the roll lists them as hosts**, with the bundle bytes the device sent; `again` (`J2197b`) after the list. For the same devices it is byte for byte what the origin sent before it held a root (tested against an independently written builder, with a link order that is not key order). A contact on this build is not sent it. - *`again` for a contact on this build* is `{"v":3,"again":[hex]}`, for a device the roll lists as a host. - *A contact's `{"v":3,"from":[...]}` is answered* with `answer(from)` (what the contact lacks, the root only if it listed no `P`) as version-3 `roll` messages with no `have`, under the session the ask came over: only for a real contact of the profile (not its own record, a link end, a group member, blocked, an AI), only while a root is held, only from that contact's own session, at most once in 30 seconds per contact. - *A device linked after the root* is in no root, so it takes none (§11.1) and holds no roll; it works as before until the handover of step 7 gives it the roll, and the contacts and the other hosts see it through its `add`. **Hosts** open sessions with each other by §6.7.2 v4 introductions to the bundle the roll lists, forwarded by any host holding both sessions; the target takes one only from a host of its roll, with the listed prekey, a first message that opens, a new ephemeral, and no live session with that key; a host drops its session with a removed key at once and forwards nothing to or from it. Profile sync, sent copies, history and call fan-out run host to host. A host that adopts a roll removing a key tombstones that link (`J2527`) and drops held renewals (`J2545`). **Sibling sessions, as built in step 6** (`J1866e`; the wire details the design left open). A host that holds a root and is a current host sends an **introduction** to every other current host it holds no record of, when its identity key is the **lower** of the two (unsigned byte order; only the lower introduces, so two hosts introducing at once can never leave each with a session the other lacks). The introduction is a profile-sync key, bounded before it is decoded and a bad value refusing the whole message: | key | value | |---|---| | `intro` | `{"to": 64 hex, the target's identity, "code": base64 of one 6.7.2 v4 pairing code, at most 4096 characters}` | The code is the one `renewThroughOldLink` builds and nothing new: the introducer's own prekey against the bundle the roll lists for the target (v2 agreement, 6.7.2), name empty, its first message an empty text sealed on a core of its own so the live core takes no ratchet step before the target agrees. The introducer sends `intro` to every host session it holds; a **forwarder** (any host) passes it on **unchanged**, and only when the sender is a current host and the code names the sender, the target is a current host (not the sender, not itself) and it holds a session with the target. The **target** takes it, quietly and never filed, only when all of these hold, and judges the code, never the route: it arrived over a session of its own profile with a current host opened under that host's own key; it is for this device and this device is a current host; the code's identity is a current host of the roll (not removed, not this device) and the **lower** key; the code's bundle verifies under that identity and its prekey **equals the prekey the roll lists** for it; the first message opens under the v2 agreement; the ephemeral key has not been taken before (the last 256 are remembered); and this device holds no record for that key and has not tombstoned it. Having taken it, the target registers the session (a hidden link end, `isSiblingHost`) and answers with its `rollHave` over it; anything that opens under the session at the introducer ends the introduction, which until then is sent again every 10 minutes for 7 days and reaches nobody else (an unanswered session is not a host session). A host that learns a key is removed drops its sibling session and any waiting introduction at once. Over a sibling session a host sends and reads the roll (`roll`, `rollHave`, `rollFrom`), further introductions and block reports, as it does over any host session. Sibling sessions form wherever a root is held; nothing here depends on the root writer's switch. **Sharing** is the giver's `add` of the newcomer's bundle after an in-person pairing on the newcomer's single-use code (valid while shown, at most 10 minutes, one giver); the giver then hands over the roll, `P`, profile sync and history. **Transferring** is a share whose giver then signs `leave`. **Taking a profile off a host** is that host's `leave`, delivered before the host deletes its copy and its identity secret. No secret key is copied by any of them. **Sharing, as built in step 7** (`J1866e`; `HostShare`, `MessageStore+HostShare.swift` / `MessageStoreHostShare.kt`). *Live in every build:* the limits below on today's origin-to-device link, the ten-minute single-giver code, the newcomer's counts in its answer and the refusal sent to it. *Dormant until a root is written* (the writer is off): everything that signs an `add`, hands a roll over or lets a host other than the origin give the profile away. - **Limits** (`scripts/limits.json`): 10 hosts for one profile, 10 profiles on a device, at most **9 of a device's profiles shared** (a profile is shared while it has two or more hosts; a transfer from a profile held alone into the tenth slot is allowed because it ends with one host, and every other share raises the newcomer's count by one). The giver checks before the scan (a profile at 10 hosts, a profile held alone while 9 others are shared, a freeze in force, a PIN required and missing) and again on the newcomer's first answer (an older build when a roll is in play, 10 hosts, the newcomer at nine); the newcomer checks the roll it is handed (it lists this device with a prekey it sent; it is not waiting past the tenth place; it is not the tenth shared profile unless a transfer). A refused share leaves the newcomer nothing: no `add`, no roll, the half-made link gone, and both screens say why. The freeze and the PIN are decider inputs only: no app holds freeze statements or asks for the PIN first yet, so neither refuses anything in a build. - **The newcomer's answer** (`deviceList` `{"v":1,"devices":[...],"label":...,"caps":["roll1"],"profiles":n,"shared":m}`): `profiles` is how many profiles the newcomer holds, `shared` how many of the others are shared; each a whole number 0 to 99, anything else reads as not said. Readers that predate them ignore the keys. - **Profile-sync keys** (each bounded before it is decoded, a bad value refusing the whole message): `refused` (the giver to the newcomer: why the share stopped, one of `newer-build`, `hosts-full`, `giver-nine`, `newcomer-nine`, `newcomer-full`, `code-expired`, `code-used`, `frozen`, `pin-needed`, `not-listed`, at most 32 characters; taken only from the record that is the newcomer's giver, opened under its own key, while no root is held); `donorDone` (a flag, from a newcomer to the host that gave it the profile, under its own key, when the donor role is over); `handoverAsk` (a flag, from a newcomer to a host that is not its giver, asking for the profile's cards). - **The add, by any host.** A host that holds a root and is listed in it signs the `add` for a device it linked once that device has answered; `P` in the statement is the root's author (the origin's key), the author is the host's own, the `seq` is reserved on disk first (§ above), and the transfer flag is set for a target the host is transferring to (step 8 sets it; nothing in step 7 does). The origin still signs only while its writer switch is on; a host that was given the profile has no switch of its own. - **The handover.** The giver hands the newcomer the whole roll, root first, and the usual first-answer sequence follows (profile sync of the cards and own card, the profile's travelling settings and door, group rosters, the history walk). The newcomer takes a root as a handover only from the record it was linked by (stamped when the link was made), within a week of it, with no root held, opened under that record's own key; `P` is read from the root and the root must verify under it; the check that the roll lists this device runs once the statements are in (after every roll message and at the retry sweep): it lists it with the prekey this device sent and not past the tenth place, and a share into a device that already shares nine is refused unless the add carries the transfer flag and the profile had one host. A roll that never lists this device within 10 minutes, lists it with another prekey, or lists it waiting is dropped whole. A root from a record without that stamp keeps the strict rule above (root `P` equals the sender's identity, and the root lists this device). - **The donor role** ends when the newcomer's history is complete (the `J1857` G / `J2198` completeness check found nothing short) and it holds a session with every other host in the roll; it then sends `donorDone` and the giver stops counting itself its donor. - **Another host carries on.** A newcomer asks its giver first (two minutes after the handover began, and again after a short answer); once the giver has been silent for 10 minutes it asks the next host it holds a session with (the others in key order, round again). The same question is the history heal (`J2198`), plus `handoverAsk` to a host that is not the giver. A host answers only for a host the roll lists, admitted within a week, at most once in 10 minutes per newcomer; the newcomer accepts the cards and history only from a sibling the roll lists while its own handover is open. - **The code** (`Receive a Profile`): valid while its screen is open and at most 10 minutes (a scan completing later is refused and leaves no record), and bound to the first giver that pairs on it (a second giver's record is removed). Not on the wire. **Transfer, as built in step 8** (`J1866e`; `HostTransfer`, `MessageStore+HostTransfer.swift` / `MessageStoreHostTransfer.kt`). **No wire change:** a transfer is the step-7 share (an `add` with its transfer flag, kind 1) followed by the giver's own `leave` (kind 2), both existing statements, spread like any other (§7.1). What step 8 fixes: - **No key is copied.** A profile *travels* when it holds a root or this build writes one (`HostTransfer.travels`). For it, `TransferSnapshot` (identity secret, prekey secret, every session and ratchet book, the seen table) is never built or sent, nothing is frozen, and `TransferWire` parts are never sent. The receiving half of the old Transfer is unchanged. A profile that does not travel (every shipped profile while `HostRollWriter.enabled` is false) keeps today's Transfer. - **The giver keeps working as a host throughout.** It signs its `leave` when ALL hold: the roll lists the newcomer as a host; the donor role is over (`donorDone` received, §5.4); and, only when the giver is the P host (the root's author), every contact without `roll1` has had the newcomer introduced -- the giver's evidence is that it forwarded that contact's hello (§5.9) to the newcomer -- or 7 days have passed since the transfer began. Time relaxes only the last clause. - **The `leave` is delivered, then the profile comes off.** It is spread to every host and, as a version-3 list, to every contact on this build; it is also handed to the newcomer directly until a radio or the newcomer's mailbox takes it. The profile is removed when the newcomer has it and every contact on this build has been told the roll as it now stands, or 24 hours after signing. - **The transfer flag cannot ride in a root.** A root entry has no flag, so a transfer target is not listed in the root: when the only answered devices are transfer targets the root lists the giver alone (a roll of one) and the target is added by an `add` with the flag. That is what lets a profile held alone move into a device's tenth slot. - **State** (`host-roll.json`, optional keys, an older file reads): `moving` `{target, since, leaveSignedAt, leave, reachedNewcomer, leaveLanded}` and `helloForwarded` (64-byte `device + sender` entries, newest last, at most 1024, written only while a roll is held). A transfer cancelled before the `leave` is signed is a share. **Taking a profile off a host, as built in step 9** (`J1866e`; `HostTakeOff`, `MessageStore+HostTakeOff.swift` / `MessageStoreHostTakeOff.kt`). **No wire change:** the host's own `leave` (kind 2), signed by `signOwnLeave` and spread like any statement (§7.1). What step 9 fixes: - **Order.** Sign `leave` (a `seq` reserved on disk first); learn it; pass it to every host session and tell every contact on this build the roll (version-3 list); send it to each other host directly, mailed as well as sent nearby and exempt from the subscription gate (a security action); repeat on every sweep until delivered; then delete the profile. - **Delivered** is: at least one other host this device holds a session with reported the send as deposited or confirmed (never merely queued); or, when no other host can be reached, every contact on this build has been told the roll as it stands with the leave in it. After 24 hours the profile comes off regardless. - **Deleted** means `ProfilesStore.delete` (iOS) / `AppContainer.deleteProfile` (Android): the profile's folder, and the identity secret, prekey secret and MLS seed from the Keychain / sealed store, PINs, Secure Mode state and the notification extension's sessions. After it, the key that signed the leave exists nowhere on the device; a statement signed with a copy of it at a higher `seq` does not count (§4a.2 rule 2). - **Not offered** when the profile is the device's last, is locked, is moving (step 8) or is already leaving. Contacts on older builds (version-1 list) are not waited for: they do not read the roll. - **State** (`host-roll.json`, optional key, an older file reads): `takingOff` `{since, next, leaveSignedAt, leave, reached, landed, undecided, forced, warned}`. - **Step 9d: a departed host signs nothing.** `hostDeparted` is true when this device's own key is among the roll's removed keys. It then refuses to sign any roll statement (`signOwnRollStatement`), to run the writer sweep, to announce or summarise the roll, pass statements on, answer an ask or resend the roll (`hostDepartedIdle`: departed with no Take Off or transfer still delivering its leave), to share, transfer or serve a handover (`canShareFromHere`, `canServeHandover`), to renew through the old link, to introduce itself to a sibling, or to sign a bundle for a giver. The last-host decision's Take It Off needs `!heldByLock`. A transfer clears and saves `moving` before the profile is removed. - **Step 9b.** The 24-hour fallback needs another host in the roll that has not left (`otherHostsRemaining > 0`), or `warned` (this device was the only host when it began, and the person was warned); otherwise `undecided` is set and nothing is removed until the person confirms (`forced`) or cancels. A send's landed report is attributed to the leave it was started for and ignored otherwise. In a transfer (step 8) the giver is removed only when `reachedNewcomer` (the 24 hours relax only the contacts clause); after 24 hours without it `moving.stalled` is set and the person chooses Try Again or Cancel the Move. **Option B only** (the owner's open question, design §10): a host honours a distrust's *erase asked* only for itself and only 24 hours after first holding it, and not at all if it signs a distrust of the marker in that time. **Between hosts, as built in step 3** (`J1866e`; the wire details the design left open, chosen as the smallest that fits it). Carried in profile sync (§5.10, payload type 9) by keys older readers ignore, each bounded before it is decoded and a bad value refusing the whole message: - `roll`: a roll encoding (above) in base64, at most **40 statements and 16 KiB** raw per message, so a longer answer is several messages (a root of ten hosts, 1794 bytes, rides with others; a roll holds at most one root-sized entry). - `rollHave`: `[{"a": 64 hex author, "s": n}]`, at most 64, authors unique. `s` is **how many of that author's statements the sender holds without a gap**, counted from the author's first (`seq` 0 for `P`, whose root is its first; `seq` 1 for any other host): `s` = the highest `seq` such that every `seq` from the first up to it is held, and 0 for an author the sender holds something of but nothing contiguous. A hole therefore shows as an `s` below the highest `seq` held. A reader holding no root sends no `rollHave`. - `rollFrom`: the asker's own `rollHave`. "Send me what is after these": every statement whose author is not listed, or whose `seq` is above the listed `s`; the root (author `P`) is included only when `P` is not listed. An empty list asks for everything. - `caps`: `["roll1"]` on every roll message, and at the top level of the answer a device sends its giver (`deviceList` `{"v":1,"devices":[...],"label":...,"caps":["roll1"]}`; readers ignore the key). A reader is **behind** when the sender lists an author it holds nothing of, or an `s` above its own. It then sends `rollFrom` with its own summary, once per summary received. **An answer to `rollFrom` carries no `rollHave`** (two readers that cannot satisfy each other would otherwise ask each other for ever). A statement a reader did not have is passed on, with its summary, to every host session except the one it came from and except a removed key; a duplicate is dropped quietly. A host accepts **roll keys only from a link end that has answered** (the phone that linked it, or a device it linked that sent its bundle), **only when the envelope opened under that record's own identity**, and never from a key the roll has removed; any other session's roll keys are not read in this step (contacts read a roll in the next). A **root** is taken only from the record that linked this device (`isLinkedPhone`), opened under its identity, with root `P` equal to that identity and the root listing this device with **the prekey of a bundle it sent** (compared by identity and prekey, not by bundle bytes, because a platform may sign a bundle afresh on every send); the first root taken is the only one held, any other for that `P` is refused and counted. A **statement** is kept only when the roll already knows its author (a root host, a host, waiting, or removed), is verified by the core, and fits what a host keeps (below); a chain that arrives out of order is kept in passes, and what no pass admits is dropped and asked for again. (`J1866f`: a host keeps up to 257 statements per author -- one past the cap, so every reader sees an author over it whichever arrive first -- and 1024 in all; the roll's 512 is the core's, by rule 0.) When a key becomes removed the host tombstones that link (`J2527`) and drops renewals held for it (`J2545`) and stops sending to or reading from it; the records themselves stay until the steps that retire them. The roll is kept per profile as a sealed side file (`host-roll.json`); the roster the Shared Profiles screen shows is the core's hosts once a root is held and the profile has more than one, and the one-time lines (§14 of the design) are said once, on hosts that were neither the giver nor the newcomer, and never for what a root lists. ### 5.8d Freezing a profile's sharing (`J1866f`; core built, step 1; no app reads or writes it) Design: `designs/J1866f-lost-device.md` ("Build decision"). **No build sends any of this yet.** The core implements it (`profile_freeze.rs`, vector `35-profile-freeze`; no FFI yet). Any host may freeze a profile; while any freeze is in force no host shares or transfers it, and readers refuse newcomers (the club, below). **Every time is relay time (§5.8e); no rule reads a device clock.** **Statement** = `body | Ed25519 signature (64) by author`. Body, big-endian, each kind exactly its own size (signed: freeze 272, extend and lift 271, recovery lift 303): ``` "channel/profile-freeze-v1\0" (26) | P (32) | author (32) | seq (u32) | at (u64) | kind (u8) | salt (16) | relay time (u64) | relay signature (64) | payload kind 1 freeze: id (16) | days (u8, must be 7) kind 2 extend: id (16) -- the author's own freeze id kind 3 lift: id (16) -- the author's own freeze id kind 4 (withdrawn: the joint lift; refused as unknown, never reused) kind 5 recovery lift: freeze author (32) | id (16) -- signed by the profile's Master Key R ``` `seq` counts the author's freeze statements from 1. `at` is the author's clock, for display; no rule reads it. The relay token is §5.8e's, for the nonce `SHA-256("channel/profile-freeze-nonce-v1\0" | P | author | salt)[0..16]`; the nonce is not carried, so a token verifies only in a statement by its author for its profile, and the author's signature covers it. The domain label is distinct from every other message an identity key signs (checked by a unit test against each). **The freeze PIN is in no statement**: the freezing host checks it locally before signing an extend or a lift. A reader takes a statement (`check_freeze_statement`) only if it is well formed, for its `P`, every signature holds and its relay token verifies under the relay key it trusts. **In force** (`active_freezes(P, statements, hosts, recovery, relay key, now)`, the same answer in any order; `frozen` is true when that call refuses): 1. Only current hosts' statements count (the caller passes the hosts from §5.8c), and the recovery lifts of `recovery` -- the roll's ONE current Master Key (§5.8c `Hosts.recovery` with exactly one entry; none while it is unset or contested); one statement per body. 2. An author with more than 64 statements counts for nothing. 3. An author that signed two bodies at one `seq` counts for nothing from that `seq` on. 4. A statement counts only if its relay token verifies, no other statement of its author carries the same salt (one token used twice voids both), and its relay time is no more than 10 minutes older than that of its author's statement at `seq` - 1, when held. 5. A freeze is (author, id); two freezes under one (author, id): the lower `seq`. 6. Lifted by its author's lift of the id, or by a recovery lift naming it (counting under 2-4, R being held to the same rules as any author). A recovery lift by any other key -- an old R after a change, a host -- counts for nothing. Lifted is final. **A freeze ends only so**: by its 7 days, its author's lift, or the Master Key's lift. The joint lift by two hosts side by side is withdrawn (the owner, 9 Oct 2026: a thief who shared the stolen host to two devices of his own could use it to lift the owner's freeze). 7. Otherwise it runs from its relay time for 7 days (604,800 s); each extension of it by its author, in time order, made before the end it then had, moves the end to its own time + 7 days. 8. In force while `now` (a relay time) is before the end. Freezes stack: frozen while any is in force. The call is refused whole on more than 1024 statements, a `now` that does not verify, or any statement malformed, for another `P`, or with a bad host signature; a statement whose relay token alone fails is ignored. **The club** (`club_decision`): while frozen, a reader serves a host key only if it held that key as a host when the freeze first reached it (its own snapshot; statement dates play no part); a key it refuses is remembered and stays refused after the freeze ends. Why a thief holding one host gains nothing: extend and lift reach only their own author's freeze; no number of hosts lifts another host's freeze; the thief's freeze stacks with the owner's and the owner's Master Key lifts it; times are the relay's, so nothing is post-dated and every freeze the thief signed before a wipe ends within 7 days of his last relay contact; a flood or an equivocation silences only its signer. **Not covered, by design or not yet**: an owner with no Master Key waits out each freeze the thief renews while he keeps the stolen device online and unwiped; a key the thief added offline whose add reaches a reader only after the freeze ended is never refused. ### 5.8e Relay time (`J1866f`; core built; it is `J1817`'s signed time, which the relay already serves) A generic signed time, reusable by any feature that must not trust a device clock. **It is the stamp the relay already serves for erase after inactivity (`J1817`, `server/netlify/functions/time.mts`), one endpoint and one key.** The client sends `GET /v1/time` with a random 16-byte nonce as 32 **lowercase** hex digits in the `X-Channel-Time-Nonce` header (never the query string; the relay refuses any other spelling); the relay answers `{ "t": , "sig": }`, `sig` an Ed25519 signature under `TIME_SIGNING_KEY` over the UTF-8 string ``` channel-time-v1|<32 lowercase hex of nonce>| ``` The app parses that JSON as hostile input and hands the core `t`, the nonce it sent and the 64 signature bytes; the core's own form of a stamp (inside freeze statements, in vectors) is `time (u64) | nonce (16) | signature (64)`, and verification rebuilds the string above and checks it strictly. Nothing in the request or answer names a profile or a freeze. Times are whole seconds, the unit every freeze rule is written in. The relay's public key is a parameter of every core call; the apps pass the `J1817` key they already pin (`RELAY_TIME_KEY` in `relay_time.rs`, `RelayTime.swift`, `RelayTime.kt`; preflight holds the three equal). `accept_time(relay key, last seen, new)` refuses a time that does not verify or is older than the last one this reader accepted (persisted in protected storage), so replaying an old token cannot wind time back. At share time an app collects its mail, fetches a fresh relay time, passes it through `accept_time`, and judges the freeze statements it holds against it (§5.8d). For a freeze statement's token the nonce is §5.8d's derivation, so its hex is what the app sends; for a host-roll stamp it is §5.8c's (from the proof). **The latest relay time** (`J1866f`). Every relay time an app verifies (today: the `J1817` fetch of erase after inactivity) is also kept, through `accept_time`, as the device's latest relay time (`RelayTime.latestToken` on both platforms; a public relay-signed value, so ordinary preferences). The host roll reads it as `now` to decide whether a Master Key set by one of several hosts has waited out its 48 hours (§5.8c rule 9c). A device that has fetched none holds every such set pending. ### 5.8f The recovery key -- parts and derivations (`J1866f`; core `recovery_key.rs`; vector 36; no app reads or writes it) Optional, one per profile, held off every device (`designs/J1866f-lost-device.md`, "Recovery key"). This section fixes only the secret, its parts and what it derives; the bundle is §5.8h; the `recovery` roll statement is §5.8c's kinds 6 and 11; what is posted to the recovery mailbox is §5.8l. **The secret** is 16 bytes from the device's CSPRNG, supplied to the core (which reads no random source for it). **The parts** are SLIP-39 exactly as published (satoshilabs `slip-0039.md`): one group (group threshold 1, group count 1) of `n` member shares with member threshold `k`, `1 < k <= n <= 16`, default **3 of 5**; extendable flag 1 (so RS1024 uses `"shamir_extendable"` and the Feistel salt prefix is empty); iteration exponent 1; empty passphrase. Each part is 20 words. Fixed random bytes give fixed words: the identifier (2 bytes, masked to 15 bits), then `k - 2` free shares of 16 bytes, then the digest share's 12 random bytes, the reference implementation's draw order. A reader accepts any SLIP-39 set (two-level groups, 256-bit secrets) but refuses an iteration exponent above 5, more than 16 parts, a part of more than 1024 bytes of text or more than 33 words, all before allocating; a rebuilt secret that is not 16 bytes is not a recovery key. SLIP-39 requires exactly the threshold count of parts per group, and the same part entered twice is a duplicate member index: both are refused. The official SLIP-39 vectors (`vectors/slip39-official.json`) all hold. **Placement** (`plan_ok`): paper parts >= `k`, device parts < `k`, paper + device = `n`. **Derivations**: HKDF-SHA256 (RFC 5869) with an empty salt and 32-byte output unless stated. | output | IKM | `info` | |---|---|---| | Ed25519 seed of R | the 16-byte secret | `channel/recovery-v1/signing` | | R | -- | the Ed25519 public key of that seed (RFC 8032) | | bundle sealing key | the 16-byte secret | `channel/recovery-v1/bundle` | | recovery mailbox tag, 16 bytes | **R** (32 bytes) | `channel/recovery-v1/mailbox` | The mailbox tag is derived from R rather than from the secret because every host and every contact must collect from that mailbox while holding only R. Anyone who learns R can therefore find the mailbox; it learns nothing it can open there. ### 5.8g Sealed order carriage (`J1866f`; core `order_carriage.rs`; vector 37; no app reads or writes it) How a profile's orders (§5.8c roll statements, §5.8d freeze statements, and the recovery key's orders) travel through any CHANNEL device on every route without naming the profile (`designs/J1866f-lost-device.md`, "Sealed order carriage"). The seal adds privacy, not authority: every statement inside is verified by its own section, exactly as if it had arrived any other way. **The carriage secret CS** is 32 bytes from the root host's CSPRNG, given to each new host inside the sealed share and never to a contact. **Keys**: `PRK = HKDF-Extract(salt = "channel/carriage-v1", IKM = CS)`; seal key = `HKDF-Expand(PRK, "order-seal", 32)`; tag key = `HKDF-Expand(PRK, "order-tag", 32)` (HKDF-SHA256, RFC 5869). **Tag**: `tag(e) = HMAC-SHA256(tag key, u32 e big-endian)[0..16]`, where `e` is the relay day (§5.8e time / 86,400, as a u32). A host computes it for `e` and `e - 1` (there is no `e - 1` at 0). **Blob** (exactly 1,024 bytes): ``` tag(e) 16 | nonce 24 | XChaCha20-Poly1305(seal key, nonce, aad = tag(e), plaintext 968) -- 984 bytes plaintext = u16 L | list (L bytes, L <= 966) | zero bytes to 968 list = one or more ( u16 len (>= 1) | statement ) ``` The nonce is 24 fresh random bytes for every seal, supplied by the caller (the core reads no random source); hosts re-seal at every epoch change and on every new order, so one order set never repeats a ciphertext. A reader refuses a blob that is not 1,024 bytes, whose tag is neither `tag(e)` nor `tag(e - 1)`, that the AEAD refuses, whose `L` exceeds 966, whose padding holds a non-zero byte, whose list is empty, or whose statement lengths are zero or run past the list. **Carrying**: every device keeps at most **256** blobs, none older than **30 days** of relay time since it first held it, deduplicated by SHA-256 of the whole blob. One connection may add at most **8** new blobs (a duplicate costs nothing). When full, blobs past 30 days go first, then one chosen by the caller's random draw. A blob that opened for a profile this device hosts (or one of its own sealed orders) is kept in a separate protected set of at most **32**, oldest out first, which a flood cannot reach. On every connection, on every route, a device pushes its blobs -- both sets together, ordered by hash and rotated by a random offset, so the order reveals nothing about which matched -- up to **16** on Bluetooth, **64** on Wi-Fi Direct and the local network, **256** on the Internet, whatever profile the connection is under, and never says which blobs matched. A device opens at most **64** matching blobs per connection. ### 5.8h The recovery bundle (`J1866f`; core `recovery_bundle.rs`; vector 38 and RFC 9180's own vectors; no app reads or writes it) What a device given only the recovery key learns about its profile. Each host writes its own bundle, signed by its own identity key and sealed to a public key derived from the recovery secret, so hosts can write and only the key's holder can read; a hostile host can withhold, never rewrite. The symmetric "bundle sealing key" of §5.8f is not used for it. **The seal key pair**: `rs = clamp(HKDF-Expand(PRK_rec, "recovery-seal", 32))`, `PRK_rec = HKDF-Extract(salt = empty, IKM = the 16-byte recovery secret)` (the PRK of every §5.8f derivation), where `clamp` is RFC 7748 §5 applied explicitly: clear bits 0-2 of byte 0, clear bit 7 of byte 31, set bit 6 of byte 31. `RS = X25519(rs, 9)`. RS travels beside R in the roll's `recovery` statement (not specified yet). **Body** (big-endian), signed by the host's Ed25519 identity key (strict verification): ``` "channel/recovery-bundle-sig-v1\0" (31) | P 32 | host key 32 | counter u64 | relay time 88 (§5.8e) | u32 n | roll (n bytes, §5.8c's roll encoding, n <= its maximum) -- the statements verbatim | u16 c (<= 4096) | c x ( contact key 32 | u16 len (1..4096) | card ) -- sorted by key, unique | CS 32 signed = body | signature 64 ``` The signer signs nothing but a well-formed body whose host is its own key. A reader bounds every length before reading it, and refuses trailing bytes. **Seal**: HPKE base mode, RFC 9180: DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, ChaCha20-Poly1305, to RS, `info = "channel/recovery-bundle-v1" || R`, empty AAD, sequence 0; the ephemeral key is `DeriveKeyPair(ikmE)` from 32 random bytes the caller supplies. Sealed form: `enc 32 | ciphertext`. *The design text binds P in `info` as well. A device recovering from the words alone does not know P (learning it is what the bundle is for), and P in the clear would link the recovery mailbox to the profile at the relay, so P is bound by the host's signature instead and checked against the root.* The implementation must pass the official RFC 9180 vectors for this suite (`vectors/hpke-rfc9180-x25519-chacha.json`, Appendix A.2.1, all 257 encryptions and 3 exports). **Opening** checks, in order: the sealed length bound, the AEAD, the body's structure, the host's signature over it, and the relay time under the relay key the caller trusts. **Slot**: a host posts its bundle to the recovery mailbox (§5.8f) under `HMAC-SHA256(key = mailbox tag, host key)[0..16]`, replacing only its own, with a higher counter. **Union** (on the recovering device, against the profile's root): bundles naming another P are dropped; every roll statement any remaining bundle carries that §5.8c accepts for P is taken once by body hash, keeping those whose author is *named* (`J3747`), exactly as §5.8c rule 0a names it: listed by the root, or added, set or changed to as a recovery key (kinds 6, 8, 11), or re-rooted to (kind 10), by a named author (repeatedly), so the Master Key's own evictions and re-roots are kept; the roll is evaluated; a bundle whose signer is not one of its hosts is dropped, and of one host's bundles only the highest counter (then the newest relay time) counts. The roll's evaluation is §5.8c's, so a host whose bundle carries more than 256 statements of its own is removed (rule 0) and its bundle is not kept, rather than the union failing. **Contact cards, by majority** (`J1866f`, 9 Oct 2026): each kept host's bundle is one vote for the version it carries of each contact key (a host that carries no card for a key does not vote). The version carried by strictly more kept hosts than any other is the card, and a key on which some host was outvoted is reported. On a tie at the top no version is chosen: the key is reported with every version and the hosts carrying each (most hosts first, then by bytes), the app marks the contact "check before messaging", and the recovered device sends it nothing until the person confirms one. When more than one host's bundle is kept, a card only one host carries is reported the same way (single-source: a thief could plant a contact no one else has). When exactly one host's bundle is kept, its cards are returned as they are and the whole recovery is marked single-source, unconfirmed. Relay time and counters never decide between different contents -- a thief's host signs a newer relay time as easily as any other. **CS** by the same rule: the value carried by strictly the most kept bundles; on a tie none is chosen, the conflict is reported with the tied values, and an outvoted value is reported. ### 5.8i Attested photo, iPhone (`J1866f` step 5a; core verifier built 11 Oct 2026, no FFI or app yet) A fresh camera photo may carry proof that it was taken just now, by this phone, inside the genuine app (`designs/J1866f-lost-device.md` section 4). iOS half: Apple App Attest. Android Key Attestation is step 5b. Core: `mesh-core-rs/src/attested_photo.rs`; vector `49-attested-photo-statement`. - **Statement.** The camera key signs, through an App Attest assertion, `"channel/attested-photo-v1" || SHA-256(image) || u16be len || relay time token (5.8e) || new profile identity (32) || recipient key (32) || u32be capture_ms_after_token`. `clientDataHash` = SHA-256(statement). - **Attestation, once per key.** Its challenge is the `clientDataHash` of the first statement the key signs, so no server is involved. The receiver checks it as Apple's validation guide says: - the x5c leaf and intermediate chain to the pinned Apple App Attestation Root CA (SHA-256 `1cb9823b...c932`), at the relay-token time, never the receiver's clock (a leaf lives about three days); - nonce, key id, rpId = SHA-256(TEAMID.bundle), counter 0, aaguid `appattest` (`appattestdevelop` only when development builds are accepted), credentialId. Beyond Apple's list: the COSE key equals the leaf key, and the CA flags are checked. - **Assertion, per photo.** ECDSA P-256 with SHA-256 over nonce = SHA-256(authenticatorData || clientDataHash). The rpId is checked, and the counter must be greater than the last one seen for that key (the caller keeps it). **Believed, not measured:** Apple publishes no real assertion, so "SHA-256 over the nonce" (as other verifiers do it) must be confirmed on a device before an app relies on it. - **Receiver, otherwise.** It also checks the relay token (5.8e) and its age, and that the recipient is itself. Any failure shows no badge and never a warning. It proves when, and with what, the picture was taken, never who is in it. ### 5.8j Attested photo, Android (`J1866f` step 5b; core verifier `attested_photo_android.rs` built 11 Oct 2026, no FFI or app yet) The statement and its hash are 5.8i's (`photo_statement`, `statement_hash`, re-exported), so both platforms sign the same bytes. **Attestation, once per key.** The key is generated in Android Keystore with challenge = SHA-256(first statement), after that statement is known, so no attestation predates its relay token. The receiver does not choose the challenge: the attestation proves "generated after this token, for this first statement". Later photos reuse it, each with its own token and recipient binding (Android cannot re-attest an existing key). **The receiver verifies** (Google, source.android.com/docs/security/features/keystore/attestation): - 2 to 6 certificates, the last carrying a pinned key. Roots by SHA-256 of DER, fetched 11 Oct 2026 from android.googleapis.com/attestation/root: RSA-4096 `cedb1cb6dc896ae5ec797348bce9286753c2b38ee71ce0fbe34a9a1248800dfc`, ECDSA P-384 `6d9db4ce6c5c0b293166d08986e05774a8776ceb525d9e4329520de12ba4bcc0`. Anchored by key, not by exact bytes, because Google's older chains end in certificates that carry the same key. - Each certificate is signed by the next, names match, top down. Signatures are ECDSA P-256 or P-384 with SHA-256 or SHA-384, and RSASSA-PKCS1-v1_5 with SHA-256 only under the pinned root. - CA, pathLen and keyCertSign are enforced, and a non-CA batch certificate is refused (strict RFC 5280; the Keymaster 3 era is excluded). - Validity is judged at the relay-token time, never a device clock. - No serial is in Google's revocation list (`attestation/status`, hex serials, fetched by the app at most daily, directly from Google rather than through the relay). - Every certificate is framing-checked (each length fits its parent) before `x509-cert` parses it. The same check runs on 5.8i's chain. **KeyDescription** (OID 1.3.6.1.4.1.11129.2.1.17), in the leaf only: - both security levels TEE or StrongBox, never Software; - the challenge as above; - hardwareEnforced: origin Generated, purpose includes Sign, EC on P-256; - RootOfTrust: deviceLocked, boot state Verified; - attestationApplicationId names our package, and at least one listed signing digest is ours; - the key's active and expire window holds at the token time. **Photo signature:** ECDSA P-256 over SHA-256(statement), DER (`SHA256withECDSA`). **Believed, not measured:** the digest and DER encoding, until confirmed on a handset. ### 5.8k The Master Key's per-profile keys -- slots and the public-slot cache (`J3544e` stage 1; core `master_key.rs`; vector 64; no app reads or writes it) One Master Key per person (`designs/J3544e-master-key.md` R4.2): the §5.8f secret, generated, shown once as SLIP-39 parts. Each profile that gets it uses its own **slot**, so two profiles of one person show contacts two unrelated `R`s. Nothing here changes §5.8f or §5.8h; they run unchanged on the profile's secret `m_P`. ``` m_P = HKDF-SHA256(salt = empty, IKM = the 16-byte Master Key, info = "channel/master-key-v1/profile" || u16 BE slot, L = 16), 0 <= slot < 1024 R_P, its seed, the bundle key, the mailbox tag = §5.8f on m_P rs_P, RS_P = §5.8h's seal pair on m_P ``` A slot at or above 1,024 is refused (701). **Drawing a slot** (the core reads no random source): the caller's random bytes, two at a time, big-endian, masked to ten bits; a slot the caller lists as used, or already drawn in this call, is skipped; at most 4,096 random bytes and 1,024 used slots, both checked first; refused 702 if the bytes run out. **Finding a slot**: a device holding the parts and a profile's `R` derives slots 0-1023 until one matches (711 if none); a device without the profile computes all 1,024 mailbox tags. **The public-slot cache** (kept on a device, never sent): `version (1) = 1 | count u16 BE <= 64 | count x (slot u16 BE | R 32 | RS 32)`, entries in draw order, exact length, no slot twice, every `R` a valid Ed25519 point; anything else is refused (705-709) before anything is allocated beyond the bound. Taking an entry removes the FIRST; the caller stores the remainder before using it. It holds no secret, so its integrity is the device store's; with the parts in hand a device re-derives every entry (712 on a mismatch). ### 5.8l What is posted to the recovery mailbox (`J3544e` stage 2; core `recovery_mailbox.rs`; vector 65; no app reads or writes it) The Master Key's orders, for anyone who holds `R`, and how a device with only the parts finds the bundles. ``` CS_R = HKDF-SHA256(salt = empty, IKM = R, info = "channel/recovery-v1/orders", 32) posting = §5.8g's blob, exactly 1,024 bytes, under CS_R at epoch 0, with a fresh random nonce address = HMAC-SHA256(key = mailbox tag, "channel/recovery-orders-v1")[0..16] item = a roll statement signed by a Master Key (kind 8, 9 or 10) | a recovery lift (§5.8d kind 5) | "channel/recovery-locator-v1\0" (28) | host key (32) -- a locator ``` **The seal hides the profile from the relay, which sees a mailbox address and a fixed-size blob; it hides nothing from a holder of `R`, and it grants nothing.** Every host and contact holds `R` and must read these, the evicted device above all. Each statement is checked by its own section as if it had come any other way. Epoch 0 is fixed because the address does not rotate: a device away for months must still find the posting, and rotating a tag would hide nothing from a relay that already sees the address. **A writer** refuses any other item (802), so nothing else is posted here by mistake. **`pack`** splits at most 64 items into postings: a re-root first, then evictions, changes, lifts, locators, each group by SHA-256, each posting filled in turn; duplicates are one. So every holder packs one set alike and what must arrive soonest comes first. **A reader** refuses what §5.8g refuses, skips and counts an item it cannot read so one bad item cannot hide the others, and opens at most 64 postings per collection. **Who posts, and for how long.** The device that signs an order posts it. Every host that holds an order posts it again every 3 days with a fresh nonce (the relay keeps a deposit 7), for as long as the roll holds it, so an evicted device that returns after months still finds it. A host also posts a locator for itself. The mailbox is an ordinary append-only one: a holder of `R` can add junk and cannot remove anything, within the relay's mailbox cap. **Locators fill a gap in §5.8h,** whose slot is `HMAC(mailbox tag, host key)`: a new phone rebuilt from the parts knows no host key, so without a locator it could not fetch a bundle. A locator is unsigned; a false one costs one fruitless fetch, because a bundle verifies under its own host's key and §5.8h's union decides among hosts. A new phone reads each of the 1,024 candidate addresses of §5.8k once. ### 5.9 Device hello (`payloadType 10`) How a contact's phone and a linked device come to share a session without either ever meeting. The contact has the device's prekey (§5.8) but no session; the device has its prekey secret but has never heard of the contact. The phone that linked the device holds sessions with both, so the hello travels through it. `body` is UTF-8 JSON: ``` { "v": 1, "device": "", "sender": "", "ephemeral": "<32 bytes, base64>", "sealed": "" } ``` The **contact** sends it to the phone under the contact session. The **phone** checks that `sender` is the contact it came from and that `device` names one of its linked devices, and forwards the body byte for byte to that device under the device session; it cannot open `sealed` and does not need to. The **device** accepts only from the phone that linked it and only when `device` is itself: it runs `PrekeyAgreement` as recipient with `ephemeral` and its prekey secret, derives the contact session (§6.8), opens `sealed` — which both proves the derivation and carries the contact's name and picture — and records the contact at the Linked tier. Never filed, never notified. ### 5.10 Profile sync (`payloadType 9`) A phone's contacts, for one of its own linked devices (`DECISIONS.md` J320, J387). One direction only, phone to device, under the session the link ceremony made. `body` is UTF-8 JSON: ``` { "v": 1, "contacts": [ { "id": "", "card": "", "name": "…", "given": "…", "middle": "…", "family": "…", "second": "…", "company": "…", "cover": "…", "phones": [ "…" ], "emails": [ "…" ], "blocked": true }, … ], "removed": [ "", … ], "me": "", "meCard": { "id": "", "card": "self", "name": "…", "given": "…", … , "phones": [ "…" ], "emails": [ "…" ] } } ``` Three optional keys, each ignored by a reader that predates it: - **`blocked`** (`J1863`) is present only when true: the card is blocked on this profile, on every device of it. - **`me`** (`J1857` stage F): the sending profile's display name. A profile made to receive this one takes it while it still carries the placeholder name. - **`meCard`** (`J1903`): the sending profile's **own card**, in the entry shape. It has at most twenty phones and twenty emails, each value at most 254 characters, each name part at most 100, and a payload breaking any of these bounds is refused whole. The receiver takes each name part the sender has filled and adds each value it does not already hold, **with discovery off**. Whether a value is published belongs to one identity per slot (`J1036`), and handles never travel (`J520`). It is sent with the whole list and whenever the own card's entry changes, **including when no other card has changed**, so a profile with no contacts still names its linked devices. At most **thirty** entries in either list per payload; a longer list is sent as several payloads. A sender sends the whole list once, when a device first answers with its bundle, and afterwards only the cards whose entry has changed, or a removal. **Notes never travel** (`J324`). A receiver accepts only from the phone that linked it: a card it already holds — matched by identity, or by `card` for one never paired — takes the phone's fields; one it does not hold is created unpaired, carrying the identity that a later hello (§5.9) attaches keys to; a removal deletes the card and its thread. Never filed, never notified. **Asking for the device list** (`J2577`, device to origin): a profile sync from a linked device may carry `"rosterAsk": true` and nothing else, from a device that holds no list of the profile's devices. The origin answers only a linked device that has answered with its bundle, no more than once a minute per device, with the usual `devices` roster to that device alone; a device asks no more than once in ten minutes. Earlier readers ignore the key. **First-contact requests reach every device of the profile** (`J2581`, both directions; origin to the devices it linked, a device to the origin, which sends the union on). A request is left at a published value's slot and read with that value's collection capability; the relay deletes nothing on collection (`J102` s4(b)), so any holder of the capability reads every invitation for its seven days. Two optional keys on a profile sync carry the rest, **never to a contact** (`LEGAL-RISK.md` section 9, `J105`; a capability is an HMAC credential and travels only inside this sealed channel): - `"slots": [{"v": "", "c": ".<64 hex>"}, ...]` -- a whole snapshot of what the sender collects at: at most 20, values unique and at most 254 characters, each capability at most 128 bytes and of the form `.`. A receiver replaces what it held FROM THAT SENDER, drops a lapsed capability, keeps the later expiry where two devices offer one value, and holds at most 40. It **polls** those slots and never publishes a prekey there. The origin sends the union (its own values, then those its devices told it); a device sends its own. - `"settled": [{"i": "<32 lowercase hex>", "k": "<64 lowercase hex or empty>", "ask": true?}, ...]` -- at most 30 requests answered on the sender. `i` is the relay's id for the invitation (the first 16 bytes of the SHA-256 of the bytes deposited), `k` the sender's identity key. A receiver drops every request with that id **or** that sender (one person is one request) and remembers `i`, so an invitation it collects later is not filed. With `"ask": true` nothing was answered: the sender holds a request it cannot open (its first message is sealed to the prekey another device published), and a device that holds the request and could open it accepts it; every other copy is dropped. The origin passes new answers on to its other devices, except the sender. Only the device the profile came from accepts every request on its own (`J1972`). Both keys are ignored by earlier readers, which therefore go on collecting only where they hold the capability. **Between a person's own devices only, device to origin** (`J1866c`, `designs/J1866-step3-coequal-removal.md`): a profile sync from a linked device may carry `"revoke": {"id": "<8 lowercase hex: the first four bytes of a device's identity key>", "at": }`, asking the origin to revoke another device of the profile. A request outside those bounds refuses the whole payload. The origin applies it only when the sender is a device it linked that has answered with its bundle, the core opened the envelope under that device's own identity, exactly one other linked device carries the id and it is not the origin, and `at` is no more than 600 s ahead, no more than 7 days old, and no more than 600 s before that device's link was made in person; it then revokes that device exactly as its own Revoke does (unlink notice, tombstone, §5.8 list to every contact, roster to every device left). Earlier readers ignore the key. **The unlink notice** (a policy update, §5.5, `{"v":1,"unlinked":true}`) gains `"at"`, seconds; a receiver refuses one written more than 600 s before the link it would end, and takes one without `at` as before. **A §5.8 list is taken only when the envelope opened under the person's own session**, never one of their device sessions. **A view-once item spent on one device** (`J2866`, between a person's own devices, either direction): a profile sync may carry `"spent": [{"c": "", "m": ""}, ...]`, telling the profile's other devices that each named view-once item (§5.27, and a held view-once file) was revealed, and so spent, on the sender. **What `c` and `m` name** (device-local conversation and message UUIDs differ on every device, so they cannot): `c` is the lowercase hex of the 32-byte identity key of the WRITER of the item (a one-to-one thread's contact, or the authenticated member of a group), and `m` is the lowercase hex of the writer's 16-byte message id; only inbound view-once items are named. A receiver marks each item spent exactly as if it had spent it itself and deletes its copy and key at once; an item it does not hold is remembered as spent, so a copy that arrives later is never shown. Bounds, all checked on the array before any entry is read, any breach **refusing the whole payload**: at most **30** entries (the same cap as `contacts` and `removed`; a longer list is sent as several payloads); each of `c` and `m` a JSON string of 1 to **64** bytes, every byte printable ASCII (0x21 to 0x7E); each entry exactly the two keys `c` and `m`; no `(c, m)` pair twice. An empty list is the same as no key, and any other value of `spent` (null, an object, a string) is refused. Key order inside the JSON is not significant (the body is JSON, not canonical CBOR). The note carries only ids and travels only inside the sealed profile-sync channel to the person's own devices, never to a contact. Earlier readers ignore the key and keep spending per device. The profile-sync body is read by the apps alone (the core never parses it), so there is no core codec: `vectors/52-profile-sync-spent.json` is the conformance file, `mesh-core-rs/tests/conformance.rs` holds the rule to it with a reference reader, and each app's reader is held to the same file. ### 5.10a A person's own devices keep the §5.8b chain; onward sharing (`J1866d`; PROPOSED, NOT BUILT) **SUPERSEDED by §5.8c** (`J1866e`, the owner, 8 Oct 2026): no second device approves a share, there is no removal authority and no permanent origin. Kept below only as the record of the proposal; build nothing from it. Design: `designs/J1866-onward-sharing.md`. **No build sends any of this yet; it is written before code, for review, and changes nothing a contact reads.** **The chain among one person's devices.** Every device of a profile stores the §5.8b chain, every link from genesis. Genesis is written by the origin (the device whose key is `P`) once every device of the profile advertises capability `chain1`, listing itself and every linked device that has answered, signed by `P` alone, and sent to each linked device; a device takes genesis only from its linking device, only when the envelope opened under that device's own identity, only when the root it is told is that identity, and only when the list carries this device's own key with the bundle it last sent. Contacts are not sent the chain: they keep reading §5.8 v1 from the origin's own session, and the origin builds that v1 list from its head (every device of the head with which it holds a session, less any device whose removal it has started and that still lacks its second signature). **Profile-sync keys between one person's devices** (§5.10's body; each optional, ignored by an earlier reader, every value bounded before decoding, a value out of bounds refusing the whole payload). Accepted only from a session whose envelope opened under a key of the receiver's head, except genesis and a newcomer's first `chainLinks` and `root`, which come from its linking device: | key | value | |---|---| | `chain` | base64 of one §5.8b list (a commit or genesis), at most 5,062 bytes decoded | | `chainLinks` | base64 of a §5.8b listing encoding (at most 128 links) | | `chainFrom` | 64 hex: SHA-256 of the asker's head body; the answer is `chainLinks` after it | | `root` | 64 hex: `P`, from the linking device to a newcomer only | | `propose` | `{"list": base64 candidate signed by its proposer only, "label": "", "at": seconds}` | | `decline` | `{"prev": 64 hex, "seq": n}` | | `intro` | `{"to": 64 hex key, "code": base64 §6.7.2 v4 pairing code}`, forwarded unchanged by a device holding sessions with both | | `resolve` | base64 listing of the chosen branch of a fork, from its fork point | **Adopting a link**: `meshcore_device_list_v2_verify(head, link) == accept`. An add is additionally refused unless one of its signers is not its proposer. **A proposal is shown to the person only when** it opened under a device of the head; the core answers `Quorum` (17) against this device's head (or, for a one-device head, `Accept`); it carries exactly one signature, by that device; the core's change report is exactly one added key, nothing removed, no bundle changed; the proposer is not being removed; the new key is not this device's, not on another card and not tombstoned; the result has at most 10 devices; `at` is at most 600 s ahead and 24 h old; this device has not signed another child of the same parent; it is the proposer's only open proposal and at most its third in 24 h. Allow re-runs every check, records `(prev, body hash)` before signing, signs the body with this device's key, and sends the commit to every device of the new head it reaches. **A device never signs two different children of one parent.** Only after adopting the commit does the linking device send the newcomer `chainLinks` from genesis with `root`, and only then does it share the profile's contents. **Automatic co-signatures** (no person asked), never of an add or of another device's bundle: a link whose only change is removing its proposer; the origin co-signing a device's §5.10 `revoke` request (never one removing the origin); any device co-signing the origin's own revoke of another device. **None of these takes a head from two devices to one** except the first. **Sibling sessions.** A device of the head without a session to another device of the head sends it an `intro`: a §6.7.2 v4 invitation from its own prekey to the target's bundle as listed in the head. The target takes the session, with no person asked, only when the invitation's identity is a key of its head, not tombstoned and not its own; its sender prekey equals that key's chain entry byte for byte; its first message opens; its ephemeral key has not been seen; and no live session with that key is held. Anything else is dropped, never filed. The origin forwards contact hellos (§5.9) to any device of its head it holds a session with. **A fork** (two different children of one parent, found by `verify_pair`, by `Sibling` against the head, or by `Replay` for a link whose `prev` is a held link's hash and whose body differs from the held link at that `seq`, the other branch verifying from that parent) freezes proposing and signing on every device that sees it, until the person chooses a branch (`resolve`); devices on the other branch roll back to the fork point and adopt the chosen links. Never tie-broken. **A device that adopts a link tombstoning its own key** ends every link to the profile's devices, tombstones them for repair (`J2527`) and drops held renewals (`J2545`). A key tombstoned in the chain is never admitted again; a removed device receives the profile again only as a new device identity. **Core additions** (step 1 of the design's plan): `meshcore_device_list_v2_sign(body, seed)`, which refuses bytes that do not decode as a §5.8b body, and `meshcore_device_list_v2_changes(held, candidate)`, which reports added keys with bundles, removed keys and changed bundles and judges nothing. ### 5.11 Wipe (`payloadType 11`) A phone telling one of **its own linked devices** to erase itself (`DECISIONS.md` J320, J407). One direction only, phone to device, under the session the link ceremony made. `body` is UTF-8 JSON: ``` { "v": 1, "at": } ``` A receiver acts on it **only when the sender is the phone that linked it** (`isLinkedPhone`), and then destroys its store key, its identity keys and its files exactly as the distress code does, and ends its process. A device that is not a linked device ignores it; so does a device receiving it from any other contact. Nothing is acknowledged: the device that obeys has nothing left to answer with, and a receipt would be a way to learn that a wipe landed. **Best effort by construction, and the interface must say so.** A device that is off, offline, or already erased never receives it; the mailbox drops it at the 30-day ceiling like any other message. Removing the device from the phone (`J386`) is the reliable act — it stops new messages reaching the device at once and needs nothing from it — and the wipe is the extra that may or may not arrive. ### 5.12 Reaction (`payloadType 12`) One small emoji attached to one message (`DECISIONS.md` J403). `body` is UTF-8 JSON: ``` { "v": 1, "to": "", "e": "" } ``` `to` names a message by the sender's `messageId` (§5.1a) — **whichever side sent it**, so a reaction to one's own message and to the other person's are the same shape. `e` is a single emoji from the set the apps offer, or the empty string, which removes whatever this sender had put there. **One reaction per sender per message**: a second one replaces the first rather than adding to it. A reaction naming a message the receiver does not hold, or one that has expired or been deleted, is dropped silently — it is not an error and there is nothing to tell the sender. A reaction is **not a message**: it does not change a conversation's sort order, its unread count, or its last line, and it raises no notification. Reactions ride the ordinary sealed envelope, so a relay sees one more envelope it cannot read and cannot tell apart from a message. ### 5.13 Contact share request (`payloadType 19`) and disposition (`payloadType 20`) `DECISIONS.md` J664 and J664a. **Sharing somebody else’s card asks them first**, and the approved card then travels **from its owner**, so consent is inherent in the transmission rather than recorded beside it. *Implementation (`J3317-cardwire`, 3.089): `mesh-core-rs/src/card_share_wire.rs` reads and writes both bodies (`vectors/67-card-wire.json`), in shadow beside the apps. Body at most 64 KiB, at most 256 card fields, JSON nesting at most 64. No byte on the wire changes.* Two types, never one with a flag. A request carries somebody’s card; a disposition carries a yes or a no. A receiver that read one as the other would either hand out a card nobody approved or file an approval as a card. Both bodies are **UTF-8 JSON the apps own**, like the contact card (§5.7) and for the same reason: what a card contains is a product decision that changes, and freezing it into the wire format would make every field a protocol revision. **Request** — requester → the card’s owner: ``` { "v": 1, "rid": "", "to": { "n": "", "r": "" }, "card": [ { "l": "