@forgesworn/fold-kit 0.5.1 → 0.7.0

package/dist/member-epoch.d.ts

@@ -61,6 +61,8 @@ export interface RekeyEvidence {
     closed: boolean;
     /** The epoch commitment, when the authority wrote one. */
     commit?: string;
+    /** The authority's member list, when it wrote one. */
+    members?: string[];
 }
 /**
  * Read an authority-signed rekey with the key of the epoch it leaves,
@@ -116,6 +118,9 @@ export interface EncodeMemberEpochGrantOptions {
     epochs: RoomEpoch[];
     /** The authority's rekey event for each of `epochs`, in the same order. */
     rekeys: Event[];
+    /** The newest credential the member holds for the device: the grant is
+     *  sealed to its seal key when it names one (see `seal.ts`). */
+    credential?: DeviceCredential;
     now: number;
     expiresAt?: number;
 }
@@ -134,6 +139,9 @@ export interface DecodeMemberEpochGrantOptions {
     authority: string;
     /** The asking device's key. */
     deviceSk: Uint8Array;
+    /** The seal key secrets this device holds, newest first, tried before
+     *  the device key (see `seal.ts`). */
+    sealSks?: readonly Uint8Array[];
     /** The ids of this device's own outstanding member requests. */
     requests: ReadonlySet<string>;
     /** Where this device is: the chain starts from this epoch's key. */
@@ -161,6 +169,8 @@ export interface MemberEpochGrant {
      *  grant one epoch ahead. Kept, they let the requester read what was said
      *  in the epochs it skipped, and hand them on from its own member desk. */
     passed: RoomEpoch[];
+    /** The newest member list in the chain, when any rekey in it had one. */
+    members?: string[];
 }
 /**
  * Verify a member's answer to one of this device's member requests. Null
@@ -190,6 +200,25 @@ export interface HostMemberEpochDeskOptions {
     removed: () => ReadonlySet<string>;
     /** True once the room has been closed. */
     closed?: () => boolean;
+    /**
+     * Whether the room knows this participant: on the authority's latest
+     * member list, in the room's current roster, or let in from this device.
+     * Consulted only once somebody has been removed; then nobody else is
+     * answered (#207). Without it, after a removal, nobody is known.
+     */
+    known?: (participant: string) => boolean;
+    /** The newest credential this device has seen for another device, from
+     *  the roster: see `HostRoomEpochOptions.credentialFor`. Keep it
+     *  monotone. */
+    credentialFor?: (device: string) => DeviceCredential | undefined;
+    /** Somebody the room does not know asked, after a removal. Called once
+     *  per participant, and again every `reportUnknownEvery` seconds while
+     *  they keep asking; nothing is published. Letting them in is making `known`
+     *  say yes, and their next ask is answered. */
+    onUnknown?: (request: MemberEpochRequest) => void;
+    /** Seconds before a participant still unknown and still asking is
+     *  reported again. Default 60 (`REPORT_UNKNOWN_EVERY_SECONDS`). */
+    reportUnknownEvery?: number;
     policy?: RoomPolicy;
     now?: () => number;
     /** Upper bound of the random wait before answering, so several members do
@@ -212,8 +241,10 @@ export interface HostMemberEpochDeskOptions {
  * Answer member epoch requests for as long as the handle is open: what any
  * member at the current epoch runs beside its session. It answers only an
  * admitted, credentialled device that is not removed, in a room that is not
- * closed, and only when it can hand over the whole chain from the
- * requester's epoch to its own with the authority's rekeys to prove it.
+ * closed, from a participant the room knows once anybody has been removed
+ * (see `hostRoomEpoch` for why), and only when it can hand over the whole
+ * chain from the requester's epoch to its own with the authority's rekeys
+ * to prove it.
  *
  * Anti-amplification: each answer waits a random `[0, jitterMs)`, and is
  * dropped if another member's grant to the same device appears meanwhile.
@@ -249,6 +280,9 @@ export interface MemberEpochRequestOptions {
     now?: () => number;
     /** How often a fresh request goes out. Default 4000 ms. */
     retryMs?: number;
+    /** The seal key secrets this device holds. Asked on every answer,
+     *  because a credential may renew while the ask is out. */
+    sealSks?: () => readonly Uint8Array[];
     expiresAt?: number;
 }
 /** What `requestRoomEpoch({ members })` takes: a second source of answers

package/dist/member-epoch.js

@@ -9,8 +9,9 @@ import { evaluateAccess } from './access.js';
 import { verifyEventUncached } from './verify.js';
 import { withExpiration } from './expiration.js';
 import { epochCommitment } from './epoch-commit.js';
+import { openSealed, sealTo } from './seal.js';
 import { KINDS } from './kinds.js';
-import { MAX_EPOCH, deriveEpoch, epochRequestAdmission, peekRekeyEvent, } from './epoch.js';
+import { MAX_EPOCH, REPORT_UNKNOWN_EVERY_SECONDS, deriveEpoch, epochRequestAdmission, peekRekeyEvent, readMemberList, sealCredential, } from './epoch.js';
 /**
  * Member-to-member epoch catch-up: any current member can bring an
  * admitted, non-removed member up to date.
@@ -118,6 +119,9 @@ export function readRekeyEvidence(event, opts) {
         };
         if (typeof body.commit === 'string' && HEX64.test(body.commit))
             evidence.commit = normaliseHex(body.commit);
+        const members = readMemberList(body.members);
+        if (members)
+            evidence.members = members;
         return evidence;
     }
     catch {
@@ -150,6 +154,12 @@ export function encodeMemberEpochRequest(opts) {
 /** Null for anything malformed, stale, from a device that cannot prove
  *  which participant it speaks for, or that cannot prove admission. */
 export function decodeMemberEpochRequest(event, opts) {
+    const read = readMemberEpochRequest(event, opts);
+    return read && read.request;
+}
+/** `decodeMemberEpochRequest`, keeping the credential the request was made
+ *  under: what the desk seals its answer by. */
+function readMemberEpochRequest(event, opts) {
     try {
         if (event.kind !== MEMBER_EPOCH_KINDS.REQUEST)
             return null;
@@ -184,7 +194,10 @@ export function decodeMemberEpochRequest(event, opts) {
             if (!evaluateAccess(opts.policy, verdict.participant, proof, opts.now, roomId).admitted)
                 return null;
         }
-        return { device: verdict.device, participant: verdict.participant, request: event.id, have: body.have };
+        return {
+            request: { device: verdict.device, participant: verdict.participant, request: event.id, have: body.have },
+            credential: body.credential,
+        };
     }
     catch {
         return null;
@@ -236,7 +249,7 @@ export function encodeMemberEpochGrant(opts) {
             ['d', roomId],
             ['p', device],
         ], opts.expiresAt),
-        content: nip44.v2.encrypt(JSON.stringify(body), nip44.v2.utils.getConversationKey(signerSk, device)),
+        content: sealTo(JSON.stringify(body), signerSk, device, opts.credential),
     }, signerSk);
 }
 /**
@@ -259,7 +272,7 @@ export function decodeMemberEpochGrant(event, opts) {
         const addressed = event.tags.find((t) => t[0] === 'p')?.[1];
         if (addressed === undefined || !hexEquals(addressed, device))
             return null;
-        const body = JSON.parse(nip44.v2.decrypt(event.content, nip44.v2.utils.getConversationKey(opts.deviceSk, event.pubkey)));
+        const body = JSON.parse(openSealed(event.content, event.pubkey, opts.deviceSk, opts.sealSks));
         if (body.v !== 1 || typeof body.request !== 'string' || !HEX64.test(body.request))
             return null;
         if (![...opts.requests].some((r) => hexEquals(r, body.request)))
@@ -279,6 +292,7 @@ export function decodeMemberEpochGrant(event, opts) {
         let previous = opts.current;
         let secret;
         const passed = [];
+        let members;
         for (let i = 0; i < length; i += 1) {
             const evidence = readRekeyEvidence(body.rekeys[i], { roomId, authority: opts.authority, previous });
             if (!evidence)
@@ -289,6 +303,8 @@ export function decodeMemberEpochGrant(event, opts) {
                 return null;
             for (const p of evidence.removed)
                 removed.add(p);
+            if (evidence.members)
+                members = evidence.members;
             const raw = body.secrets[i];
             if (typeof raw !== 'string')
                 return null;
@@ -308,7 +324,7 @@ export function decodeMemberEpochGrant(event, opts) {
             if (i < length - 1)
                 passed.push({ epoch: evidence.epoch, secret });
         }
-        return { epoch: { epoch: top, secret: secret }, removed: [...removed].sort(), passed };
+        return { epoch: { epoch: top, secret: secret }, removed: [...removed].sort(), passed, ...(members ? { members } : {}) };
     }
     catch {
         return null;
@@ -318,8 +334,10 @@ export function decodeMemberEpochGrant(event, opts) {
  * Answer member epoch requests for as long as the handle is open: what any
  * member at the current epoch runs beside its session. It answers only an
  * admitted, credentialled device that is not removed, in a room that is not
- * closed, and only when it can hand over the whole chain from the
- * requester's epoch to its own with the authority's rekeys to prove it.
+ * closed, from a participant the room knows once anybody has been removed
+ * (see `hostRoomEpoch` for why), and only when it can hand over the whole
+ * chain from the requester's epoch to its own with the authority's rekeys
+ * to prove it.
  *
  * Anti-amplification: each answer waits a random `[0, jitterMs)`, and is
  * dropped if another member's grant to the same device appears meanwhile.
@@ -344,6 +362,10 @@ export function hostMemberEpochDesk(opts) {
     const grantSeen = new Set();
     /** Requesting devices this desk has already stood down for once. */
     const stoodDown = new Set();
+    /** When each unknown participant was last reported. A requester asks
+     *  afresh every `retryMs` while it waits, so this is by participant, not
+     *  by request: one "let them in?" a `reportUnknownEvery`, not one a retry. */
+    const reported = new Map();
     /** Ids of the grants this desk published: each is signed by a one-time
      *  key, so its own grants are told apart by id, not by signer. */
     const mine = new Set();
@@ -386,7 +408,13 @@ export function hostMemberEpochDesk(opts) {
         }
         return { epochs, rekeys };
     };
-    const answer = (request) => {
+    const admissible = (request) => {
+        const removed = opts.removed();
+        if ([...removed].some((p) => hexEquals(p, request.participant)))
+            return false;
+        return removed.size === 0 || opts.known?.(request.participant) === true;
+    };
+    const answer = (request, presented) => {
         if (closed)
             return;
         if (grantSeen.has(request.device) && !stoodDown.has(request.device)) {
@@ -398,7 +426,7 @@ export function hostMemberEpochDesk(opts) {
         // Asked again, now that the wait is over: the room may have moved.
         if (opts.closed?.())
             return;
-        if ([...opts.removed()].some((p) => hexEquals(p, request.participant)))
+        if (!admissible(request))
             return;
         const current = opts.current();
         if (!current || request.have >= current.epoch)
@@ -414,6 +442,7 @@ export function hostMemberEpochDesk(opts) {
                 request: request.request,
                 epochs: chain.epochs,
                 rekeys: chain.rekeys,
+                credential: sealCredential(request, presented, opts.credentialFor, roomId, now()),
                 now: now(),
                 expiresAt: opts.expiresAt,
             });
@@ -440,31 +469,48 @@ export function hostMemberEpochDesk(opts) {
     const unsubRequests = opts.transport.subscribe([{ kinds: [MEMBER_EPOCH_KINDS.REQUEST], '#d': [roomId] }], (event) => {
         if (closed || hexEquals(event.pubkey, self))
             return;
-        const request = decodeMemberEpochRequest(event, { roomId, authority, roomKey: opts.roomKey, now: now(), policy: opts.policy });
-        if (!request || answered.has(request.request))
+        const read = readMemberEpochRequest(event, { roomId, authority, roomKey: opts.roomKey, now: now(), policy: opts.policy });
+        if (!read || answered.has(read.request.request))
             return;
-        answered.add(request.request);
-        bound(answered);
+        const { request, credential } = read;
         if (opts.closed?.()) {
+            answered.add(request.request);
+            bound(answered);
             opts.onRefused?.(request, 'closed');
             return;
         }
         if ([...opts.removed()].some((p) => hexEquals(p, request.participant))) {
+            answered.add(request.request);
+            bound(answered);
             opts.onRefused?.(request, 'removed');
             return;
         }
+        if (!admissible(request)) {
+            const last = reported.get(request.participant);
+            if (last !== undefined && now() - last < (opts.reportUnknownEvery ?? REPORT_UNKNOWN_EVERY_SECONDS))
+                return;
+            reported.set(request.participant, now());
+            if (reported.size > 256)
+                reported.delete(reported.keys().next().value);
+            opts.onUnknown?.(request);
+            opts.onRefused?.(request, 'unknown');
+            return;
+        }
+        reported.delete(request.participant);
+        answered.add(request.request);
+        bound(answered);
         const current = opts.current();
         if (!current || request.have >= current.epoch)
             return;
         grantSeen.delete(request.device);
         const delay = jitterMs === 0 ? 0 : Math.floor(random() * jitterMs);
         if (delay === 0) {
-            answer(request);
+            answer(request, credential);
             return;
         }
         const timer = setTimeout(() => {
             timers.delete(timer);
-            answer(request);
+            answer(request, credential);
         }, delay);
         timer.unref?.();
         timers.add(timer);
@@ -555,6 +601,7 @@ export function memberEpochSource(opts) {
                     roomId,
                     authority,
                     deviceSk: opts.deviceSk,
+                    sealSks: opts.sealSks?.(),
                     requests,
                     current: current(),
                     participant,

package/dist/seal.d.ts

@@ -0,0 +1,77 @@
+import type { DeviceCredential } from './types.js';
+/**
+ * Seal keys: how a device heals after its key is copied.
+ *
+ * A device key signs, and until now every rekey copy and every epoch grant
+ * was also sealed to it. Whoever copied it opened every one after, until
+ * somebody noticed and removed the device. Rotating a receiving key signed
+ * by the device key would heal nothing: the thief holds that key and signs
+ * their own rotation.
+ *
+ * So the receiving key rides in the device credential (kind 20460), which
+ * the participant signs. A device mints a fresh seal key at every renewal,
+ * and its participant's signer, not the device, binds it. Rekeys and grants
+ * are sealed to the seal key of the newest credential the sender holds for
+ * the device. A thief who copied the device once holds the seal keys minted
+ * up to then, and none minted after: once the copied credential has lapsed
+ * and the room has rekeyed, they are out.
+ *
+ * A device keeps its seal secrets as it keeps its device key, to open what
+ * was sealed to them when it reads the room again. Healing needs only that
+ * each new one is fresh; retiring old ones is a question of forward
+ * secrecy, not of healing.
+ *
+ * A credential with no `seal` tag is sealed to as before, to the device
+ * key, so a client that knows nothing of this keeps working, unhealed. See
+ * docs/seal-key.md.
+ */
+/** The credential tag that names a device's seal key. */
+export declare const SEAL_TAG = "seal";
+/** True for an x-only secp256k1 public key: 32-byte hex that lifts to a
+ *  point on the curve, so NIP-44 can agree a key with it. */
+export declare function isSealPubkey(value: unknown): value is string;
+export interface SealKey {
+    secretKey: Uint8Array;
+    /** x-only, lower-case hex: what `createDeviceCredential({ seal })` takes. */
+    pubkey: string;
+}
+/** A fresh seal key, for the next credential this device asks for. */
+export declare function generateSealKey(): SealKey;
+/**
+ * The seal key a credential names. Undefined when it names none, and null
+ * when its `seal` tags are unusable: more than one, or one that is not a
+ * point on the curve. Only the participant could have signed either, so
+ * nothing here is an attack, but a sender must not throw on it mid-rekey:
+ * it treats null as none.
+ */
+export declare function credentialSeal(credential: DeviceCredential): string | undefined | null;
+/**
+ * Where to seal something for `device`: the seal key `credential` names, or
+ * the device key when it names none, or is not this device's.
+ *
+ * Expiry is deliberately not checked. A device that has gone quiet for
+ * longer than its credential kept that seal key, and opens the copy when it
+ * is back. Falling back to the device key instead would hand that copy to
+ * anybody holding a stolen device key, which is the one person healing
+ * exists to shut out.
+ */
+export declare function sealTarget(device: string, credential?: DeviceCredential): string;
+/** Seal `plaintext` from `senderSk` to `device`, by `sealTarget`. */
+export declare function sealTo(plaintext: string, senderSk: Uint8Array, device: string, credential?: DeviceCredential): string;
+/**
+ * Open something sealed to this device by `sender`: under each seal key in
+ * turn, then under the device key. Throws when none of them opens it.
+ * NIP-44's MAC verifies under the right key only, so a wrong one fails
+ * rather than producing garbage.
+ */
+export declare function openSealed(ciphertext: string, sender: string, deviceSk: Uint8Array, sealSks?: readonly Uint8Array[]): string;
+/**
+ * The newer of two credentials: the later expiry, then the later
+ * `created_at`. Expiry first because some remote signers restamp
+ * `created_at` with their own clock (kithmoot#205), while the expiry is the
+ * device's own request, inside the signature either way. Ties keep `a`.
+ *
+ * Neither is checked here; compare only credentials already verified for
+ * the same device.
+ */
+export declare function newerCredential(a: DeviceCredential, b: DeviceCredential): DeviceCredential;

package/dist/seal.js

@@ -0,0 +1,128 @@
+import { schnorr } from '@noble/curves/secp256k1.js';
+import { nip44 } from 'nostr-tools';
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
+import { hexEquals, normaliseHex } from './hex.js';
+/**
+ * Seal keys: how a device heals after its key is copied.
+ *
+ * A device key signs, and until now every rekey copy and every epoch grant
+ * was also sealed to it. Whoever copied it opened every one after, until
+ * somebody noticed and removed the device. Rotating a receiving key signed
+ * by the device key would heal nothing: the thief holds that key and signs
+ * their own rotation.
+ *
+ * So the receiving key rides in the device credential (kind 20460), which
+ * the participant signs. A device mints a fresh seal key at every renewal,
+ * and its participant's signer, not the device, binds it. Rekeys and grants
+ * are sealed to the seal key of the newest credential the sender holds for
+ * the device. A thief who copied the device once holds the seal keys minted
+ * up to then, and none minted after: once the copied credential has lapsed
+ * and the room has rekeyed, they are out.
+ *
+ * A device keeps its seal secrets as it keeps its device key, to open what
+ * was sealed to them when it reads the room again. Healing needs only that
+ * each new one is fresh; retiring old ones is a question of forward
+ * secrecy, not of healing.
+ *
+ * A credential with no `seal` tag is sealed to as before, to the device
+ * key, so a client that knows nothing of this keeps working, unhealed. See
+ * docs/seal-key.md.
+ */
+/** The credential tag that names a device's seal key. */
+export const SEAL_TAG = 'seal';
+const HEX64 = /^[0-9a-f]{64}$/i;
+/** True for an x-only secp256k1 public key: 32-byte hex that lifts to a
+ *  point on the curve, so NIP-44 can agree a key with it. */
+export function isSealPubkey(value) {
+    if (typeof value !== 'string' || !HEX64.test(value))
+        return false;
+    try {
+        schnorr.utils.lift_x(BigInt(`0x${value}`));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A fresh seal key, for the next credential this device asks for. */
+export function generateSealKey() {
+    const secretKey = generateSecretKey();
+    return { secretKey, pubkey: getPublicKey(secretKey) };
+}
+/**
+ * The seal key a credential names. Undefined when it names none, and null
+ * when its `seal` tags are unusable: more than one, or one that is not a
+ * point on the curve. Only the participant could have signed either, so
+ * nothing here is an attack, but a sender must not throw on it mid-rekey:
+ * it treats null as none.
+ */
+export function credentialSeal(credential) {
+    const tags = credential.tags.filter((t) => t[0] === SEAL_TAG);
+    if (tags.length === 0)
+        return undefined;
+    if (tags.length > 1)
+        return null;
+    const value = tags[0][1];
+    return isSealPubkey(value) ? normaliseHex(value) : null;
+}
+/**
+ * Where to seal something for `device`: the seal key `credential` names, or
+ * the device key when it names none, or is not this device's.
+ *
+ * Expiry is deliberately not checked. A device that has gone quiet for
+ * longer than its credential kept that seal key, and opens the copy when it
+ * is back. Falling back to the device key instead would hand that copy to
+ * anybody holding a stolen device key, which is the one person healing
+ * exists to shut out.
+ */
+export function sealTarget(device, credential) {
+    const to = normaliseHex(device);
+    if (!credential)
+        return to;
+    const named = credential.tags.find((t) => t[0] === 'device')?.[1];
+    if (named === undefined || !hexEquals(named, to))
+        return to;
+    return credentialSeal(credential) ?? to;
+}
+/** Seal `plaintext` from `senderSk` to `device`, by `sealTarget`. */
+export function sealTo(plaintext, senderSk, device, credential) {
+    return nip44.v2.encrypt(plaintext, nip44.v2.utils.getConversationKey(senderSk, sealTarget(device, credential)));
+}
+/**
+ * Open something sealed to this device by `sender`: under each seal key in
+ * turn, then under the device key. Throws when none of them opens it.
+ * NIP-44's MAC verifies under the right key only, so a wrong one fails
+ * rather than producing garbage.
+ */
+export function openSealed(ciphertext, sender, deviceSk, sealSks = []) {
+    for (const sk of sealSks) {
+        try {
+            return nip44.v2.decrypt(ciphertext, nip44.v2.utils.getConversationKey(sk, sender));
+        }
+        catch {
+            // Not this one: try the next, then the device key.
+        }
+    }
+    return nip44.v2.decrypt(ciphertext, nip44.v2.utils.getConversationKey(deviceSk, sender));
+}
+function expirationOf(credential) {
+    const raw = credential.tags.find((t) => t[0] === 'expiration')?.[1];
+    const at = raw === undefined ? NaN : Number(raw);
+    return Number.isFinite(at) ? at : -Infinity;
+}
+/**
+ * The newer of two credentials: the later expiry, then the later
+ * `created_at`. Expiry first because some remote signers restamp
+ * `created_at` with their own clock (kithmoot#205), while the expiry is the
+ * device's own request, inside the signature either way. Ties keep `a`.
+ *
+ * Neither is checked here; compare only credentials already verified for
+ * the same device.
+ */
+export function newerCredential(a, b) {
+    const ea = expirationOf(a);
+    const eb = expirationOf(b);
+    if (eb !== ea)
+        return eb > ea ? b : a;
+    return b.created_at > a.created_at ? b : a;
+}

package/llms.txt

@@ -80,6 +80,8 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `epochRequestAdmission(opts)`, `deriveEpochRequestKey(roomKey)`
 - `hostRoomEpoch(opts)` / `requestRoomEpoch(opts)` / `EpochRefusedError` - the live request/grant desk, both sides
 - Member epoch catch-up (see `docs/member-epoch-catch-up.md`): `encodeRekeyEvent({ ..., commit: true })` writes `epochCommitment(roomId, epoch, secret)` into the rekey body; `hostMemberEpochDesk(opts)` lets any current member answer; `requestRoomEpoch({ ..., members: memberEpochSource(opts) })` asks the authority and members, first verifiable answer wins; `requestMemberEpoch(opts)` asks members alone. Kinds `MEMBER_EPOCH_KINDS` = `{ REQUEST: 20471, GRANT: 20472 }`. A member grant carries the authority-signed rekeys from the asker's epoch to the current one; the asker verifies the chain itself (`decodeMemberEpochGrant`) and refuses a last epoch with no commitment (legacy: authority only), a chain that removes it or closes the room, and one that stops short of `expected`. A verified grant is `{ epoch, removed, passed }`: `passed` holds the epochs between the asker's and `epoch`, oldest first, and `requestRoomEpoch` carries it as an optional `passed` when a member answered. Codecs: `encodeMemberEpochRequest`, `decodeMemberEpochRequest`, `encodeMemberEpochGrant`, `readRekeyEvidence`, `deriveMemberEpochRequestKey`, `MAX_MEMBER_EPOCH_CHAIN` (32)
+- The known-members gate (#207, see `docs/member-epoch-catch-up.md`): once a room has removed anybody (`removed()` not empty), `hostRoomEpoch` and `hostMemberEpochDesk` grant only to a participant for which `known(participant)` is true; anybody else is reported through `onUnknown` (once per participant, and again every `reportUnknownEvery` seconds, default `REPORT_UNKNOWN_EVERY_SECONDS` = 60, while they keep asking) and refused: the authority answers `refused: 'unknown'` (an `EpochRefusal`), a member stays silent. `unknown` is not final: `requestRoomEpoch` keeps asking, calls its `onUnknown` once, and rejects with `EpochRefusedError('unknown')` only at its timeout; a desk looks at the requester's next ask afresh, so letting somebody in is making `known` say yes. No `known` after a removal means nobody is known. Member lists: `encodeRekeyEvent({ members })` writes the authority's list (removed dropped, sorted) into the body, read back as `RekeyNotice.members` and `RekeyEvidence.members`, and as `MemberEpochGrant.members` (newest in the chain); `hostRoomEpoch({ members })` puts it in its grants (`EpochGrant.members`). `readMemberList(raw)` reads one, undefined when malformed. Without `members` and with no removal every event is byte-identical to 0.5.1
+- Seal keys (see `docs/seal-key.md`): `createDeviceCredential({ ..., seal })` appends `["seal", <x-only pubkey>]` last, under the participant's signature; mint a fresh one per credential with `generateSealKey()` and keep its secret as you keep the device key (old copies are sealed to old seal keys; healing needs only that each new one is fresh). `encodeRekeyEvent` recipients may be `{ device, credential }`; `encodeEpochGrant` and `encodeMemberEpochGrant` take `credential`; each copy is sealed to `sealTarget(device, credential)`: the credential's seal key, else the device key (never back to the device key because the credential lapsed). Readers take `sealSks` (`decodeRekeyEvent`, `decodeEpochGrant`, `decodeMemberEpochGrant`) or a `sealSks()` getter (`requestRoomEpoch`, `memberEpochSource`) and try them before the device key (`openSealed`); a rekey copy nothing opens reads as no copy. Desks take `credentialFor(device)`, the newest credential the room has seen (keep it monotone), and seal to the newer of that and the presented one (`sealCredential`, `newerCredential`: later expiration, then later created_at). `credentialSeal(c)` is the pubkey, undefined for none, null when doubled or off the curve (sealed to the device key). Without seal keys every event is byte-identical to 0.6.0
 - `canonicalAdmins(admins)` / `signAdmins(opts)` / `verifyAdmins(opts)` - the authority's signed admin list
 - `canonicalChannels(channels)` / `signChannels(opts)` / `verifyChannels(opts)` - the authority's signed channel list; `CHANNEL_NAME`, `RESERVED_CHANNELS`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/fold-kit",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Circle primitives for private Nostr groups nobody operates: epoch keys, link invites, removal by rekey, device credentials.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,6 +21,7 @@
     "vectors/kithmoot-vectors.json",
     "vectors/circle-vectors.json",
     "vectors/member-epoch-vectors.json",
+    "vectors/seal-vectors.json",
     "LICENSE",
     "README.md",
     "llms.txt"
@@ -33,6 +34,7 @@
     "diff-source": "node scripts/diff-source.mjs",
     "generate-fold": "node scripts/generate-fold.mjs",
     "generate-member-epoch": "node scripts/generate-member-epoch.mjs",
+    "generate-seal": "node scripts/generate-seal.mjs",
     "bundle-check": "node scripts/bundle-check.mjs",
     "tarball-smoke": "node scripts/tarball-smoke.mjs",
     "vectors": "vitest run vectors/",

package/vectors/member-epoch-vectors.json

@@ -136,6 +136,70 @@
           }
         }
       },
+      {
+        "name": "rekey-with-members",
+        "kind": "positive",
+        "note": "The rekey to epoch 2 with the authority's member list (`encodeRekeyEvent({ members })`, #207): the participants it knows to be in the room, the removed ones dropped even when passed in, lower-case, deduplicated and sorted. Body key order: v, epoch, removed, commit, members, keys. A desk hands an epoch on, once anybody has been removed, only to a participant the room knows; this list is where a member learns who that is. A list that is not an array of 32-byte hex keys is read as absent, which makes nobody known.",
+        "input": {
+          "roomId": "76c7081ef2322b7619d5cb5e690779fb942d63964f0b819e3d852db6c6a264f9",
+          "authority": "a5098de007349f8c12d6a854dfc069074b803470f59484697c50c5211b13c810",
+          "previousEpoch": 1,
+          "previousSecretHex": "cf6c5602daa51ecab29fbcbcef0da517b303cd59ee2904c15e226b7dd00e7752",
+          "previousKeyHex": "e038a7fca65628eebee35c562410ac63cce191b776ba0e8e5a1d241d9417f733",
+          "next": {
+            "epoch": 2,
+            "secretHex": "d4f5a0426e6880797fa29d914bb6977d193dfcd4f46b2a3acc576226eeec3ac9"
+          },
+          "recipients": [
+            "ef4396c842882c47ad1106d846d5c7e712c8928b69c92bc1798fa63deb9dd76b"
+          ],
+          "removed": [
+            "298cf780bc6d1b93c4900b20c89a911286ee3488ab94f543d96d567c70eb9ed2"
+          ],
+          "members": [
+            "588c59130ea8b9d81e836d0c5a89daa6b888923357c1415359b48595b4937f53",
+            "298cf780bc6d1b93c4900b20c89a911286ee3488ab94f543d96d567c70eb9ed2"
+          ],
+          "authoritySkHex": "825cf62829b0262bc5b46870d5cc054d6049e54a68cf1ea393c3da56226c456b",
+          "createdAt": 1799999002,
+          "event": {
+            "id": "d8d5c810c2e22d87493d8a10f908e38e68b5e4611ad5a230103ca01d5ba7a954",
+            "pubkey": "a5098de007349f8c12d6a854dfc069074b803470f59484697c50c5211b13c810",
+            "created_at": 1799999002,
+            "kind": 1462,
+            "tags": [
+              [
+                "d",
+                "76c7081ef2322b7619d5cb5e690779fb942d63964f0b819e3d852db6c6a264f9"
+              ],
+              [
+                "epoch",
+                "2"
+              ]
+            ],
+            "content": "AjCp1V9xfa32TYx5FAmMp1toqAM2yKrdBWdygJs+bFNGNIls48ZUufb0m3Cs51qusvmVJF51AEvXiW82LyhO6o/2J9Sra65b80+cyj8Km+LrLCXx6qyLPIYjKdISORDS6UhDKXa9UInbnZnGf87KKruDujB82QKDo26ImrXPbzy246dYMCvon7dYLGa+y3Qk9u5OLVKSrYVhDhFRHZX2XMltl478SRQ7GuvzbibZbFrNz1EvWSJOqbxf8YLpvYzbq55xmr9CA1rjk9vBKTzaHGX23ZvPPdaQFHh53YXCzYGN4+p54P/gH9PgZREZt+5Jel5kDhVfk8YMinaSzaBQ7MvEUEEIGDUPc6xbmZ3twlam+y/4H0vuugQtOm85tU7sozohPj65hlpaxRmTdenWivldIAWyPAEsUjOtGcvnFur5Hbg9H+WEsyXAX6tLZZV3jNFcCPLkoWB9O3iFasN3m2P0larhRTr9lhReqzt3UxtGBp14rErj0uZEZlwrz4n3ZiFgH/qc1X/pFlskh4dQJV/PGCEe6F7v7fd4aChiYHA1ghq2cy4fKW44+FU2EKPEezWcD96sOshiCoh0xWxHJoNbWhKJ5P8EcyK7TCH9UJVk9OyAiGVYnnxh+cuDgVfCOdRR6VbxWopqclvhlV+NGBullxSv5aQJSj6fS5O+QxSCwZrR8DA2SMKRSFU+kXHQxOgEvZW1cPdHWMtUr1dwsRrMd3ayNyZqSIjjyktqzsmrD+Pl6Ikk5tbE3kyNYdWHX7Mz",
+            "sig": "90c5666a5ca4c5d4c1a0e4b3b4422aa7462d4300986f82afff435a88edb48a41e3191192c6404b17401712204de56ba2269a6b4376f0ef224ad9798728550710"
+          },
+          "randomHex": [
+            "ff9c267263a44961a1d49a09c831ef35fa2d53e4d4cfc572d72f506478e61045",
+            "30a9d55f717dadf64d8c7914098ca75b68a80336c8aadd056772809b3e6c5346",
+            "11ae6ba1ae1e25f1493588462e919538089a63c28e68b7f5734bd0df2ba395e3"
+          ]
+        },
+        "output": {
+          "evidence": {
+            "epoch": 2,
+            "removed": [
+              "298cf780bc6d1b93c4900b20c89a911286ee3488ab94f543d96d567c70eb9ed2"
+            ],
+            "closed": false,
+            "commit": "3472885df839fc5d48d809476e28e36c458c3e4717e35c2ec0d69bbbdf94f896",
+            "members": [
+              "588c59130ea8b9d81e836d0c5a89daa6b888923357c1415359b48595b4937f53"
+            ]
+          }
+        }
+      },
       {
         "name": "member-request",
         "kind": "positive",