@forgesworn/fold-kit 0.6.0 → 0.8.0

package/README.md

@@ -160,6 +160,22 @@ the rest).
   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`
+- Scheduled rekeys and the history window (`docs/scheduled-rekey.md`):
+  `encodeRekeyEvent({ scheduled: true })` marks a turn of the key that
+  removes nobody, read back as `RekeyNotice.scheduled` and
+  `RekeyEvidence.scheduled`; `HISTORY_WINDOW_SECONDS`, `MAX_HISTORY_EPOCHS`
+  and `epochsInWindow` are the rule for which left epochs a member reads;
+  `encodeEpochGrant({ passed })` and `hostRoomEpoch({ past })` hand those
+  epochs (`LeftEpoch`) to every device the authority grants, read back as
+  `EpochGrant.passed`. Vectors: `vectors/schedule-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

@@ -98,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,6 +111,11 @@ export interface EncodeRekeyOptions {
     /** True when the room is being closed: nobody is kept, and the event
      *  says so rather than leaving everybody to wonder. */
     closed?: boolean;
+    /** Mark this as a scheduled turn of the key rather than a removal, so
+     *  clients can let it pass quietly. Refused with a removal or a close: a
+     *  rekey that removes somebody is never quiet. Omitted, the event is
+     *  byte-identical to before. */
+    scheduled?: boolean;
     /** Write the epoch commitment into the body, so any current member can
      *  bring a device that missed this rekey up to date (see
      *  `member-epoch.ts`). Omitted, the event is byte-identical to before. */
@@ -122,6 +130,12 @@ export interface EncodeRekeyOptions {
      *  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. */
@@ -130,6 +144,10 @@ export interface RekeyNotice {
     removed: string[];
     by?: string;
     closed: boolean;
+    /** True for a scheduled turn of the key: nobody removed, the room still
+     *  open. What lets a client move on without saying so. Absent when the
+     *  body contradicts itself, so a removal is always announced. */
+    scheduled?: true;
     /** The new secret, when a copy was sealed for this device. Absent for a
      *  device that was removed, or that was not in the room when the
      *  authority rekeyed. */
@@ -160,6 +178,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
@@ -167,6 +188,33 @@ export interface DecodeRekeyOptions extends PeekRekeyOptions {
  * already past (a replay), or one sealed to an epoch it is not at.
  */
 export declare function decodeRekeyEvent(event: Event, opts: DecodeRekeyOptions): RekeyNotice | null;
+/** How long a member goes on reading an epoch the room has left: 30 days,
+ *  as long as a chat log keeps a message. */
+export declare const HISTORY_WINDOW_SECONDS: number;
+/** The most left epochs a member goes on reading, and an authority's grant
+ *  hands over, however many fall inside the window. A weekly schedule puts
+ *  about five in it; removals are what push it higher. Not
+ *  `MAX_MEMBER_EPOCH_CHAIN`, which bounds how far behind a member desk will
+ *  bring somebody. */
+export declare const MAX_HISTORY_EPOCHS = 16;
+/** An epoch the room has moved past, and when. */
+export interface LeftEpoch extends RoomEpoch {
+    /** When the room left it, in unix seconds: the `created_at` of the rekey
+     *  out of it. */
+    leftAt: number;
+}
+/**
+ * The left epochs still read at `now`: those left within
+ * `HISTORY_WINDOW_SECONDS` (one left exactly that long ago is kept), newest
+ * first, one per epoch number (the first given), at most
+ * `MAX_HISTORY_EPOCHS`. Every client applies the same rule, so what an
+ * authority hands over is what a member goes on reading. Pure, and never
+ * throws: an entry with no usable number or time is dropped.
+ */
+export declare function epochsInWindow<T extends {
+    epoch: number;
+    leftAt: number;
+}>(left: readonly T[], now: number): T[];
 /**
  * The key an epoch request's admission proof is computed under: the epoch-0
  * room key, expanded under its own info string. Taken from the room key
@@ -257,7 +305,19 @@ export interface EncodeEpochGrantOptions {
     /** The participants the authority knows, so the requester's own member
      *  desk knows them too. Omitted, the body is as before. */
     members?: string[];
+    /**
+     * The epochs the room has left that are still read (`epochsInWindow`),
+     * so a newcomer, or a device back after missing several rekeys, reads
+     * the last month and not only the current epoch. Each is after epoch 0,
+     * whose secret is the room secret and is never handed over, and before
+     * `epoch`; at most `MAX_HISTORY_EPOCHS`, each once. Omitted or empty,
+     * the body is as before.
+     */
+    passed?: readonly LeftEpoch[];
     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;
@@ -269,6 +329,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;
@@ -278,10 +341,15 @@ export type EpochGrant = {
         epoch: 0;
     };
     removed: string[];
-    /** Present on a member's answer through `requestRoomEpoch({ members })`:
-     *  the epochs it carried between the requester's and `epoch`. See
-     *  `MemberEpochGrant.passed`. The authority's own answer has none. */
-    passed?: RoomEpoch[];
+    /** Earlier epochs handed over with `epoch`, oldest first. A member's
+     *  answer through `requestRoomEpoch({ members })` carries the epochs
+     *  between the requester's and `epoch` (see `MemberEpochGrant.passed`);
+     *  the authority's carries the window's (`EncodeEpochGrantOptions.passed`),
+     *  when its desk was given them. `leftAt` is when the room left each,
+     *  when the answer said. */
+    passed?: Array<RoomEpoch & {
+        leftAt?: number;
+    }>;
     /** The participants the room knows, when the answer carried them. */
     members?: string[];
     refused?: undefined;
@@ -314,6 +382,23 @@ export interface HostRoomEpochOptions {
     /** The participants to tell a granted device about, so its own member
      *  desk knows them too. Asked on every grant. */
     members?: () => readonly string[];
+    /**
+     * The epochs the room has left, with their secrets and when it left
+     * each: every grant carries those still in the window, so a newcomer
+     * reads the last month as a returning member does. Asked on every grant.
+     * Whatever a grant could not carry (epoch 0, an epoch not before the
+     * current one, a bad secret) is left out rather than costing the grant.
+     */
+    past?: () => readonly LeftEpoch[];
+    /**
+     * 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
@@ -330,6 +415,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
@@ -370,6 +464,9 @@ export interface RequestRoomEpochOptions {
     /** 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 {

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';
 /**
@@ -142,12 +143,15 @@ export function encodeRekeyEvent(opts) {
     if (epoch !== opts.current.epoch + 1)
         throw new Error('a rekey moves the room forward by exactly one epoch');
     const removed = [...new Set(opts.removed.map((p) => requireHex32(p, 'removed participant')))].sort();
+    if (opts.scheduled && (removed.length > 0 || opts.closed))
+        throw new Error('a scheduled rekey removes nobody and does not close the room');
     const keys = {};
     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,
@@ -155,6 +159,7 @@ export function encodeRekeyEvent(opts) {
         removed,
         ...(opts.by !== undefined ? { by: requireHex32(opts.by, 'admin') } : {}),
         ...(opts.closed ? { closed: true } : {}),
+        ...(opts.scheduled ? { scheduled: true } : {}),
         ...(opts.commit ? { commit: epochCommitment(roomId, epoch, opts.next.secret) } : {}),
         ...(opts.members !== undefined ? { members: memberListOf(opts.members, removed) } : {}),
         keys,
@@ -221,17 +226,28 @@ export function decodeRekeyEvent(event, opts) {
         };
         if (typeof body.by === 'string' && HEX64.test(body.by))
             notice.by = normaliseHex(body.by);
+        if (body.scheduled === true && notice.removed.length === 0 && !notice.closed)
+            notice.scheduled = true;
         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;
@@ -241,6 +257,41 @@ export function decodeRekeyEvent(event, opts) {
     }
 }
 // ---------------------------------------------------------------------------
+// The history window
+// ---------------------------------------------------------------------------
+/** How long a member goes on reading an epoch the room has left: 30 days,
+ *  as long as a chat log keeps a message. */
+export const HISTORY_WINDOW_SECONDS = 30 * 86_400;
+/** The most left epochs a member goes on reading, and an authority's grant
+ *  hands over, however many fall inside the window. A weekly schedule puts
+ *  about five in it; removals are what push it higher. Not
+ *  `MAX_MEMBER_EPOCH_CHAIN`, which bounds how far behind a member desk will
+ *  bring somebody. */
+export const MAX_HISTORY_EPOCHS = 16;
+/**
+ * The left epochs still read at `now`: those left within
+ * `HISTORY_WINDOW_SECONDS` (one left exactly that long ago is kept), newest
+ * first, one per epoch number (the first given), at most
+ * `MAX_HISTORY_EPOCHS`. Every client applies the same rule, so what an
+ * authority hands over is what a member goes on reading. Pure, and never
+ * throws: an entry with no usable number or time is dropped.
+ */
+export function epochsInWindow(left, now) {
+    const since = now - HISTORY_WINDOW_SECONDS;
+    const usable = left.filter((e) => typeof e === 'object' && e !== null && Number.isSafeInteger(e.epoch) && e.epoch >= 0 && Number.isFinite(e.leftAt) && e.leftAt >= since);
+    const seen = new Set();
+    const out = [];
+    for (const e of usable.sort((a, b) => b.epoch - a.epoch)) {
+        if (seen.has(e.epoch))
+            continue;
+        seen.add(e.epoch);
+        out.push(e);
+        if (out.length === MAX_HISTORY_EPOCHS)
+            break;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
 // Asking the authority for the current epoch
 // ---------------------------------------------------------------------------
 /**
@@ -314,6 +365,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;
@@ -358,7 +415,7 @@ 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;
@@ -368,6 +425,56 @@ export function decodeEpochRequest(event, opts) {
  *  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;
+function passedListOf(passed, granted) {
+    if (passed.length > MAX_HISTORY_EPOCHS)
+        throw new Error(`a grant carries at most ${MAX_HISTORY_EPOCHS} passed epochs`);
+    const out = passed
+        .map((e) => {
+        const epoch = requireEpochNumber(e.epoch);
+        if (epoch < 1 || epoch >= granted)
+            throw new Error('a passed epoch comes after epoch 0 and before the one granted');
+        require32(e.secret, 'epoch secret');
+        if (!Number.isSafeInteger(e.leftAt) || e.leftAt < 0)
+            throw new Error('leftAt must be a non-negative integer');
+        return { epoch, secret: base64urlnopad.encode(e.secret), left: e.leftAt };
+    })
+        .sort((a, b) => a.epoch - b.epoch);
+    for (let i = 1; i < out.length; i += 1) {
+        if (out[i].epoch === out[i - 1].epoch)
+            throw new Error('a passed epoch is listed once');
+    }
+    return out;
+}
+/** A grant's passed epochs, or undefined unless every entry is in the form
+ *  `encodeEpochGrant` writes. One bad entry costs the history, not the
+ *  grant: the current epoch still stands. */
+function readPassedList(raw, granted) {
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_HISTORY_EPOCHS)
+        return undefined;
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== 'object' || entry === null)
+            return undefined;
+        const { epoch, secret, left } = entry;
+        if (!Number.isSafeInteger(epoch) || epoch < 1 || epoch >= granted)
+            return undefined;
+        if (out.length > 0 && epoch <= out[out.length - 1].epoch)
+            return undefined;
+        if (typeof secret !== 'string' || !Number.isSafeInteger(left) || left < 0)
+            return undefined;
+        let bytes;
+        try {
+            bytes = base64urlnopad.decode(secret);
+        }
+        catch {
+            return undefined;
+        }
+        if (bytes.length !== 32)
+            return undefined;
+        out.push({ epoch: epoch, secret: bytes, leftAt: left });
+    }
+    return out;
+}
 /** Answer one request: the current epoch sealed to the asking device, or a
  *  refusal it alone can read. */
 export function encodeEpochGrant(opts) {
@@ -390,6 +497,8 @@ export function encodeEpochGrant(opts) {
         body.removed = [...new Set((opts.removed ?? []).map((p) => requireHex32(p, 'removed participant')))].sort();
         if (opts.members !== undefined)
             body.members = memberListOf(opts.members, body.removed);
+        if (opts.passed !== undefined && opts.passed.length > 0)
+            body.passed = passedListOf(opts.passed, body.epoch);
     }
     return finalizeEvent({
         kind: KINDS.EPOCH_GRANT,
@@ -398,7 +507,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
@@ -420,7 +529,7 @@ 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' || body.refused === 'unknown')
@@ -439,12 +548,59 @@ export function decodeEpochGrant(event, opts) {
         const secret = base64urlnopad.decode(body.secret);
         if (secret.length !== 32)
             return null;
-        return { epoch: { epoch: body.epoch, secret }, removed, ...listed };
+        const passed = readPassedList(body.passed, body.epoch);
+        return { epoch: { epoch: body.epoch, secret }, removed, ...listed, ...(passed ? { passed } : {}) };
     }
     catch {
         return null;
     }
 }
+/** What a desk hands over of `past()`: the window's epochs below the one it
+ *  grants, leaving out anything `encodeEpochGrant` would refuse, so a bad
+ *  entry costs the history and never the grant. */
+function passedFor(past, granted, now) {
+    if (!past)
+        return [];
+    let given;
+    try {
+        given = past();
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(given))
+        return [];
+    const carried = given.filter((e) => typeof e === 'object' &&
+        e !== null &&
+        Number.isSafeInteger(e.epoch) &&
+        e.epoch >= 1 &&
+        e.epoch < granted &&
+        e.secret instanceof Uint8Array &&
+        e.secret.length === 32 &&
+        Number.isSafeInteger(e.leftAt) &&
+        e.leftAt >= 0);
+    return epochsInWindow(carried, now);
+}
+/**
+ * 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
@@ -483,7 +639,7 @@ export function hostRoomEpoch(opts) {
     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,
@@ -491,8 +647,9 @@ export function hostRoomEpoch(opts) {
             policy: opts.policy,
             legacyParticipants: opts.legacyParticipants,
         });
-        if (!request || answered.has(request.request))
+        if (!read || answered.has(read.request.request))
             return;
+        const request = read.request;
         let refused;
         if (opts.closed?.())
             refused = 'closed';
@@ -513,19 +670,34 @@ export function hostRoomEpoch(opts) {
         }
         let grant;
         try {
-            grant = refused
-                ? encodeEpochGrant({ roomId, authoritySk: opts.authoritySk, device: request.device, request: request.request, now: now(), refused, expiresAt: opts.expiresAt })
-                : encodeEpochGrant({
+            if (refused) {
+                grant = encodeEpochGrant({
                     roomId,
                     authoritySk: opts.authoritySk,
                     device: request.device,
                     request: request.request,
                     now: now(),
-                    epoch: opts.current(),
+                    refused,
+                    credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
+                    expiresAt: opts.expiresAt,
+                });
+            }
+            else {
+                const epoch = opts.current();
+                grant = encodeEpochGrant({
+                    roomId,
+                    authoritySk: opts.authoritySk,
+                    device: request.device,
+                    request: request.request,
+                    now: now(),
+                    epoch,
                     removed: [...opts.removed()],
                     ...(opts.members ? { members: [...opts.members()] } : {}),
+                    ...(opts.past ? { passed: passedFor(opts.past, epoch.epoch, now()) } : {}),
+                    credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
                     expiresAt: opts.expiresAt,
                 });
+            }
         }
         catch {
             return;
@@ -604,7 +776,14 @@ 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 === 'unknown') {

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, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, 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, HISTORY_WINDOW_SECONDS, MAX_HISTORY_EPOCHS, epochsInWindow, 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, LeftEpoch, 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, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, 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, HISTORY_WINDOW_SECONDS, MAX_HISTORY_EPOCHS, epochsInWindow, 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';