@forgesworn/fold-kit 0.9.0 → 0.12.0

package/docs/live-persistent-admission.md

@@ -0,0 +1,192 @@
+# Live persistent admission, version 1
+
+This profile lets a first-time device obtain a persistent room's signed
+invitation without claiming that a mesh cache contains complete history. It is
+a new, opt-in exchange. Existing v3 stored invitations, legacy live delegation,
+and the epoch desk are unchanged. The codecs alone do not enable offline joining.
+
+## Authority and the remaining gate
+
+Only the root inviter pinned by the original persistent link may answer. The
+answer supplies the existing signed kind 1463 envelope and a current epoch hint;
+it supplies no delegation, inviter key or current epoch secret. A delegate or
+cache cannot assert that an invitation has not been retired.
+
+Before making an answer, the host must recover its durable invitation lifecycle
+and room epoch state, including pending writes, retirement, closure, earliest
+room end and sticky self-destruct policy. It serialises the final state check,
+answer construction and handoff with retirement, rekey and closure. An old
+export or a keeper file without lifecycle evidence cannot become ready merely
+because it contains the root key. A host with unknown, pending, corrupt, retired,
+closed or expired state refuses. Key possession alone is insufficient.
+
+The existing keeper v2 file does not record a complete invitation lifecycle or
+an atomic pending transition. Host integration therefore needs a versioned
+durable journal before enabling this profile across a cold start. Older state
+must not be silently interpreted as proof of an active invitation. Multiple
+independently writable copies of a root key cannot provide global freshness
+while partitioned; this profile requires one logical authority writer with
+exclusive durable ownership. Restoring an old backup needs explicit recovery.
+
+A verified answer is evidence of the root's state at the time it was signed,
+not a lease guaranteeing the room cannot change afterwards. Retirement learned
+locally always wins, even over a newer answer. A response already in transit
+cannot be recalled. A copied bearer/envelope already reveals epoch zero;
+retirement cannot erase it. No offline protocol defeats a lying root or hidden
+revocation indefinitely.
+
+After the exchange the client must run an authenticated, current epoch desk
+exchange **even for an epoch-zero hint**, before roster, chat or forwarding.
+The current client's settle delay / expected-epoch fast path is insufficient
+for this entry mode. A hint is a minimum recovery target, never a current-key
+grant. An unknown participant stays pending for the existing admission decision;
+the new challenge must not call `letIn` from an unproved name or participant key.
+Removal, access policy and device credential checks remain the epoch desk's job.
+The client stays non-publishing if this gate cannot finish. Rekey racing the
+gate retains the room's existing authenticated transition rules and limitations.
+
+## Routing descriptor
+
+The original invitation URL remains intact. Alongside it carry a separate
+base64url-without-padding UTF-8 JSON descriptor, at most 512 encoded characters:
+
+```json
+{"v":1,"room":"<root room id>","invitation":"<derived invitation id>","inviter":"<pinned root public key>"}
+```
+
+All three values are 64 lowercase hex characters. These are the only fields.
+Encoders use the displayed order without whitespace. Decoders accept JSON field
+order differences but require minified JSON that round-trips through JSON.stringify
+without changes. They refuse duplicate fields, whitespace, unknown fields,
+non-canonical base64url and wrong invitation/authority. The decoded JSON is at
+most 384 bytes. The expected room is checked again against the authenticated
+response and the decrypted kind 1463 envelope. A modified descriptor can deny
+discovery but cannot substitute a room. Derive the existing nearby scope/UUID
+from this root room ID; never advertise the bearer or original URL. The room ID
+and persistent discovery scope reveal correlation. This descriptor is routing
+metadata, not admission evidence. A client must select Nearby before parsing it
+into any transport; signed relay hints never override that route.
+
+The first implementation exposes the descriptor separately; it does not invent
+a new universal-link envelope that an old app might open through the internet.
+App QR/share integration must preserve the original link and explicit route.
+
+## Wire exchange
+
+Reuse ephemeral kinds 20466 / 20467 with a distinct encrypted profile. This
+allocates no MeshCore data type. No public relay publication is required.
+Integers are nonnegative safe integers; timestamps are Unix seconds. All hex
+fields are lowercase. Signatures are checked without trusting cached verdicts.
+Tags contain exactly one two-element `d`, `p` and `expiration`, no others;
+ordering does not matter to readers. Writers emit that order.
+
+The requester generates a fresh one-use secp256k1 key and signs kind 20466.
+`d` is the existing bearer-derived invitation ID, `p` the root inviter,
+`expiration` is `created_at + 90` as canonical decimal. Its NIP-44 v2 plaintext:
+
+```json
+{"v":1,"profile":"persistent-live","room":"<expected root room id>","requester":"<event pubkey>"}
+```
+
+The symmetric request key is HKDF-SHA256(bearer, empty salt,
+`kithmoot/v1/persistent-live/request-key`, 32). The body has exactly these fields, in minified JSON that round-trips through
+JSON.stringify without changes (field order may differ). The same rule applies
+to the response body, rejecting duplicate fields and ambiguous number spellings.
+An event ID binds all request fields and acts as the challenge identifier.
+Retries use that same event; a new user attempt uses a new key and randomness.
+The host rejects a request over 90 seconds old, more than five seconds in the
+future, or at/after its expiry. Legacy request decoders use another key and
+cannot treat this request as a delegation request.
+
+The root signs kind 20467, addressed by the same `d` and the requester's `p`.
+Its expiry is `min(request.expiration, response.created_at + 30)`. Its NIP-44
+conversation key is derived from the root secret and requester public key.
+Plaintext, with exactly these fields:
+
+```json
+{"v":1,"profile":"persistent-live","request":"<request event id>","room":"<expected root room id>","epoch":0,"invitation":{}}
+```
+
+`invitation` is the complete existing signed kind 1463 event, with exactly its
+seven wire fields (`id`, `pubkey`, `created_at`, `kind`, `tags`, `content`, `sig`).
+Do not re-sign it merely to answer a retry. The response's `epoch` is the host's
+current nonnegative safe integer epoch, separately returned as `epochHint`;
+the decoded persistent invitation still opens epoch zero.
+
+The requester validates its original live request, matches its private reply
+key, verifies the pinned root signature, exact tags and expiry, decrypts, and
+checks the exact request ID, profile, room and bounded embedded event. The
+response may be at most five seconds earlier than the request (clock skew),
+at most five seconds ahead of local time, and must not be expired. Its expiry
+must equal the formula above. The signed invitation must decrypt under the
+original bearer, name the expected room, and be neither future-dated beyond
+five seconds nor ended. End/relay/self-destruct semantics are unchanged.
+No malformed response escapes as an exception or supplies another authority.
+
+Legacy v2 grants, delegated responses, cached kind 1463 alone, another request's
+answer, and an answer from an earlier attempt cannot satisfy this exchange.
+The decoder is stateless: the request owner must consume success at most once,
+remove its subscription and delete the ephemeral key on success, cancel or
+timeout. Do not persist reply keys for restarting a challenge.
+
+## Resource and transport limits
+
+Before cryptography, bound request content to 2,048 characters and complete
+request JSON to 4,096 UTF-8 bytes; response content to 16,384 characters and
+complete response JSON to 20,480 bytes. An embedded invitation is at most 8,192
+UTF-8 bytes, content at most 6,144 characters, eight tags, four strings per tag,
+each at most 256 characters. Bound complete raw input before parsing JSON;
+`parseLivePersistentEvent` provides that raw boundary and requires minified JSON
+without duplicate fields. Typed-event decoders can only bound the already
+allocated event object they receive.
+Refuse oversize envelopes instead of trimming relay policy or authority fields.
+
+The exchange owner allows one outstanding challenge per device/room, a
+90-second monotonic deadline, and at most three identical offers at 0, 10 and
+20 seconds. Retries must fit inside the cached response's 30-second lifetime:
+the previously specified 0/30/60 schedule could recover a lost request but
+could never recover a lost response. The shared-mesh integration exposed this
+on 2026-10-09. Response bytes and expiry remain unchanged; an expired response
+is never re-signed to extend it. Wall-clock rollback cancels it; time changes never extend the
+monotonic deadline. Silence is unavailable, not admission or an automatic
+internet fallback. There is no cache-complete/EOSE substitute.
+
+The responder deduplicates at most 128 request IDs for their remaining lifetime
+and stores at most one signed reply per accepted request. Admission refuses at
+capacity instead of evicting live guards. Each retry rechecks lifecycle state
+and expiry before reoffering identical bytes. No re-sign on expiry. Global
+limits precede per-peer limits because fresh requester keys are cheap: at most
+16 accepted challenges and 64 KiB of reply offers per rolling minute per
+authority process, divided among at most eight active rooms. Limit pre-crypto
+input work too. A process restart must not reset these budgets. The authority's
+durable control ledger is separate from any radio airtime ledger.
+
+These are application bounds, not LoRa duty-cycle compliance. A radio route
+must reserve its own airtime and fragmentation budget and can decline a large
+reply. BLE qualification comes first. Native text-channel bridging continues
+to use its separate gateway identity and trust boundary. Ordinary mixed room
+transport does not forward these control messages automatically. A later
+transit owner must opt in to exact request/response selectors, directions,
+deadlines and quotas; no wildcard control forwarding.
+
+## Implementation and acceptance gates
+
+1. Independent TypeScript/Kotlin codecs and frozen deterministic wire vectors:
+   request and response bytes, descriptor, wrong bearer/root/room/request/key,
+   duplicate/extra tags and JSON fields, version/profile confusion, stale/future
+   times, malformed expiry, end/destruct/relay policy, oversized nested objects
+   and forged verification-cache flags. Preserve all existing protocol vectors.
+2. Request lifecycle with real mesh transport: all initial packets lost, retry,
+   cancel, no peers, last-moment response, clock rollback, process death,
+   duplicate answer and zero fallback sockets.
+3. Durable authority owner and exact retirement/closure/rekey transaction:
+   SIGKILL before/after persistence and handoff, old state migration refusal,
+   competing root owners, corrupt storage and requester-rotation floods.
+4. Actual fresh RoomSession admission and encrypted chat over mesh, with the
+   mandatory authenticated epoch gate and existing unknown/removed policy.
+   No delegation appears and no pre-gate roster/chat leaves. Repeat after both
+   parties cold-start, and with explicit mixed-path forwarding.
+5. Native permission/route/share UI, offline network isolation and physical BLE
+   qualification. LoRa measurements and original radio restrictions remain
+   independent gates. Codec/vector success must never be labelled a completed
+   offline joining or radio result.

package/docs/member-epoch-catch-up.md

@@ -0,0 +1,346 @@
+# Member epoch catch-up
+
+Status: implemented in `src/epoch-commit.ts`, `src/member-epoch.ts` and two
+optional additions to `src/epoch.ts`. Unreleased. Vectors:
+`vectors/member-epoch-vectors.json`.
+
+## The problem
+
+Only the room's authority (the root inviter key, or a keeper hosting
+`hostRoomEpoch` with that key) answers an epoch request (kind 20468, answered
+with 20469). Requests are ephemeral, so a device that missed a rekey can
+recover only while the authority's device is online with the room open.
+
+What happened on 2 October 2026: room "The moot" was at epoch 1 and its
+creating phone was offline. A member's phone had rejoined with a new device
+key. Stored rekeys seal only to the devices that were present, so none of
+them sealed to the new key, and the phone stayed at epoch 0. Call bells
+(keyed per epoch), chat and presence silently stopped crossing between
+devices at epoch 0 and devices at epoch 1. A desktop online at epoch 1 held
+the secret the phone needed, and nothing let it pass that secret on in a
+form the phone could check.
+
+## What the existing format already proves, and the one gap
+
+A rekey into epoch j+1 (kind 1462) is signed by the authority. Its content
+is NIP-44 v2 under epoch j's key, and NIP-44's HMAC verifies under no other
+key. So a third party holding a candidate secret for epoch j can derive
+`deriveEpoch(j, secret).key`, decrypt the authority-signed rekey j+1 and
+learn whether the candidate is genuine. **Every epoch that has a successor
+is therefore already committed to by an authority signature.**
+
+The current epoch N has no successor. Rekey N refers to secret N only
+through its per-device seals (NIP-44 between the authority and each kept
+device). Only the authority and that one device can open a seal. So the
+existing protocol cannot prove secret N to anybody else, and a member's
+answer for the top epoch cannot be checked. That gap is the reason for the
+one wire addition below. The rest of the scheme is the existing rekey
+chain, read in a new way.
+
+Alternatives considered and not built:
+
+- *A member reveals its NIP-44 conversation key with the authority* so the
+  requester can open the member's own seal in rekey N. This is ruled out
+  because that key also opens every future seal to that device. A requester
+  removed later could read the next secret through it, which defeats
+  removal.
+- *A member reveals only the per-message NIP-44 keys of its own seal in
+  rekey N* (the HKDF-expand output for that seal's nonce). This would work
+  for legacy rooms today, and it reveals nothing beyond that one message.
+  It was left out because it needs a raw ChaCha20 primitive that this kit
+  does not take as a peer dependency, and it works only for a member whose
+  device was sealed to at N. A member that caught up through a grant has no
+  seal to open. It remains an option if legacy rooms turn out to matter
+  more than the remedy below.
+
+## Wire additions
+
+All of these are additive. No existing event changes byte-for-byte unless a
+caller opts in, and no existing body version changes.
+
+### 1. The epoch commitment (inside the rekey body)
+
+```
+commit = hex( HMAC-SHA256( key = secret_N,
+                           msg = "kithmoot/v1/epoch-commit:" + roomId + ":" + N ) )
+```
+
+`roomId` is lower-case hex and `N` is decimal. `encodeRekeyEvent({ commit:
+true })` writes it into the encrypted body after `by` and `closed` and
+before `keys`. The body stays `v: 1`: a reader from before this change
+ignores the key, and the label carries the version. It sits inside the
+ciphertext rather than in a tag, so a relay still sees only the room id,
+the epoch number, the authority and a size. The commitment is used nowhere
+else on the wire. A removed member who reads rekey N (it holds key N-1)
+learns a PRF output of secret N, which gives it nothing to locate epoch N
+traffic with. The epoch id would have done that, which is why the
+commitment is not the epoch id.
+
+Without `commit`, `encodeRekeyEvent` produces exactly the 0.4.0 event (the
+`roomEpoch/rekey` vector still reproduces byte for byte).
+
+### 2. Member epoch request, kind 20471 (ephemeral)
+
+- Tags: `["d", roomId]`, plus the NIP-40 `expiration` of a conference room.
+  It has no `p` tag because no single answerer is addressed.
+- Signed by the asking device.
+- Content: NIP-44 v2 with the conversation key
+  `HKDF-SHA256(roomKey₀, info = "kithmoot/v1/member-epoch-request-key", 32)`,
+  where `roomKey₀` is the epoch-0 room key.
+- Body: `{"v":1,"credential":<device credential>,"proof"?:<kindred proof>,
+  "admission":<epochRequestAdmission(...)>,"have":<the asker's epoch>}`. The
+  admission proof is the existing one, binding room, authority, device and
+  `created_at`. Members hold `roomKey₀` and check it exactly as the
+  authority's desk does.
+- Each retry is a fresh event with a new id (see "Anti-amplification").
+
+### 3. Member epoch grant, kind 20472 (ephemeral)
+
+- Tags: `["d", roomId]`, `["p", asking device]`, plus `expiration`.
+- Signed by a **one-time key** made for this grant alone and then dropped,
+  never by the answering member's device key, and NIP-44 v2 from that key
+  to the asking device. Nothing about a grant is trusted on its signer, so
+  a device key would add only a public line from the answering device to
+  the room id in `d`. A desk tells its own grants apart by event id. Vectors
+  record the 48-byte draw the key is made from, before the body nonce and
+  the signature aux-rand.
+- Body: `{"v":1,"request":<request id>,"epoch":N,"secrets":[base64url secret
+  for have+1 .. N],"rekeys":[the authority's kind-1462 events for have+1 ..
+  N]}`. One grant carries at most 32 epochs (`MAX_MEMBER_EPOCH_CHAIN`).
+
+There is no member refusal event. A refusal from a member is a claim the
+requester cannot check, so members decline by not answering. Only the
+authority's 20469 refusal means anything.
+
+## Verification rules (requester, `decodeMemberEpochGrant`)
+
+The requester is at epoch `k` and holds key `k`. It accepts a grant only if
+all of these hold:
+
+1. The kind is 20472, the signature is valid, the event is fresh (within 90
+   s), `d` is the room, `p` is this device, and the body opens with this
+   device's key. `request` is one of this device's own outstanding member
+   request ids.
+2. `secrets` and `rekeys` have the same length L, with 1 <= L <= 32, and
+   `epoch = k + L`.
+3. If the requester has seen a valid rekey up to epoch E, then `epoch >=
+   E`. This blocks a rollback: a member removed at E still holds secret E-1
+   and could otherwise keep the requester one epoch back on a key it shares.
+   `decodeMemberEpochGrant` takes E as `expected`; `memberEpochSource` (and
+   so `requestRoomEpoch({ members })` and `requestMemberEpoch`) subscribes to
+   the room's kind-1462 events and sets E itself, from `peekRekeyEvent` on
+   whatever the relays replay, raised further by any `expected` the caller
+   passes. Its first request waits for that replay to end (EOSE, or 1.5 s
+   at most), so a member cannot answer before the floor is known. A relay that withholds rekey E from the
+   requester while serving it a removed member's grant can still hold it at
+   E-1, so a client should keep watching rekeys after it settles, as it
+   already does to learn of the next one.
+4. For each j = k+1 .. N, in order:
+   - `peekRekeyEvent(rekeys[j])` returns j. That means kind 1462, the
+     authority's signature, this room and an epoch tag of j.
+   - `rekeys[j]` decrypts under key j-1. For j = k+1 that is the
+     requester's own key. Later ones derive from the offered secret j-1. A
+     decryption failure means the offered secret j-1 is not the one the
+     authority encrypted under, and the grant is refused. **This is what
+     proves every secret except the last.**
+   - The body is `v: 1` with `epoch: j`. If it is `closed`, refuse. If its
+     `removed` names the requester's participant, refuse. Otherwise its
+     removals are added to the cumulative set.
+   - At j = N the body must carry `commit`, equal to
+     `epochCommitment(roomId, N, secret N)`. If it is absent, refuse: that
+     is a legacy epoch, and only the authority can hand it on. **This is
+     what proves the last secret.**
+5. Result: `{ epoch: { epoch: N, secret: secret N }, removed: known ∪ every
+   removal in the chain }`. `removed` is cumulative, with the same meaning
+   as the authority grant's. Nothing names the member that answered: its
+   grant was signed by a one-time key.
+
+The answering member's identity plays no part in correctness. The trust
+root is the authority's signatures plus the key-committing NIP-44 MAC and
+the commitment. A member, a relay or a stranger can withhold an answer.
+None of them can make a requester accept a secret the authority did not
+issue, an epoch it did not sign, or a removed list it did not write.
+
+The first grant that passes all of these wins (`memberEpochSource` stops on
+it). `requestRoomEpoch({ members })` races it against the authority's grant
+and settles on whichever verifies first. An authority refusal still
+rejects the call.
+
+## Desk rules (`hostMemberEpochDesk`)
+
+A member answers a request only when all of these hold:
+
+- the request decodes: fresh, credentialled for this room, with a valid
+  admission proof under `roomKey₀`, and passing the room policy if one is
+  given;
+- the room is not closed (`closed()`). Otherwise it calls
+  `onRefused('closed')` and stays silent;
+- the requester's participant is not in this member's cumulative removed
+  set, which it learnt from the authority's rekeys. Otherwise it calls
+  `onRefused('removed')` and stays silent;
+- once anybody has been removed (the removed set is not empty), the room
+  knows the requester's participant (`known(participant)`): on the
+  authority's latest member list, in the current roster, or let in from
+  this device. Otherwise it calls `onUnknown` and `onRefused('unknown')`
+  once per participant (again a minute later if they are still asking, `reportUnknownEvery`) and stays silent; the requester's next ask is looked at
+  afresh, so letting them in is making `known` say yes. See "The
+  known-members gate" below;
+- this device is in step (`current()` is defined) and ahead of `have`;
+- it holds every secret and every authority rekey from `have + 1` to its
+  own epoch (`secretAt`, `rekeyAt`), and the chain is no more than 32 long;
+- when it can read the last rekey itself (it holds the key before it), that
+  rekey carries a commitment. A member that joined at the current epoch
+  cannot check this, so it sends the grant and the requester decides;
+- the serialised grant fits its byte budget (`maxGrantBytes`, default
+  60000, under the 64 KiB many relays enforce). The grant inlines whole
+  rekey events, each with one seal per kept device, so a long chain in a
+  large room can outgrow a relay's limit, and such a chain is left to the
+  authority. The requester can already fetch the durable 1462s from its
+  relays, so a later revision could carry rekey ids in place of the events.
+
+The requester re-checks everything, so a desk bug cannot weaken anything.
+At worst it costs bandwidth.
+
+## The known-members gate (#207)
+
+The admission proof is made under `roomKey₀`, which a removed member still
+holds. Refusing by participant alone is therefore undone by a fresh
+participant key and a credential for it: to a desk, that is a newcomer
+with the link. An honest member who was offline through a rekey, and a
+removed member back under a new key, hold exactly the same keys, so no
+key-based rule tells them apart. What does is whether the room has seen
+the participant before.
+
+So once a room has removed anybody, the authority's desk (`hostRoomEpoch`)
+and every member desk grant only to a participant the room knows
+(`known`). Anybody else is sent to approval: the authority answers
+`refused: 'unknown'`, which is not final (`requestRoomEpoch` keeps asking
+and calls `onUnknown`), and a member desk stays silent. A member letting
+them in makes `known` say yes, and the requester's next ask is granted.
+A room that has never removed anybody behaves exactly as before, and a
+desk given no `known` lets nobody through after a removal.
+The authority sends a participant `unknown` at most once a
+`reportUnknownEvery`, after a random wait, within a cap on refusals a
+minute (see `docs/quiet-replies.md`).
+
+Where a desk learns who is known is the application's business, with two
+sources here: `encodeRekeyEvent({ members })` writes the authority's
+member list into the rekey body (`RekeyNotice.members`,
+`RekeyEvidence.members`, and the newest one in a chain as
+`MemberEpochGrant.members`), and the authority's own grant can carry it
+(`hostRoomEpoch({ members })`, `EpochGrant.members`). The list is every
+participant the authority knows to be in the room, not only those present
+as it rekeys; the encoder drops removed participants from it. It is
+inside the body, sealed under the epoch being left, so a removed member
+reads the list in the one rekey that removed them, as it reads that
+rekey's removed set. They saw the same people in that epoch's roster.
+
+What this does not do: in a room whose link is still live, a removed
+person can come back through the invitation as anybody holding the link
+can, and then knocks like any stranger. Removal plus a replaced link, or
+removal in a room that asks before letting people in, now keeps them out.
+
+## Anti-amplification
+
+- Each desk waits a random `[0, jitterMs)` (default 1500 ms) before
+  answering.
+- If, during that wait, it sees another device's 20472 addressed to the same
+  requester, it stands down. It cannot read that grant and does not need
+  to.
+- It stands down **at most once per requesting device**. The requester sends
+  a fresh request every `retryMs` (default 4000 ms, a new id each time)
+  until something verifies, and on the second round every desk answers. A
+  stranger who posts junk 20472s to suppress honest answers therefore buys
+  one round's delay, not a denial of service.
+- Requests are deduplicated by id, and each desk answers a given request at
+  most once.
+
+## Threat model, and why confidentiality is not weakened
+
+What this protects is the epoch secret: the roster, chat, presence, call
+bells and media keys of an epoch. The parties involved are:
+
+- **A current member** already holds secret N and can leak it to anyone.
+  Handing it to an admitted, non-removed device gives that device nothing a
+  malicious member could not give it anyway. The member path adds no
+  capability an insider lacks.
+- **A removed member** is refused twice: by every honest desk (its removed
+  set comes from authority-signed rekeys), and by the requester's own
+  check, which refuses any chain that names it as removed. Its old link
+  still opens epoch 0, as it always did. With that it can read member
+  requests (sealed under a key derived from `roomKey₀`) and learn the
+  credential (participant and device) of a device asking to catch up. That
+  is the same in-room exposure a roster at epoch 0 always had, and it is
+  stated here rather than hidden. It cannot answer convincingly beyond the
+  epoch before its removal, and rule 3 refuses that answer once the
+  requester has seen the later rekey.
+- **A closed room stays closed.** A closing rekey seals to nobody, so nobody
+  holds a secret past it. Desks refuse, and a chain containing `closed` is
+  refused.
+- **A stranger** with the room id and the authority pubkey from a public
+  rekey cannot read a member request (no `roomKey₀`), cannot produce an
+  admission proof, and is never answered.
+- **A newly admitted device** that claims a low `have` is handed every
+  secret from there to the current epoch (up to 32), where the authority's
+  grant hands over only the current one. Verification has to start from a
+  key the requester already holds, and every admitted device holds the
+  epoch-0 key, so a desk cannot tell a device that really is at epoch 0 from
+  one that only says so. The member path therefore gives a newcomer that
+  passes the room's policy the keys to the history of earlier epochs, which
+  the authority path did not. Epochs exist to shut the removed out, not to
+  hide the past from the admitted, so this is accepted, but it is a
+  difference.
+- **Any holder of the link**, including a removed member, can open a member
+  request and read the asking device's credential and kindred proof: its
+  participant, its current device key, and that it is behind. The
+  authority's request shows that to the authority alone. For a removed
+  member this includes device keys made after its removal, which the epoch-0
+  roster it can still read does not.
+- **A relay** sees, per request, the room id, the asking device's pubkey and
+  a time. The existing 20468 already shows it exactly that, plus the
+  authority's pubkey in `p`. Per grant it sees the room id, the asking
+  device and a one-time key, so it learns nothing about which member
+  answered. Grant contents are NIP-44 to the requester's device, as the
+  authority's grant is.
+- **Forgery.** Without the authority's key, nobody can mint a rekey that
+  passes `peekRekeyEvent`. Without the real key j-1, nobody can find another
+  secret under which an authority-signed ciphertext decrypts (NIP-44's MAC
+  is HMAC-SHA256). Without inverting HMAC, nobody can find another secret
+  matching the commitment.
+
+What is weakened: nothing about confidentiality. The availability the
+authority's absence used to deny is what is restored.
+
+## Legacy rooms (rekeys written before `commit`)
+
+- A legacy rekey **in the middle** of a chain is fine: the next rekey's
+  decryption vouches for its secret.
+- A legacy rekey **at the top** cannot be vouched for by a member.
+  Requesters refuse such grants, and desks that can see the missing
+  commitment do not send them. The epoch stays authority-only, exactly as
+  today.
+- Remedy for such a room ("The moot"): once the authority's device runs a
+  version that writes `commit`, a single turnover rekey (no removals) makes
+  the whole history member-recoverable. The new top carries a commitment,
+  and every earlier epoch, legacy or not, is proven by its successor. Until
+  then the room behaves as it does today, and the authority path is
+  untouched.
+
+## API
+
+- `epochCommitment(roomId, epoch, secret)`, `EPOCH_COMMIT_PREFIX`
+- `encodeRekeyEvent({ ..., commit: true })`
+- `readRekeyEvidence(event, { roomId, authority, previous })` reads a rekey
+  with the key of the epoch it leaves, with no seal needed: `{ epoch,
+  removed, closed, commit? }`
+- `encodeMemberEpochRequest` / `decodeMemberEpochRequest`,
+  `deriveMemberEpochRequestKey`
+- `encodeMemberEpochGrant` / `decodeMemberEpochGrant`
+- `hostMemberEpochDesk(opts)` is the answering side
+- `memberEpochSource(opts)`, used as `requestRoomEpoch({ members })`, and
+  `requestMemberEpoch(opts)` are the asking side. Their `removed` (the set
+  the device already knows) is a function, asked on every grant, or any
+  iterable, read once when the source is made, so a generator is not used
+  up by the first grant.
+- `MEMBER_EPOCH_KINDS` (`{ REQUEST: 20471, GRANT: 20472 }`),
+  `MAX_MEMBER_EPOCH_CHAIN`

package/docs/mls-admission-v4.md

@@ -0,0 +1,84 @@
+# MLS admission v4 evidence codec
+
+Import from `@forgesworn/fold-kit/mls-admission`.
+
+This implements only the pure codec from the independently reviewed
+[Vennel design](https://github.com/forgesworn/vennel/blob/e9a90c6ae724138f15b377a0b22d022c56303bc5/docs/2026-10-11-mls-admission-codec-design.md).
+No relay I/O, browser admission, box role service, counter storage, vault signing,
+MLS Add or Welcome adoption is implemented here. Existing v2/v3 codecs stay
+unchanged; a v4 link is a separate three-element array fragment, not a legacy
+room traffic secret or an extended legacy link.
+
+`encodeMlsInvitationV4(root, bearer)` encodes a fragment. Supply a fresh valid
+root and 32 CSPRNG bytes, retain their custody, and wipe caller copies on settled
+termination. `readMlsInvitationV4(fragment)` returns root, invitation id and a
+caller-owned bearer copy. Zero bearers and invalid x-only keys are refused;
+these checks cannot establish the entropy of a supplied bearer.
+
+All core/proof inputs are canonical compact JSON of the fixed arrays defined
+in the design. Nested signed events are seven-field arrays. Outer wire inputs
+and outputs are compact JSON NIP-01 **objects**, with exactly seven fields;
+field order may vary, but duplicate keys, whitespace and alternate encodings
+are refused. Decoders accept strings only, so caller objects, proxies, accessors
+and cached-verification markers never cross the wire decoder boundary.
+
+1. Reserve a global durable counter, stable operation and challenge in the
+   actual owner before building the request array. Call
+   `mlsAdmissionProofTemplatesV4({fragment, core, now})` for the three purpose-bound
+   role templates and expected public keys. Settle the account/browser/enrolled
+   device signers inside actual custody. No sealed scalar or generic vault
+   signer should be exposed to satisfy this API.
+2. `encodeMlsAdmissionRequestV4({fragment, core, proofs, requestSecretKey, now})`
+   verifies those exact signed proofs, then encrypts with fresh NIP44 randomness
+   and signs using the one-operation ephemeral request key.
+3. `decodeMlsAdmissionRequestV4({fragment, event, localSecretKey, side, now})`
+   independently verifies the request at either endpoint (`side` is `root` or
+   `joiner`). Only this decoder issues `VerifiedMlsAdmissionRequest`.
+   `readMlsAdmissionRequestV4(handle)` returns immutable core/digest/event-id
+   strings for evidence; they cannot rehydrate its nominal identity.
+4. Construct the Allow array against that retained request, get its two keeper
+   proof templates with `{fragment, core, request, now}`, and settle actual
+   keeper account/device consent after exact current saved-room/leaf checks.
+   Deny has an empty proof array. Encode with
+   `encodeMlsAdmissionAnswerV4({fragment, request, core, proofs, rootSecretKey, now})`.
+5. `decodeMlsAdmissionAnswerV4({fragment, request, event, requestSecretKey, now})` returns
+   evidence-only `VerifiedAdmissionAnswer`. `readMlsAdmissionAnswerV4(handle)`
+   returns decision, core/digest and event ids. There is no constructor,
+   registration hook, capability conversion or admission factory.
+
+Verified handles retain only public root/invitation id and protocol evidence,
+never the invitation fragment, bearer or direction keys. Supply the fragment
+transiently to each answer operation; its root/id must match the retained request.
+Decoded owned fragment/bearer bytes are wiped on parse failure and on settled
+operation return. Only `readMlsInvitationV4` transfers its successful bearer copy
+to the caller. Immutable caller input strings cannot be overwritten by JavaScript.
+
+The engine device is the enrolled Nostr key named in its person credential,
+not the MLS leaf's Ed25519 signature key. All signed events are freshly verified;
+strict duplicate/tag/decimal/curve/credential checks apply across both roles.
+The application must still pass VMLS credential and binding policy, revocation
+checks, current clock/custody checks and typed consent.
+
+The application must obtain a fresh authenticated box/Link keeper witness with
+conditional keeper revision at the effect boundary, then consume each operation
+once in durable storage. This library cannot attest role, currentness, child
+revision, route, counter nonreuse, revocation, durable idempotence or saved-room
+truth. Root signature correlates the answer; it does not authorise a keeper.
+Repeated decoder calls can return fresh evidence handles; this is deliberately
+not a durable replay barrier. Same-answer replay must return existing operation
+state without repeated effects. Recovery fetches fresh custody/witness evidence
+and reconciles the existing operation with `findJoin`, never a second capability.
+Hold when the required vault or authoritative conditional service is absent.
+
+All ciphertexts use a 16,384-byte canonical padded wrapper and 21,936-character
+NIP44 payload bucket. Timing, carrier, invitation pseudonym/root, ephemeral
+request identity, event correlation, relay/network addresses and volume remain
+visible. There is no forward-secrecy claim. Do not log raw evidence, account or
+group ids, capability bytes or invitation/request secrets.
+
+`vectors/mls-admission-v4.json` uses synthetic public test keys and independent
+Node SHA256/HKDF composition, deterministic test-only Schnorr auxiliary bytes
+and NIP44 nonces. Production encoders expose no fixed nonce/randomness option.
+`npm run generate-mls-admission` deterministically regenerates that file;
+normal tests verify its frozen wire bytes without regeneration. Codec vectors
+and local tests are not browser, deployed, two-account or phone acceptance.