@forgesworn/fold-kit 0.9.0 → 0.12.0

package/docs/persistent-invitation-evidence.md

@@ -0,0 +1,135 @@
+# Persistent invitation evidence
+
+The additive `requestPersistentRoomAdmissionEvidence` API retains what an
+injected stored-event query observed, so protected clients can revalidate the
+signed source of a fixed relay list after restart. It performs no publication,
+storage or routing effects and supplies no relay defaults. The existing
+`requestPersistentRoomAdmission`, encoder, decoder and wire formats are unchanged.
+Import from `@forgesworn/fold-kit/persistent-invitation-evidence`; the existing
+main entry and its bundle budget remain unchanged.
+
+## A single creator source
+
+`revalidatePersistentInvitationSource({ event, invitation, expectedRoomSecret })`
+validates one actual `encodePersistentInvitation` Event, or the exact canonical
+carrier string retained from it. The exact 32-byte room-root pin is mandatory;
+missing, malformed or mismatching pins fail rather than disabling the check.
+The capability and root are copied before carrier verification, and temporary
+copies and derived keys are erased. The returned `admission.secret` is a fresh
+owned buffer that the caller must erase. Caller buffers are never erased.
+
+`PersistentInvitationSource` is a frozen envelope with `version: 1`,
+`invitationId`, `inviter`, `eventId`, `createdAt`, the canonical `event` string
+and owned `admission` fields. It authenticates the supported encoder's exact
+signature, inviter, invitation ID, root, end/expiration, destruction flag and
+relay list. Retirement events and noncanonical reload strings are rejected.
+The same plain-data boundary and 16,384-byte carrier limit below apply, with
+string bounds checked before parsing and object bounds before verification.
+
+This source has **no completion/EOSE claim**. It is not a query observation,
+latest-event selection, publication receipt, current membership authority or
+evidence of absence of retirement. A creator retains the canonical event,
+actual owner/fixed metadata and a bounded pending publication intent in
+acknowledged protected custody before opening any relay pool. After uncertain
+delivery it retries these exact event bytes without signing again or changing
+the timestamp. Every underlying write still needs a fresh client authority,
+generation and lifecycle guard. These storage and effect rules are client
+responsibilities; this validator performs no signing, relay I/O or storage.
+
+## Carrier and bounds
+
+`PersistentInvitationEvidence` version 1 contains `invitationId`, `inviter`,
+`completion: 'eose'`, sorted unique `eventIds` and corresponding `events`.
+Each event string is JSON in this exact field order:
+`id, pubkey, created_at, kind, tags, content, sig`. This preserves every signed
+field, tag order and ciphertext. It is an allowlisted representation of the
+Event supplied by the transport, **not the original relay wire JSON bytes**.
+The optional Nostr verification-cache symbol is discarded and never trusted.
+Unknown fields, non-data descriptors, custom prototypes, sparse arrays and
+noncanonical reload strings are refused. JavaScript proxies are outside this
+plain-data transport boundary; callers must not pass executable objects.
+
+Queries admit at most 64 delivered candidates, including invalid candidates and
+duplicates, with 16,384 UTF-8 bytes per canonical carrier and 262,144 UTF-8 bytes
+across all delivered canonical candidates. Work/bytes are charged before crypto;
+candidate 65 is refused before carrier copying. Retained evidence has the same
+limits. Event tags are bounded to 64 arrays of at most eight strings. These are
+evidence-profile limits, not new wire limits for the legacy API. Exact duplicates
+cost no additional retained capacity but consume query work and byte budget;
+the same ID with a different carrier fails the entire query. Capacity is checked
+before admitting another candidate, with no eviction or truncated success.
+Malformed/oversized object framing fails the query. Well-framed events that
+fail signature, capability or scope validation are ignored, never retained.
+
+Evidence records, carrier strings and ID arrays are frozen owned copies.
+String memory is not claimed securely erased. Each admitted result has a fresh
+owned secret buffer; callers erase it after use. Temporary decoded secrets,
+derived welcome/room keys and the query's invitation-bearer copy are erased.
+
+## Authentication and selection
+
+Both the query and `revalidatePersistentInvitationEvidence` recompute event IDs
+and verify signatures without a cached verdict, require the exact inviter and
+single two-element invitation `d` tag, and validate capability decryption and
+room derivation. Group bodies and tags must exactly match the canonical shape
+of the supported encoder, including the exact end/expiration, self-destruct
+and relay-list fields. An unknown group body cannot contribute authority.
+Authenticated retirements use the existing retirement semantics, including
+legacy-valid extended bodies, so stricter group parsing cannot weaken a known
+retirement. Every observed valid retirement carrier is retained.
+
+At EOSE the entire retained set is processed in sorted event-ID order:
+
+- Any observed retirement yields `status: 'held', reason: 'retired'`, with
+  its event IDs and no admission. No valid group event yields `unavailable`.
+- Different decoded room roots yield `conflicting-rooms`. The optional
+  `expectedRoomSecret` binds an existing physical room to its exact root;
+  a mismatch yields `wrong-room`.
+- The earliest end across all signed copies stands. Self-destruct is sticky
+  if any copy carries it. A copy without relays makes no relay-list assertion.
+- Relay-bearing copies with the greatest `created_at` select the list.
+  Different lists at that greatest timestamp yield `conflicting-relays`
+  regardless of arrival order; identical lists are accepted. A strictly newer
+  list can supersede an older tie. The legacy API still keeps first arrival
+  on a tie, preserving existing compatibility.
+
+An admitted outcome exposes `contributors.room`, `.ends`, `.destruct` and
+`.relays` as exact event-ID arrays. The aggregate can combine assertions from
+several events; it is not represented as a single synthetic signed envelope.
+Held results still retain the complete observed evidence for protected refusal
+custody and later independent revalidation.
+
+## Completion and failure
+
+The query waits for the transport's EOSE even after an invitation or retirement
+arrives. Timeout, abort, subscription failure, contradictory duplicate or
+capacity failure rejects with `PersistentInvitationEvidenceQueryError`.
+Its bounded `observation` is explicitly `completion: 'incomplete'`, diagnostic
+custody only. The revalidator always refuses incomplete observations. They
+cannot be relabelled to establish completeness; completion metadata itself is
+local and must be protected by the client's custody transaction.
+
+The query is exact to the two source kinds, inviter and invitation `d` ID.
+EOSE binds that local query observation and the listed event identities. It
+does not prove that a relay disclosed every retirement or competing event,
+global non-retirement, current membership, freshness or current routing
+permission. Revalidation after restart proves signed historical consistency
+within that retained set. The same room under a rotated invitation has a
+different invitation/evidence identity and cannot alias this record.
+
+## Client integration remains required
+
+Clients must retain the exact selected invitation capability and evidence in
+protected storage, bind them to the physical room root, and await durable
+coherent retention before using decoded fields. A `held` or incomplete result
+never grants permission to dial, publish, migrate, clean up or resume admission.
+Creator paths must separately prepare and retain the exact signed event with
+owner/access bindings, fixed list and publication intent before network effects,
+retrying uncertain delivery with the same event. This API does not fabricate
+EOSE for a locally prepared event.
+
+Browser/tab coherence, capacity and client/version fences, selected-lane
+consent, supported legacy-row reconciliation, startup ordering, current
+authority and actual app/physical acceptance remain client integration work.
+This additive library API alone does not activate KithMoot protected recovery,
+close DG08 or satisfy authentic MLS admission/independent continuity gates.

package/docs/quiet-replies.md

@@ -0,0 +1,81 @@
+# Quiet automatic replies
+
+Unreleased. A desk that answers automatically, at once, under a key that does
+not change, tells anybody who can make it answer when the device holding
+that key is online and how quickly it responds. A removed member still holds
+the epoch-0 room key, and anybody with a temporary link holds its bearer, so
+both can ask as often as they like. This is the timing side channel
+described as "Careless Whisper" for silent delivery receipts.
+
+None of what follows changes an event's content, tags or kind, and no
+vector changes. It only changes whether a reply is sent, and when.
+
+## The authority desk (`hostRoomEpoch`)
+
+On by default.
+
+- **Every answer waits.** Grants and refusals alike wait a random
+  `replyDelayMs` first, default `[500, 2000]` milliseconds
+  (`DEFAULT_REPLY_DELAY_MS`). If only refusals waited, the wait itself would
+  give the answer away. The desk decides when the wait ends, not when the
+  request arrived, so a removal or a rekey during the wait applies. Closing
+  the desk cancels every wait. `[0, 0]` answers at once, as before.
+- **A refusal goes out once per participant per window.** A `removed` or
+  `closed` refusal is sent at most once every `refuseAgainAfter` seconds,
+  default 3600 (`REFUSE_AGAIN_AFTER_SECONDS`). An `unknown` refusal is sent
+  at most once every `reportUnknownEvery` seconds (default 60, the same
+  cadence that already limits `onUnknown`). A request inside the window gets
+  no reply, and its asker times out with the plain "not answering" error
+  rather than `EpochRefusedError`.
+- **Refusals are capped in total.** At most `maxRefusalsPerMinute`
+  refusals of any kind go out in any 60 seconds, default 20
+  (`MAX_REFUSALS_PER_MINUTE`). Anybody can mint a participant key, so a
+  per-participant limit alone would not stop a room-key holder asking as
+  somebody new each time.
+- **Grants are never limited.** A participant who is granted is forgotten
+  by the limiter. Letting an `unknown` participant in still works on their
+  next ask, because a grant is never held back.
+- **Memory is bounded.** The limiter remembers at most 256 participants
+  (`REFUSAL_LIMITER_CAPACITY`) and forgets the oldest first. The
+  per-minute cap still holds after that. No more than 256 requests wait at
+  once, and a request turned away while the queue is full is answered when
+  it is retried.
+- `onRefused` and `onUnknown` still fire on the desk for a refusal the
+  limits kept off the wire, so an application sees everything it saw
+  before.
+- `random` and `schedule` can be injected for tests.
+
+## The temporary-link responder (`hostRoomInvitation`)
+
+Off by default. Without the new options, nothing waits, no subscription is
+added, and grants are published exactly as before.
+
+- `grantDelayMs: [min, max]` waits a random time in that range before every
+  grant, after `admit` when one is set. This is for a device that answers
+  without asking anyone.
+- `coordinate: true` is for a room where several delegated devices answer
+  the same link. Each one waits (`grantDelayMs`, default `[500, 2000]`),
+  watches for grants to the same requester (kind 20467, the link's `d` tag,
+  the requester's `p` tag) from any other key, and stands down if one
+  appears. Normally only one device answers. It cannot read the other
+  grant, and does not need to.
+- Anyone holding the link could post a false grant, so a responder stands
+  down at most once per request. It then forgets the request, so the
+  requester's next retry of the same request is answered without asking
+  `admit` again.
+- No more than 256 grants wait at once; a request turned away while the
+  queue is full is answered when it is retried.
+
+## The member desk (`hostMemberEpochDesk`)
+
+Unchanged. It already waits a random `[0, jitterMs)` (default 1500 ms),
+stands down once per requesting device when another member answers, and
+publishes nothing for a refusal (see `docs/member-epoch-catch-up.md`,
+"Anti-amplification").
+
+## What this does not hide
+
+A desk that answers at all still shows that some device holding its key is
+online at some point in the window. The delay hides how quickly it answers,
+and the limits stop a key holder polling it. It does not make the desk's
+presence invisible.

package/docs/room-destruct.md

@@ -0,0 +1,142 @@
+# Self-destructing rooms
+
+Status: 0.9.0. The wire format for KithMoot's room self-destruct: a room
+whose devices, when it ends, delete what they wrote and forget the room.
+This release adds only the flag and its readers. It deletes nothing itself:
+the tidy-up (NIP-09 deletions, blob deletions, local wipe) is the client's.
+
+## The flag
+
+`destruct: true` rides in three places, each one already signed by the
+room's authority (the root inviter):
+
+| Event | Where | Encoder | Reader |
+|-------|-------|---------|--------|
+| Group invitation (1463) | encrypted body, after `ends`, before `relays` | `encodePersistentInvitation({ destruct: true })` | `PersistentRoomAdmission.destruct` |
+| Invitation retirement (1461) | plain JSON content, after `ended` | `encodeInvitationRetirement({ ended: true, destruct: true })` | `decodeInvitationRetirementNotice(...).destruct` |
+| Closing rekey (1462) | encrypted body, after `closed` | `encodeRekeyEvent({ closed: true, destruct: true })` | `RekeyNotice.destruct`, `RekeyEvidence.destruct` |
+
+Each is `true` or absent. Omitted, or passed as `false`, every event is
+byte-identical to 0.8.0's.
+
+### The group invitation
+
+The body order is `v, room, secret, ends, destruct, relays`. `destruct`
+without `ends` is valid: a room with no fixed end self-destructs when its
+authority closes it.
+
+- **Strict, as `ends` is.** `decodePersistentInvitation` refuses the whole
+  envelope (null) when `destruct` is present and not `true`: `false`,
+  `"true"`, `1` and `null` are all refused. The encoder never writes them.
+- **Never a tag.** The NIP-40 `expiration` tag is unchanged; nothing on the
+  outside of the event says the room self-destructs.
+
+### Two signed copies
+
+`requestPersistentRoomAdmission` reads every stored copy of the invitation
+before it admits. When two copies disagree on `destruct`, the flag sticks:
+any valid copy from the authority that says `destruct` makes the admission
+`destruct: true`, whichever order the copies arrive in.
+
+This is the rule `ends` already follows ("the earlier end stands, so a stale
+copy can never keep a room open longer"): for a claim that limits the room,
+the more limiting copy wins, regardless of timestamp. A stale or careless
+copy can never keep a room's content alive. Only `relays` follows
+newest-wins, because relays are a routing preference rather than a limit.
+The three merge independently: earliest end, sticky destruct, newest relays.
+
+The consequence is that an authority cannot take back a self-destruct by
+republishing the invitation without it. It can only close the room.
+
+### The retirement
+
+An ended room's retirement may say the room self-destructs:
+`{"v":1,"ended":true,"destruct":true}`.
+
+- **Only beside `ended`.** The encoder throws on `destruct` without `ended`,
+  and `decodeInvitationRetirementNotice` reports `destruct` only beside
+  `ended: true`. A retirement whose flag is missing, malformed or without
+  `ended` is still a valid retirement (a retired link must stay retired); the
+  flag is simply not believed.
+- **Not encrypted.** Unlike the other two, the retirement's content is plain
+  JSON, as `ended` always was. It names no member and links no rooms: the
+  event is signed by the inviter key and tagged with the invitation id, which
+  nobody without the link can tie to a room. What it does tell a relay is
+  that whoever holds this link was in a room that self-destructed, the same
+  order of fact `ended` already gives away. A client that does not want even
+  that can leave the retirement unflagged: the invitation and the closing
+  rekey carry the flag inside the encryption, so members learn it without
+  the retirement.
+- `retirementError` is unchanged: a joiner is told the room was ended.
+
+### The closing rekey
+
+The body order is `v, epoch, removed, (by), closed, destruct, (scheduled),
+(commit), (members), keys`. A closure seals the next secret to nobody, so
+`keys` is empty.
+
+- **Only beside `closed`.** The encoder throws on `destruct` without
+  `closed`. With `scheduled` it throws twice over: `scheduled` refuses a
+  close, and `destruct` needs one.
+- **Not believed without it.** `decodeRekeyEvent` and `readRekeyEvidence`
+  report `destruct` only when the body says `closed: true`, and only for the
+  value `true`. A body that carries the flag on an open rekey (beside a
+  removal, or beside the scheduled marker) is still read in full, without
+  the flag. Refusing it would leave the device on the old epoch and hide the
+  removal, and a 0.8.0 reader reads it anyway, so the readers follow the
+  `scheduled` precedent: drop the contradictory flag, keep the rekey.
+
+## Compatibility
+
+Every reader of these three formats, in 0.8.0 and in KithMoot Android's
+port, reads named fields off the parsed body and never enumerates its keys,
+so an unknown key is ignored. Both directions, for each:
+
+- **New writer, 0.8.0 reader.** The invitation admits with the same secret,
+  end and relays and no `destruct`; the retirement reads as `{ ended: true }`;
+  the closure reads as an ordinary close. Checked against a real 0.8.0 build
+  and recorded per vector as `oldReader`. An old client in a self-destructing
+  room ends it the old way and tidies nothing.
+- **0.8.0 writer, new reader.** No flag, so `destruct` is absent everywhere.
+- **The one tightening.** A 0.9.0 reader refuses a group invitation whose
+  `destruct` is present and not `true`. No released writer produces one;
+  a 0.8.0 reader admits it (`destruct-invitation-malformed`).
+- **Types.** `PersistentRoomAdmission.destruct`, `RekeyNotice.destruct` and
+  `RekeyEvidence.destruct` are optional `true`; the retirement notice's type
+  is now `{ ended: boolean; destruct?: true }`, which still satisfies
+  `retirementError`.
+
+## What this does not cover
+
+- **A device that missed the closure.** A device offline at the close learns
+  of it from the authority's epoch refusal (`refused: 'closed'`), which
+  carries no flag. A room flagged on its invitation is covered by the stored
+  admission. A room first flagged on its closing rekey is covered only for a
+  device that reads that rekey (it is stored; `readRekeyEvidence` reads it
+  from the previous epoch's key).
+- **Deletion itself.** Each device can delete only what it signed, and
+  relays may keep copies. The flag is an instruction to cooperating clients.
+
+## Vectors
+
+`vectors/destruct-vectors.json` (generated by `scripts/generate-destruct.mjs`,
+checked by `vectors/verify-destruct.test.ts`), one group, `destruct`:
+
+- `destruct-invitation`: a conference invitation with `ends`, `destruct` and
+  `relays`; `unflagged` is the same invitation with the same draws and no
+  flag, so its body is the flagged body without `"destruct":true,`.
+- `destruct-invitation-no-end`: `destruct` with no `ends`.
+- `destruct-invitation-malformed`: `false`, `"true"`, `1`, `null`, built by
+  hand; each refused, each admitted by the 0.8.0 reader.
+- `destruct-invitation-copies`: an older flagged copy and a newer unflagged
+  one naming the relays; admitted with `destruct` and the relays in either
+  order.
+- `destruct-retirement`: `ended` and `destruct`; `unflagged` is 0.8.0's ended
+  retirement with the same draw.
+- `destruct-retirement-not-ended`: the flag without `ended`, built by hand;
+  the encoder refuses it, a reader keeps the retirement and drops the flag.
+- `destruct-closure`: a closing rekey with the flag, read by both readers;
+  `unflagged` is the same closure with the same draws.
+- `destruct-rekey-open`: the flag beside a removal and beside the scheduled
+  marker, built by hand; the encoder refuses both, a reader reads both
+  without the flag.

package/docs/scheduled-rekey.md

@@ -0,0 +1,142 @@
+# Scheduled rekeys and the history window
+
+Status: 0.8.0. The readers and wire format for phase 2a of KithMoot's key
+schedule parity plan (`kithmoot/docs/2026-10-04-key-schedule-parity.md`).
+This release adds nothing that rekeys on a schedule. It gives clients what
+they need to read such a rekey quietly, and to hand a newcomer the room's
+last month, before any authority starts rekeying on a timer.
+
+It makes no forward-secrecy claim and erases nothing. `MAX_MEMBER_EPOCH_CHAIN`
+stays at 32.
+
+## The problem
+
+Seal keys (`docs/seal-key.md`) heal a copied device only at a rekey, and a
+room rekeys only when somebody is removed. A quiet room heals never. The fix
+is an authority that turns the key over on a schedule, which raises three
+questions that this release answers on the wire:
+
+- **Every rekey is announced.** A client cannot tell a weekly turn of the key
+  from a removal, so it would announce one every week.
+- **A newcomer reads only the current epoch.** With the key turning weekly,
+  somebody joining on a Friday sees nothing said before Monday.
+- **No two clients agree on how much history to keep.** KithMoot reads four
+  left epochs; with weekly rekeys that is a month, and with removals it is
+  less.
+
+## The design
+
+### The marker
+
+A scheduled rekey carries `"scheduled": true` inside its encrypted body
+(`encodeRekeyEvent({ scheduled: true })`), between where `closed` and
+`commit` would be.
+
+- **Inside the body, not a tag.** A clear tag would tell the relay that
+  nobody was removed. The body is part of the content the event id hashes
+  (NIP-01), so the marker is signed.
+- **Never beside a removal or a close.** The encoder throws when `scheduled`
+  is combined with a non-empty `removed` or with `closed`. A rekey that
+  removes somebody is never quiet.
+- **Not believed beside one either.** `decodeRekeyEvent` reports
+  `RekeyNotice.scheduled` and `readRekeyEvidence` reports
+  `RekeyEvidence.scheduled` only when `removed` is empty and the rekey does
+  not close the room. A body that contradicts itself is read as a removal or
+  a close, so it is still announced.
+- **Byte-identical without it.** A rekey with no marker, or with `scheduled:
+  false`, is exactly 0.7.0's.
+
+A scheduled rekey is otherwise an ordinary rekey: it carries the commitment
+and the member list when asked, so a member grant's chain runs through it
+unbroken (`vectors/schedule-vectors.json`, `scheduled-rekey`).
+
+### The history window
+
+`HISTORY_WINDOW_SECONDS` is 30 days, as long as a chat log keeps a message.
+`MAX_HISTORY_EPOCHS` is 16. `epochsInWindow(left, now)` is the one rule
+every client applies:
+
+- it keeps the epochs left within the window (one left exactly 30 days ago
+  is kept, one a second older is not);
+- newest first by epoch number, the first given of a doubled epoch;
+- at most 16, however many fall inside the window;
+- it is pure and never throws: an entry with no usable number or time is
+  dropped.
+
+A weekly schedule puts about five epochs in the window; removals push it
+higher, and the cap bounds the relay filters a client opens.
+`MAX_HISTORY_EPOCHS` (how far back a member reads) is a different limit from
+`MAX_MEMBER_EPOCH_CHAIN` (how far behind a member desk will bring somebody).
+
+### The grant carries the window
+
+The authority's grant (kind 20469) gains an optional `passed`: the window's
+left epochs, oldest first, each `{ epoch, secret (base64url), left (unix
+seconds) }`.
+
+- **Every grant carries it.** An epoch request does not say which epoch the
+  device holds, so the desk cannot tell a newcomer from a device coming back.
+  Both are given the window. `hostRoomEpoch({ past })` asks for the room's
+  left epochs (`LeftEpoch`: `{ epoch, secret, leftAt }`) on every grant.
+- **Never epoch 0.** Its secret is the room secret, which the requester
+  already holds and which is never handed over. Nothing at or above the
+  granted epoch is carried either.
+- **The encoder is strict.** `encodeEpochGrant({ passed })` sorts the list
+  and throws on more than 16 entries, epoch 0, an epoch not below the one
+  granted, a doubled epoch, a secret that is not 32 bytes, or a `leftAt`
+  that is not a non-negative integer. An empty or absent list writes nothing,
+  so the body is 0.7.0's.
+- **The desk is forgiving.** Before encoding, `hostRoomEpoch` drops whatever
+  the encoder would refuse and applies `epochsInWindow`, so a bad `past()`
+  (or one that throws) costs the history and never the grant.
+- **The reader is strict and forgiving at once.** `decodeEpochGrant` takes
+  `passed` only in exactly the form the encoder writes (strictly increasing,
+  each in `[1, epoch)`, at most 16, 32-byte secrets, a non-negative integer
+  `left`), and returns it as `EpochGrant.passed` with `leftAt`. Anything else
+  drops the field and keeps the grant: the current epoch still stands.
+
+`decodeMemberEpochGrant` now sets `leftAt` on each passed epoch too, from the
+`created_at` of the authority's rekey out of it, so both kinds of answer say
+when each epoch was left.
+
+## Compatibility
+
+Both directions, for each change:
+
+- **New writer, old reader (rekey).** 0.7.0's `decodeRekeyEvent` and
+  `readRekeyEvidence` build their result from named fields, so they ignore
+  the marker. An old client announces a scheduled rekey as it would any
+  other.
+- **Old writer, new reader (rekey).** No marker, so `scheduled` is absent and
+  the rekey is announced as before.
+- **New writer, old reader (grant).** 0.7.0's `decodeEpochGrant` reads named
+  fields and gets the current epoch, as from any grant before
+  (`epoch-grant-window-old-reader`). It reads the window once it updates.
+- **Old writer, new reader (grant).** No `passed`, so `EpochGrant.passed` is
+  absent, as before.
+- **Types.** `EpochGrant.passed` and `MemberEpochGrant.passed` are now
+  `Array<RoomEpoch & { leftAt?: number }>`, which still accepts a plain
+  `RoomEpoch[]`. `RekeyNotice.scheduled` and `RekeyEvidence.scheduled` are
+  optional and absent unless set.
+
+## Vectors
+
+`vectors/schedule-vectors.json` (generated by `scripts/generate-schedule.mjs`,
+checked by `vectors/verify-schedule.test.ts`), one group, `schedule`:
+
+- `scheduled-rekey`: empty `removed`, the member list carried, the commitment
+  present, the marker present; read as scheduled with its secret, and read
+  through `readRekeyEvidence` from the previous epoch. `unflagged` is the
+  same rekey with the same draws and no marker: its body is the scheduled
+  body without `"scheduled":true,`.
+- `scheduled-rekey-contradictory`: the marker beside a removal and beside a
+  close, built by hand; both read as not scheduled, and the encoder refuses
+  both.
+- `epoch-grant-window`: a grant of epoch 18 carrying epochs 2 to 17, the cap.
+  The encoder refuses a 17th; a hand-built grant with 17 entries, one with
+  two out of order, and one carrying epoch 0 each read as the grant without
+  `passed`.
+- `epoch-grant-window-old-reader`: the same grant read as 0.7.0 reads it: the
+  current epoch only.
+- `history-window`: `epochsInWindow` at the 30-day edge, at the cap of 16, on
+  a weekly schedule, on unsorted input with a doubled epoch, and on nothing.

package/docs/seal-key.md

@@ -0,0 +1,104 @@
+# Seal keys: healing after a device is copied
+
+Status: 0.7.0. The first phase of KithMoot's key schedule parity plan
+(`kithmoot/docs/2026-10-04-key-schedule-parity.md`).
+
+## The problem
+
+A device key does two jobs. It signs, and every rekey copy (1462, the `keys`
+map) and every epoch grant (20469 from the authority, 20472 from a member)
+was NIP-44-sealed to it. Whoever copies a device key opens every rekey and
+grant after it, for as long as nobody notices and removes the device.
+
+Rotating a receiving key that the device key signs heals nothing: the thief
+holds the device key and signs their own rotation.
+
+## The design
+
+The receiving key rides in the device credential (kind 20460), which the
+**participant** signs. The participant key usually lives in a signer (an
+extension, a bunker, Heartwood) and not on the device, so it is the one thing
+a device thief does not get.
+
+- **Wire.** A credential may end with `["seal", <x-only pubkey>]`. The device
+  mints a fresh seal key at each renewal. `createDeviceCredential({ seal })`
+  appends the tag last, and refuses a value that is not a point on the curve.
+  A credential with no seal tag is byte-identical to one from 0.6.0.
+- **Sending.** A rekey copy and both grants are sealed to the seal key of the
+  newest credential the sender holds for the device (`sealTarget`), falling
+  back to the device key when that credential names none. The `keys` map stays
+  keyed by device. A seal tag that is doubled or off the curve reads as
+  unusable (`credentialSeal` returns null), and the sender seals to the device
+  key rather than failing the whole rekey: only the participant can have
+  signed it.
+- **Keeping the secrets.** A device keeps its seal secrets as it keeps its
+  device key. A device that reads a room again from the start (as a browser
+  does, following the rekeys from epoch 0) opens each old copy with the seal
+  key it was sealed to, so dropping them would leave it asking a desk for
+  every epoch. Keeping them costs healing nothing: a thief who copies the
+  device holds the seal keys minted up to then, which is what the newest of
+  them already gave away, and none minted after. Retiring them belongs to
+  forward secrecy (the plan's phase 2), alongside epoch secrets.
+- **Never back to the device key.** `sealTarget` does not check expiry. A
+  device quiet for longer than its credential still holds that seal key.
+  Falling back to the device key would hand the copy to the thief.
+- **Reading.** Every reader tries each seal key it holds, then the device key
+  (`openSealed`). A rekey copy none of them opens reads as no copy: the rekey
+  is still read (who was removed, whether the room closed), without a secret,
+  and the device asks for the epoch.
+- **Desks.** `hostRoomEpoch` and `hostMemberEpochDesk` take `credentialFor
+  (device)`, the newest credential the room has seen for that device.
+  `sealCredential` seals the answer to the newer of that and the one the
+  request carries (`newerCredential`: later expiry, then later `created_at`),
+  when the known one verifies for the same room, device and participant. A
+  thief replaying the device's older, still-live credential is answered under
+  the seal key the device has minted since.
+
+`credentialFor` must be monotone. Roster entries are device-signed, so a
+thief can publish one carrying the older credential. If that replaced the
+newer one, the desk would seal to the copied seal key again.
+
+## What healing covers
+
+A thief who copied a device once holds the seal keys minted up to then, and
+none minted after. They read until the next rekey and until the
+copied credential lapses (up to twelve hours in KithMoot). After both, rekeys
+are sealed where they cannot reach, and the desks answer the device's new
+seal key.
+
+Not covered here:
+
+- **The link outlives healing.** The thief also holds epoch 0, which is the
+  link, and can come back as a new participant. Healing turns an invisible
+  reader into a visible stranger. Keeping them out as well needs the link
+  replaced.
+- **Rekeys.** Healing completes only at a rekey. KithMoot rekeys on removal
+  today; scheduled rekeys are the plan's phase 2.
+- **A participant key on the device** (a local nsec, no signer) heals only by
+  removal: the thief can sign a fresh credential with a seal key of their own.
+- **Secondary devices** whose credential another device mints, and which do
+  not renew, carry no seal key and are sealed to as before.
+
+## Compatibility
+
+- Old senders ignore the tag and seal to the device key; new readers try the
+  device key last, so they still read.
+- New senders seal to the seal key only when the credential names one, and a
+  client mints a seal key only once it reads seal-sealed copies, so an old
+  reader never receives one.
+- `decodeEpochRequest` and `decodeMemberEpochRequest` return what they did in
+  0.6.0. The desks read the credential internally.
+
+## Vectors
+
+`vectors/seal-vectors.json` (generated by `scripts/generate-seal.mjs`,
+checked by `vectors/verify-seal.test.ts`):
+
+- `credential-seal-key`, `credential-without-seal`,
+  `credential-seal-doubled`, `credential-seal-off-curve`;
+- `newer-credential`;
+- `rekey-seal` (a seal-keyed and a bare recipient; the renewed device, the
+  thief and the bare device reading it), and `rekey-without-seal-keys`
+  (byte-identical to a rekey with bare devices);
+- `epoch-grant-seal` and `member-grant-seal` (the thief replays the copied
+  credential; the desk seals to the renewed one).