@forgesworn/fold-kit 0.5.1 → 0.7.0

package/README.md

@@ -154,6 +154,20 @@ the rest).
   `encodeMemberEpochRequest`, `decodeMemberEpochRequest`,
   `encodeMemberEpochGrant`, `decodeMemberEpochGrant`, `readRekeyEvidence`,
   `deriveMemberEpochRequestKey`. Vectors: `vectors/member-epoch-vectors.json`
+- The known-members gate (#207, `docs/member-epoch-catch-up.md`): once a
+  room has removed anybody, both desks grant only to participants the room
+  knows (`known`), and send anybody else to approval (`onUnknown`; the
+  authority answers `refused: 'unknown'`, which `requestRoomEpoch` waits
+  through). `encodeRekeyEvent({ members })` and `hostRoomEpoch({ members })`
+  carry the authority's member list (`readMemberList` reads one)
+- Seal keys (`docs/seal-key.md`): a credential may name a seal key
+  (`createDeviceCredential({ seal })`, `generateSealKey`), and rekeys and
+  both grants are sealed to the newest one the sender holds for a device
+  instead of its device key, so a copied device heals once its credential
+  lapses and the room rekeys. Recipients as `{ device, credential }`;
+  `sealSks` on the readers; `credentialFor` on both desks;
+  `credentialSeal`, `sealTarget`, `sealTo`, `openSealed`, `newerCredential`,
+  `sealCredential`. Vectors: `vectors/seal-vectors.json`
 - `canonicalAdmins`, `signAdmins`, `verifyAdmins` - the authority's signed
   admin list
 - `canonicalChannels`, `signChannels`, `verifyChannels`, `CHANNEL_NAME`,

package/dist/credential.d.ts

@@ -25,6 +25,11 @@ export interface CreateCredentialOptions {
     expiresAt: number;
     /** Injectable clock, in unix seconds. Defaults to the real one. */
     now?: () => number;
+    /** The device's seal key for this credential: an x-only public key,
+     *  minted fresh for each credential, to which rekeys and epoch grants are
+     *  then sealed instead of the device key. See `seal.ts`. Omitted, the
+     *  credential is byte-identical to one minted before seal keys. */
+    seal?: string;
 }
 /** The longest a person-scoped credential may run. A phone that leaves the house is better at seven days. */
 export declare const PERSON_CREDENTIAL_MAX_SECONDS: number;

package/dist/credential.js

@@ -1,6 +1,7 @@
 import { KINDS } from './kinds.js';
 import { verifyEventUncached } from './verify.js';
 import { hexEquals, normaliseHex } from './hex.js';
+import { isSealPubkey, SEAL_TAG } from './seal.js';
 /** The longest a person-scoped credential may run. A phone that leaves the house is better at seven days. */
 export const PERSON_CREDENTIAL_MAX_SECONDS = 30 * 24 * 60 * 60;
 /**
@@ -43,6 +44,8 @@ export async function createDeviceCredential(opts) {
         throw new Error('a room credential needs a room');
     if (person && opts.expiresAt - now > PERSON_CREDENTIAL_MAX_SECONDS)
         throw new Error('a person credential may not run more than 30 days');
+    if (opts.seal !== undefined && !isSealPubkey(opts.seal))
+        throw new Error('a seal key must be an x-only public key on the curve');
     const unsigned = {
         kind: KINDS.CREDENTIAL,
         created_at: now,
@@ -52,6 +55,7 @@ export async function createDeviceCredential(opts) {
             ['expiration', String(opts.expiresAt)],
             ...(person ? [['scope', 'person']] : []),
             ...(opts.label !== undefined ? [['label', opts.label]] : []),
+            ...(opts.seal !== undefined ? [[SEAL_TAG, opts.seal.toLowerCase()]] : []),
         ],
         content: '',
     };

package/dist/epoch.d.ts

@@ -73,6 +73,10 @@ export interface EpochKeys {
     /** The cipher key. The room key in epoch 0. */
     key: Uint8Array;
 }
+/** A participant list as a body carries it: lower-case, deduplicated and
+ *  sorted, or undefined when the field is absent or is not a list of keys.
+ *  Undefined is the safe reading, since it makes nobody known. */
+export declare function readMemberList(raw: unknown): string[] | undefined;
 /** A fresh secret for the next epoch. */
 export declare function generateEpochSecret(): Uint8Array;
 /**
@@ -94,8 +98,11 @@ export interface EncodeRekeyOptions {
     /** The epoch being entered. Must be `current.epoch + 1`. */
     next: RoomEpoch;
     /** Devices to seal the new secret for. Everybody still in the room,
-     *  except the removed participants' devices. */
-    recipients: string[];
+     *  except the removed participants' devices. A recipient given with its
+     *  newest credential is sealed to that credential's seal key, when it
+     *  names one; a bare device, to the device key (see `seal.ts`). The
+     *  `keys` map is keyed by device either way. */
+    recipients: ReadonlyArray<string | RekeyRecipient>;
     /** Participants removed at this step. Empty on a rekey that only turns
      *  the key over. */
     removed: string[];
@@ -108,11 +115,22 @@ export interface EncodeRekeyOptions {
      *  bring a device that missed this rekey up to date (see
      *  `member-epoch.ts`). Omitted, the event is byte-identical to before. */
     commit?: boolean;
+    /** Every participant the authority knows to be in the room, not only the
+     *  ones present now: a member who is offline as the room rekeys is still
+     *  a member. Removed participants are dropped. Omitted, the event is
+     *  byte-identical to before. */
+    members?: string[];
     now: number;
     /** A conference room's end, in unix seconds: the event carries it as a
      *  NIP-40 expiration (see `withExpiration`). Omit for a room with no end. */
     expiresAt?: number;
 }
+/** A rekey recipient: a device, and the newest credential the sender holds
+ *  for it. */
+export interface RekeyRecipient {
+    device: string;
+    credential?: DeviceCredential;
+}
 /** Announce the next epoch. See the module comment for what this is. */
 export declare function encodeRekeyEvent(opts: EncodeRekeyOptions): Event;
 /** What a rekey says, once read. */
@@ -125,6 +143,9 @@ export interface RekeyNotice {
      *  device that was removed, or that was not in the room when the
      *  authority rekeyed. */
     secret?: Uint8Array;
+    /** The participants the authority listed as in the room. Absent from a
+     *  rekey written without the list. */
+    members?: string[];
     /** True for a current-state grant, whose removed list is cumulative.
      *  It synchronises this session; it does not describe a new removal. */
     catchUp?: true;
@@ -148,6 +169,9 @@ export interface DecodeRekeyOptions extends PeekRekeyOptions {
     current: EpochKeys;
     /** This device's key, to open its own copy. */
     deviceSk: Uint8Array;
+    /** The seal key secrets this device holds, newest first, tried before
+     *  the device key (see `seal.ts`). */
+    sealSks?: readonly Uint8Array[];
 }
 /**
  * Read a rekey. Null for anything that does not check out, and for a rekey
@@ -225,8 +249,14 @@ export interface EpochRequest {
  *  cannot prove which participant it speaks for in this room, or from one
  *  that cannot prove it was admitted to the room at all. */
 export declare function decodeEpochRequest(event: Event, opts: DecodeEpochRequestOptions): EpochRequest | null;
-/** Why the authority would not hand an epoch over. */
-export type EpochRefusal = 'removed' | 'closed';
+/** How often a desk reports the same unknown participant while they keep
+ *  asking: often enough that a missed "let them in?" comes back, rarely
+ *  enough that it is not a nag. */
+export declare const REPORT_UNKNOWN_EVERY_SECONDS = 60;
+/** Why the authority would not hand an epoch over. `unknown` is not final:
+ *  the room has removed somebody, and does not yet know this participant,
+ *  so it waits for a member to let them in (#207). */
+export type EpochRefusal = 'removed' | 'closed' | 'unknown';
 export interface EncodeEpochGrantOptions {
     roomId: string;
     authoritySk: Uint8Array;
@@ -236,7 +266,13 @@ export interface EncodeEpochGrantOptions {
     /** The current epoch. Omitted when refusing. */
     epoch?: RoomEpoch;
     removed?: string[];
+    /** The participants the authority knows, so the requester's own member
+     *  desk knows them too. Omitted, the body is as before. */
+    members?: string[];
     refused?: EpochRefusal;
+    /** The newest credential the authority holds for the device: the grant
+     *  is sealed to its seal key when it names one (see `seal.ts`). */
+    credential?: DeviceCredential;
     /** A conference room's end, in unix seconds: the event carries it as a
      *  NIP-40 expiration (see `withExpiration`). Omit for a room with no end. */
     expiresAt?: number;
@@ -248,6 +284,9 @@ export interface DecodeEpochGrantOptions {
     roomId: string;
     authority: string;
     deviceSk: Uint8Array;
+    /** The seal key secrets this device holds: see
+     *  `DecodeRekeyOptions.sealSks`. */
+    sealSks?: readonly Uint8Array[];
     request: string;
     now: number;
     maxAgeSeconds?: number;
@@ -261,6 +300,8 @@ export type EpochGrant = {
      *  the epochs it carried between the requester's and `epoch`. See
      *  `MemberEpochGrant.passed`. The authority's own answer has none. */
     passed?: RoomEpoch[];
+    /** The participants the room knows, when the answer carried them. */
+    members?: string[];
     refused?: undefined;
 } | {
     refused: EpochRefusal;
@@ -281,6 +322,33 @@ export interface HostRoomEpochOptions {
     removed: () => ReadonlySet<string>;
     /** True once the room has been closed: every request is refused. */
     closed?: () => boolean;
+    /**
+     * Whether the room knows this participant: on the authority's member
+     * list, in the room now, or let in. Consulted only once somebody has been
+     * removed, and then everybody else is answered `unknown` (#207). Without
+     * it, after a removal, nobody is known. Asked on every request.
+     */
+    known?: (participant: string) => boolean;
+    /** The participants to tell a granted device about, so its own member
+     *  desk knows them too. Asked on every grant. */
+    members?: () => readonly string[];
+    /**
+     * The newest credential the authority has seen for a device, from the
+     * roster. An answer is sealed to the newer of this and the one the
+     * request carries, so a thief replaying a device's older, still-live
+     * credential is answered under the seal key the device minted since.
+     * Keep it monotone: a roster entry carrying an older credential than one
+     * already seen must not replace it, or the thief can publish one.
+     */
+    credentialFor?: (device: string) => DeviceCredential | undefined;
+    /** Somebody the room does not know asked, after a removal: what an app
+     *  turns into "let them in?". Called once per participant, and again
+     *  every `reportUnknownEvery` seconds while they keep asking. Letting them in
+     *  is making `known` say yes; the requester's next ask is then granted. */
+    onUnknown?: (request: EpochRequest) => void;
+    /** Seconds before a participant still unknown and still asking is
+     *  reported again. Default 60. */
+    reportUnknownEvery?: number;
     policy?: RoomPolicy;
     legacyParticipants?: ReadonlySet<string>;
     now?: () => number;
@@ -289,6 +357,15 @@ export interface HostRoomEpochOptions {
     /** A conference room's end: every grant carries it as an expiration. */
     expiresAt?: number;
 }
+/**
+ * The credential to seal an answer to: the one the request carries, unless
+ * the room has seen a newer one for the same device and participant that
+ * still verifies. Shared by both desks.
+ */
+export declare function sealCredential(request: {
+    device: string;
+    participant: string;
+}, presented: DeviceCredential, credentialFor: ((device: string) => DeviceCredential | undefined) | undefined, roomId: string, now: number): DeviceCredential;
 /**
  * Answer epoch requests for as long as the handle is open. What a keeper
  * runs beside its invitation desk: a member arriving, or returning, after
@@ -298,6 +375,13 @@ export interface HostRoomEpochOptions {
  * *secret*, which opens epoch 0 and nothing after it. A request with no
  * admission proof, or one made under some other key, is not answered at
  * all: a stranger learns nothing, not even that a desk is here.
+ *
+ * The admission proof is made under the epoch-0 room key, which a removed
+ * member still holds, so removal by participant alone is undone by a fresh
+ * key (#207). Once anyone has been removed the desk therefore grants only
+ * to participants the room knows (`known`), and answers anybody else
+ * `unknown` until a member lets them in. A room that has never removed
+ * anybody is answered exactly as before.
  */
 export declare function hostRoomEpoch(opts: HostRoomEpochOptions): {
     close(): void;
@@ -319,6 +403,12 @@ export interface RequestRoomEpochOptions {
     /** Ask the room's current members too (`memberEpochSource`): the first
      *  answer that checks out, the authority's or a member's, settles it. */
     members?: MemberEpochSource;
+    /** The authority said the room does not know this participant yet. Not
+     *  final: the ask goes on, and a member letting them in settles it. */
+    onUnknown?: () => void;
+    /** The seal key secrets this device holds. Asked on every answer,
+     *  because a credential may renew while the ask is out. */
+    sealSks?: () => readonly Uint8Array[];
 }
 /** Thrown when the authority answered, and the answer was no. */
 export declare class EpochRefusedError extends Error {
@@ -327,7 +417,8 @@ export declare class EpochRefusedError extends Error {
 }
 /** Ask the authority where the room is, and wait for the answer. Rejects
  *  with `EpochRefusedError` on a refusal, and with a plain error when
- *  nobody answers inside the timeout. */
+ *  nobody answers inside the timeout. `unknown` is not final: the ask goes
+ *  on, and only a timeout after it rejects, with `EpochRefusedError`. */
 export declare function requestRoomEpoch(opts: RequestRoomEpochOptions): Promise<Exclude<EpochGrant, {
     refused: EpochRefusal;
 }>>;

package/dist/epoch.js

@@ -12,6 +12,7 @@ import { deriveRoom } from './room.js';
 import { verifyDeviceCredential } from './credential.js';
 import { evaluateAccess } from './access.js';
 import { verifyEventUncached } from './verify.js';
+import { newerCredential, openSealed, sealTo } from './seal.js';
 import { withExpiration } from './expiration.js';
 import { epochCommitment } from './epoch-commit.js';
 /**
@@ -80,6 +81,14 @@ function require32(bytes, what) {
     if (bytes.length !== 32)
         throw new Error(`${what} must be 32 bytes`);
 }
+/** A participant list as a body carries it: lower-case, deduplicated and
+ *  sorted, or undefined when the field is absent or is not a list of keys.
+ *  Undefined is the safe reading, since it makes nobody known. */
+export function readMemberList(raw) {
+    if (!Array.isArray(raw) || !raw.every((p) => typeof p === 'string' && HEX64.test(p)))
+        return undefined;
+    return [...new Set(raw.map(normaliseHex))].sort();
+}
 function requireHex32(value, what) {
     if (!HEX64.test(value))
         throw new Error(`${what} must be 32-byte hex`);
@@ -119,6 +128,12 @@ export function deriveEpoch(epoch) {
         key: hkdf(sha256, epoch.secret, undefined, `${EPOCH_KEY_INFO}/${n}`, 32),
     };
 }
+function memberListOf(members, removed) {
+    const out = new Set(members.map((p) => requireHex32(p, 'member participant')));
+    for (const p of removed)
+        out.delete(normaliseHex(p));
+    return [...out].sort();
+}
 /** Announce the next epoch. See the module comment for what this is. */
 export function encodeRekeyEvent(opts) {
     require32(opts.authoritySk, 'authority secret key');
@@ -132,8 +147,9 @@ export function encodeRekeyEvent(opts) {
     const sealed = { v: 1, secret: base64urlnopad.encode(opts.next.secret) };
     const plaintext = JSON.stringify(sealed);
     for (const raw of opts.closed ? [] : opts.recipients) {
-        const device = requireHex32(raw, 'recipient device');
-        keys[device] = nip44.v2.encrypt(plaintext, nip44.v2.utils.getConversationKey(opts.authoritySk, device));
+        const recipient = typeof raw === 'string' ? { device: raw } : raw;
+        const device = requireHex32(recipient.device, 'recipient device');
+        keys[device] = sealTo(plaintext, opts.authoritySk, device, recipient.credential);
     }
     const body = {
         v: 1,
@@ -142,6 +158,7 @@ export function encodeRekeyEvent(opts) {
         ...(opts.by !== undefined ? { by: requireHex32(opts.by, 'admin') } : {}),
         ...(opts.closed ? { closed: true } : {}),
         ...(opts.commit ? { commit: epochCommitment(roomId, epoch, opts.next.secret) } : {}),
+        ...(opts.members !== undefined ? { members: memberListOf(opts.members, removed) } : {}),
         keys,
     };
     return finalizeEvent({
@@ -206,14 +223,26 @@ export function decodeRekeyEvent(event, opts) {
         };
         if (typeof body.by === 'string' && HEX64.test(body.by))
             notice.by = normaliseHex(body.by);
+        const members = readMemberList(body.members);
+        if (members)
+            notice.members = members;
         const device = getPublicKey(opts.deviceSk);
         const mine = Object.entries(body.keys).find(([to]) => hexEquals(to, device))?.[1];
         if (typeof mine === 'string') {
-            const sealed = JSON.parse(nip44.v2.decrypt(mine, nip44.v2.utils.getConversationKey(opts.deviceSk, event.pubkey)));
-            if (sealed.v === 1 && typeof sealed.secret === 'string') {
-                const secret = base64urlnopad.decode(sealed.secret);
-                if (secret.length === 32)
-                    notice.secret = secret;
+            // A copy none of this device's keys opens is no copy: sealed to a
+            // seal key it has since erased, or one it never had. The rest of the
+            // rekey still says who was removed, so it is read without the secret,
+            // and the device asks for the epoch.
+            try {
+                const sealed = JSON.parse(openSealed(mine, event.pubkey, opts.deviceSk, opts.sealSks));
+                if (sealed.v === 1 && typeof sealed.secret === 'string') {
+                    const secret = base64urlnopad.decode(sealed.secret);
+                    if (secret.length === 32)
+                        notice.secret = secret;
+                }
+            }
+            catch {
+                // No secret, as above.
             }
         }
         return notice;
@@ -296,6 +325,12 @@ export function encodeEpochRequest(opts) {
  *  cannot prove which participant it speaks for in this room, or from one
  *  that cannot prove it was admitted to the room at all. */
 export function decodeEpochRequest(event, opts) {
+    const read = readEpochRequest(event, opts);
+    return read && read.request;
+}
+/** `decodeEpochRequest`, keeping the credential the request was made
+ *  under: what the desk seals its answer by. */
+function readEpochRequest(event, opts) {
     try {
         if (event.kind !== KINDS.EPOCH_REQUEST)
             return null;
@@ -340,12 +375,16 @@ export function decodeEpochRequest(event, opts) {
             if (!evaluateAccess(opts.policy, verdict.participant, proof, opts.now, opts.roomId).admitted)
                 return null;
         }
-        return { device: verdict.device, participant: verdict.participant, request: event.id };
+        return { request: { device: verdict.device, participant: verdict.participant, request: event.id }, credential: body.credential };
     }
     catch {
         return null;
     }
 }
+/** How often a desk reports the same unknown participant while they keep
+ *  asking: often enough that a missed "let them in?" comes back, rarely
+ *  enough that it is not a nag. */
+export const REPORT_UNKNOWN_EVERY_SECONDS = 60;
 /** Answer one request: the current epoch sealed to the asking device, or a
  *  refusal it alone can read. */
 export function encodeEpochGrant(opts) {
@@ -366,6 +405,8 @@ export function encodeEpochGrant(opts) {
             body.secret = base64urlnopad.encode(opts.epoch.secret);
         }
         body.removed = [...new Set((opts.removed ?? []).map((p) => requireHex32(p, 'removed participant')))].sort();
+        if (opts.members !== undefined)
+            body.members = memberListOf(opts.members, body.removed);
     }
     return finalizeEvent({
         kind: KINDS.EPOCH_GRANT,
@@ -374,7 +415,7 @@ export function encodeEpochGrant(opts) {
             ['d', roomId],
             ['p', device],
         ], opts.expiresAt),
-        content: nip44.v2.encrypt(JSON.stringify(body), nip44.v2.utils.getConversationKey(opts.authoritySk, device)),
+        content: sealTo(JSON.stringify(body), opts.authoritySk, device, opts.credential),
     }, opts.authoritySk);
 }
 /** Read the authority's answer to this device's own request. Null for
@@ -396,29 +437,51 @@ export function decodeEpochGrant(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' || !hexEquals(body.request, opts.request))
             return null;
-        if (body.refused === 'removed' || body.refused === 'closed')
+        if (body.refused === 'removed' || body.refused === 'closed' || body.refused === 'unknown')
             return { refused: body.refused };
         if (!Number.isSafeInteger(body.epoch) || body.epoch < 0 || body.epoch > MAX_EPOCH)
             return null;
         const removed = Array.isArray(body.removed)
             ? [...new Set(body.removed.filter((p) => typeof p === 'string' && HEX64.test(p)).map(normaliseHex))].sort()
             : [];
+        const members = readMemberList(body.members);
+        const listed = members ? { members } : {};
         if (body.epoch === 0)
-            return { epoch: { epoch: 0 }, removed };
+            return { epoch: { epoch: 0 }, removed, ...listed };
         if (typeof body.secret !== 'string')
             return null;
         const secret = base64urlnopad.decode(body.secret);
         if (secret.length !== 32)
             return null;
-        return { epoch: { epoch: body.epoch, secret }, removed };
+        return { epoch: { epoch: body.epoch, secret }, removed, ...listed };
     }
     catch {
         return null;
     }
 }
+/**
+ * The credential to seal an answer to: the one the request carries, unless
+ * the room has seen a newer one for the same device and participant that
+ * still verifies. Shared by both desks.
+ */
+export function sealCredential(request, presented, credentialFor, roomId, now) {
+    let known;
+    try {
+        known = credentialFor?.(request.device);
+    }
+    catch {
+        known = undefined;
+    }
+    if (!known)
+        return presented;
+    const verdict = verifyDeviceCredential(known, { roomId, now });
+    if (!verdict.ok || verdict.device !== normaliseHex(request.device) || verdict.participant !== normaliseHex(request.participant))
+        return presented;
+    return newerCredential(presented, known);
+}
 /**
  * Answer epoch requests for as long as the handle is open. What a keeper
  * runs beside its invitation desk: a member arriving, or returning, after
@@ -428,6 +491,13 @@ export function decodeEpochGrant(event, opts) {
  * *secret*, which opens epoch 0 and nothing after it. A request with no
  * admission proof, or one made under some other key, is not answered at
  * all: a stranger learns nothing, not even that a desk is here.
+ *
+ * The admission proof is made under the epoch-0 room key, which a removed
+ * member still holds, so removal by participant alone is undone by a fresh
+ * key (#207). Once anyone has been removed the desk therefore grants only
+ * to participants the room knows (`known`), and answers anybody else
+ * `unknown` until a member lets them in. A room that has never removed
+ * anybody is answered exactly as before.
  */
 export function hostRoomEpoch(opts) {
     require32(opts.authoritySk, 'authority secret key');
@@ -436,11 +506,21 @@ export function hostRoomEpoch(opts) {
     const authority = getPublicKey(opts.authoritySk);
     const now = opts.now ?? (() => Math.floor(Date.now() / 1000));
     const answered = new Set();
+    /** Requests answered `unknown`, which the requester sends again while it
+     *  waits: answered again only once they are known. */
+    const waiting = new Set();
+    /** When each unknown participant was last reported through `onUnknown`,
+     *  so one still waiting is reported again only after `reportUnknownEvery`. */
+    const reported = new Map();
+    const bound = (set) => {
+        if (set.size > 256)
+            set.delete(set.values().next().value);
+    };
     let closed = false;
     const unsub = opts.transport.subscribe([{ kinds: [KINDS.EPOCH_REQUEST], '#d': [roomId], '#p': [authority] }], (event) => {
         if (closed)
             return;
-        const request = decodeEpochRequest(event, {
+        const read = readEpochRequest(event, {
             roomId,
             authoritySk: opts.authoritySk,
             roomKey: opts.roomKey,
@@ -448,20 +528,40 @@ export function hostRoomEpoch(opts) {
             policy: opts.policy,
             legacyParticipants: opts.legacyParticipants,
         });
-        if (!request || answered.has(request.request))
+        if (!read || answered.has(read.request.request))
             return;
-        answered.add(request.request);
-        if (answered.size > 256)
-            answered.delete(answered.values().next().value);
+        const request = read.request;
         let refused;
         if (opts.closed?.())
             refused = 'closed';
         else if (opts.removed().has(request.participant))
             refused = 'removed';
+        else if (opts.removed().size > 0 && !opts.known?.(request.participant))
+            refused = 'unknown';
+        if (refused === 'unknown') {
+            if (waiting.has(request.request))
+                return;
+            waiting.add(request.request);
+            bound(waiting);
+        }
+        else {
+            waiting.delete(request.request);
+            answered.add(request.request);
+            bound(answered);
+        }
         let grant;
         try {
             grant = refused
-                ? encodeEpochGrant({ roomId, authoritySk: opts.authoritySk, device: request.device, request: request.request, now: now(), refused, expiresAt: opts.expiresAt })
+                ? encodeEpochGrant({
+                    roomId,
+                    authoritySk: opts.authoritySk,
+                    device: request.device,
+                    request: request.request,
+                    now: now(),
+                    refused,
+                    credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
+                    expiresAt: opts.expiresAt,
+                })
                 : encodeEpochGrant({
                     roomId,
                     authoritySk: opts.authoritySk,
@@ -470,6 +570,8 @@ export function hostRoomEpoch(opts) {
                     now: now(),
                     epoch: opts.current(),
                     removed: [...opts.removed()],
+                    ...(opts.members ? { members: [...opts.members()] } : {}),
+                    credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
                     expiresAt: opts.expiresAt,
                 });
         }
@@ -477,6 +579,14 @@ export function hostRoomEpoch(opts) {
             return;
         }
         opts.transport.publish(grant).catch(() => { });
+        if (refused === 'unknown' && now() - (reported.get(request.participant) ?? -Infinity) >= (opts.reportUnknownEvery ?? REPORT_UNKNOWN_EVERY_SECONDS)) {
+            reported.set(request.participant, now());
+            if (reported.size > 256)
+                reported.delete(reported.keys().next().value);
+            opts.onUnknown?.(request);
+        }
+        if (!refused)
+            reported.delete(request.participant);
         if (refused)
             opts.onRefused?.(request, refused);
         else
@@ -495,14 +605,19 @@ export function hostRoomEpoch(opts) {
 export class EpochRefusedError extends Error {
     refused;
     constructor(refused) {
-        super(refused === 'removed' ? 'you were removed from this room' : 'this room has been closed');
+        super(refused === 'removed'
+            ? 'you were removed from this room'
+            : refused === 'unknown'
+                ? 'nobody in this room has let you in yet'
+                : 'this room has been closed');
         this.name = 'EpochRefusedError';
         this.refused = refused;
     }
 }
 /** Ask the authority where the room is, and wait for the answer. Rejects
  *  with `EpochRefusedError` on a refusal, and with a plain error when
- *  nobody answers inside the timeout. */
+ *  nobody answers inside the timeout. `unknown` is not final: the ask goes
+ *  on, and only a timeout after it rejects, with `EpochRefusedError`. */
 export function requestRoomEpoch(opts) {
     const now = opts.now ?? (() => Math.floor(Date.now() / 1000));
     const roomId = requireHex32(opts.roomId, 'room id');
@@ -523,6 +638,7 @@ export function requestRoomEpoch(opts) {
         let expiry;
         let unsub = () => { };
         let stopMembers = () => { };
+        let unknown = false;
         const finish = (settle) => {
             if (settled)
                 return;
@@ -536,10 +652,22 @@ export function requestRoomEpoch(opts) {
             settle();
         };
         unsub = opts.transport.subscribe([{ kinds: [KINDS.EPOCH_GRANT], '#d': [roomId], '#p': [device] }], (event) => {
-            const grant = decodeEpochGrant(event, { roomId, authority: opts.authority, deviceSk: opts.deviceSk, request: request.id, now: now() });
+            const grant = decodeEpochGrant(event, {
+                roomId,
+                authority: opts.authority,
+                deviceSk: opts.deviceSk,
+                sealSks: opts.sealSks?.(),
+                request: request.id,
+                now: now(),
+            });
             if (!grant)
                 return;
-            if (grant.refused)
+            if (grant.refused === 'unknown') {
+                if (!unknown)
+                    opts.onUnknown?.();
+                unknown = true;
+            }
+            else if (grant.refused)
                 finish(() => reject(new EpochRefusedError(grant.refused)));
             else
                 finish(() => resolve(grant));
@@ -555,7 +683,7 @@ export function requestRoomEpoch(opts) {
             if (!settled)
                 opts.transport.publish(request).catch(() => { });
         };
-        expiry = setTimeout(() => finish(() => reject(new Error('the room has moved to a newer epoch and its keeper is not answering'))), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        expiry = setTimeout(() => finish(() => reject(unknown ? new EpochRefusedError('unknown') : new Error('the room has moved to a newer epoch and its keeper is not answering'))), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
         expiry.unref?.();
         retry = setInterval(ask, opts.retryMs ?? DEFAULT_RETRY_MS);
         retry.unref?.();

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export type { DeviceCredential, AccessTier, AgentRule, RoomPolicy, KindredProof
 export type { RelayTransport } from './transport.js';
 export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
 export type { CreateCredentialOptions, VerifyResult } from './credential.js';
+export { SEAL_TAG, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
+export type { SealKey } from './seal.js';
 export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
 export type { ScopedKeys } from './scoped.js';
 export { createSubKeyCertificate, verifySubKeyCertificate, SUB_KEY_CERTIFICATE_SCOPE, } from './sub-cert.js';
@@ -24,8 +26,8 @@ export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } fr
 export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
 export type { RoomLink } from './link.js';
-export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
-export type { RoomEpoch, EpochKeys, EncodeRekeyOptions, RekeyNotice, PeekRekeyOptions, DecodeRekeyOptions, EpochRequestAdmissionOptions, EncodeEpochRequestOptions, DecodeEpochRequestOptions, EpochRequest, EpochRefusal, EncodeEpochGrantOptions, DecodeEpochGrantOptions, EpochGrant, HostRoomEpochOptions, RequestRoomEpochOptions, SignAdminsOptions, SignChannelsOptions, VerifyChannelsOptions, VerifyAdminsOptions, } from './epoch.js';
+export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, sealCredential, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export type { RoomEpoch, EpochKeys, EncodeRekeyOptions, RekeyRecipient, RekeyNotice, PeekRekeyOptions, DecodeRekeyOptions, EpochRequestAdmissionOptions, EncodeEpochRequestOptions, DecodeEpochRequestOptions, EpochRequest, EpochRefusal, EncodeEpochGrantOptions, DecodeEpochGrantOptions, EpochGrant, HostRoomEpochOptions, RequestRoomEpochOptions, SignAdminsOptions, SignChannelsOptions, VerifyChannelsOptions, VerifyAdminsOptions, } from './epoch.js';
 export { EPOCH_COMMIT_PREFIX, epochCommitment, EPOCH_COMMIT_LABELS } from './epoch-commit.js';
 export { MEMBER_EPOCH_KINDS, MEMBER_EPOCH_REQUEST_KEY_INFO, MAX_MEMBER_EPOCH_CHAIN, deriveMemberEpochRequestKey, readRekeyEvidence, encodeMemberEpochRequest, decodeMemberEpochRequest, encodeMemberEpochGrant, decodeMemberEpochGrant, hostMemberEpochDesk, memberEpochSource, requestMemberEpoch, MEMBER_EPOCH_LABELS, } from './member-epoch.js';
 export type { RekeyEvidence, EncodeMemberEpochRequestOptions, DecodeMemberEpochRequestOptions, MemberEpochRequest, EncodeMemberEpochGrantOptions, DecodeMemberEpochGrantOptions, MemberEpochGrant, HostMemberEpochDeskOptions, MemberEpochRequestOptions, MemberEpochSource, } from './member-epoch.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export { verifyEventUncached, boundedEventVerifier } from './verify.js';
 export { localIdentity } from './identity.js';
 export { KINDS } from './kinds.js';
 export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
+export { SEAL_TAG, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
 export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
 export { createSubKeyCertificate, verifySubKeyCertificate, SUB_KEY_CERTIFICATE_SCOPE, } from './sub-cert.js';
 export { generateRoomSecret, deriveRoom, encodeJoinUrl, decodeJoinUrl, parseRoomPolicy, ROOM_LABELS, } from './room.js';
@@ -16,7 +17,7 @@ export { encodePersistentInvitation, decodePersistentInvitation, requestPersiste
 export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } from './expiration.js';
 export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
-export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, sealCredential, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
 export { EPOCH_COMMIT_PREFIX, epochCommitment, EPOCH_COMMIT_LABELS } from './epoch-commit.js';
 export { MEMBER_EPOCH_KINDS, MEMBER_EPOCH_REQUEST_KEY_INFO, MAX_MEMBER_EPOCH_CHAIN, deriveMemberEpochRequestKey, readRekeyEvidence, encodeMemberEpochRequest, decodeMemberEpochRequest, encodeMemberEpochGrant, decodeMemberEpochGrant, hostMemberEpochDesk, memberEpochSource, requestMemberEpoch, MEMBER_EPOCH_LABELS, } from './member-epoch.js';
 export { deriveChannel, CHANNEL_ID_INFO, CHANNEL_KEY_INFO, MAX_CHANNEL_NAME_LENGTH, CHANNEL_LABELS } from './channel.js';