@forgesworn/fold-kit 0.7.0 → 0.9.0

package/README.md

@@ -126,6 +126,16 @@ the rest).
   `requestPersistentRoomAdmission` keeps the relays of the newest signed
   copy that names any. `isInvitationRelays`, `requireInvitationRelays` and
   `MAX_INVITATION_RELAYS` are the rule
+- Self-destructing rooms (`docs/room-destruct.md`): pass `destruct: true`
+  and the encrypted body carries it after `ends` (no end needed: the room
+  then self-destructs when its authority closes it). The decoder returns
+  `destruct: true` and refuses the envelope on any other value;
+  `requestPersistentRoomAdmission` keeps it if any signed copy says it.
+  `encodeInvitationRetirement({ ended: true, destruct: true })` and
+  `encodeRekeyEvent({ closed: true, destruct: true })` carry it when the
+  room ends early, read back by `decodeInvitationRetirementNotice`,
+  `RekeyNotice.destruct` and `RekeyEvidence.destruct`. Vectors:
+  `vectors/destruct-vectors.json`
 - `withExpiration`, `isRoomEnds`, `requireRoomEnds`, `MAX_ROOM_ENDS_SECONDS` -
   the conference-room expiration rule: add the end as an `expiration` tag,
   keep an earlier one, lower a later one. `encodeInvitationRetirement` takes
@@ -168,6 +178,14 @@ the rest).
   `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/epoch.d.ts

@@ -111,6 +111,15 @@ 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;
+    /** The room being closed self-destructs: every device deletes what it
+     *  wrote and forgets the room. Inside the encrypted body. Refused
+     *  without `closed`. Omitted, the event is byte-identical to before. */
+    destruct?: 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. */
@@ -139,6 +148,14 @@ export interface RekeyNotice {
     removed: string[];
     by?: string;
     closed: boolean;
+    /** True when the closed room self-destructs. Absent unless `closed`:
+     *  beside an open room the flag is not believed, and the rekey is read
+     *  as if it were not there. */
+    destruct?: true;
+    /** 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. */
@@ -179,6 +196,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
@@ -269,6 +313,15 @@ 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`). */
@@ -296,10 +349,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;
@@ -332,6 +390,14 @@ 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

package/dist/epoch.js

@@ -143,6 +143,10 @@ 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');
+    if (opts.destruct && !opts.closed)
+        throw new Error('only a closing rekey can self-destruct the room');
     const keys = {};
     const sealed = { v: 1, secret: base64urlnopad.encode(opts.next.secret) };
     const plaintext = JSON.stringify(sealed);
@@ -157,6 +161,8 @@ export function encodeRekeyEvent(opts) {
         removed,
         ...(opts.by !== undefined ? { by: requireHex32(opts.by, 'admin') } : {}),
         ...(opts.closed ? { closed: true } : {}),
+        ...(opts.destruct ? { destruct: true } : {}),
+        ...(opts.scheduled ? { scheduled: true } : {}),
         ...(opts.commit ? { commit: epochCommitment(roomId, epoch, opts.next.secret) } : {}),
         ...(opts.members !== undefined ? { members: memberListOf(opts.members, removed) } : {}),
         keys,
@@ -223,6 +229,10 @@ export function decodeRekeyEvent(event, opts) {
         };
         if (typeof body.by === 'string' && HEX64.test(body.by))
             notice.by = normaliseHex(body.by);
+        if (body.destruct === true && notice.closed)
+            notice.destruct = true;
+        if (body.scheduled === true && notice.removed.length === 0 && !notice.closed)
+            notice.scheduled = true;
         const members = readMemberList(body.members);
         if (members)
             notice.members = members;
@@ -252,6 +262,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
 // ---------------------------------------------------------------------------
 /**
@@ -385,6 +430,56 @@ function readEpochRequest(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) {
@@ -407,6 +502,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,
@@ -456,12 +553,39 @@ 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
@@ -551,8 +675,8 @@ export function hostRoomEpoch(opts) {
         }
         let grant;
         try {
-            grant = refused
-                ? encodeEpochGrant({
+            if (refused) {
+                grant = encodeEpochGrant({
                     roomId,
                     authoritySk: opts.authoritySk,
                     device: request.device,
@@ -561,19 +685,24 @@ export function hostRoomEpoch(opts) {
                     refused,
                     credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
                     expiresAt: opts.expiresAt,
-                })
-                : encodeEpochGrant({
+                });
+            }
+            else {
+                const epoch = opts.current();
+                grant = encodeEpochGrant({
                     roomId,
                     authoritySk: opts.authoritySk,
                     device: request.device,
                     request: request.request,
                     now: now(),
-                    epoch: opts.current(),
+                    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;

package/dist/index.d.ts

@@ -26,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, 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_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

@@ -17,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, sealCredential, 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';

package/dist/invitation.d.ts

@@ -165,6 +165,12 @@ export interface EncodeInvitationRetirementOptions {
     /** The room itself was ended, not just this link replaced. Additive: a
      * reader that predates it still sees an ordinary retirement. */
     ended?: boolean;
+    /** The ended room self-destructs: every device deletes what it wrote and
+     * forgets the room. Only beside `ended`, else it throws. Unlike the
+     * invitation's own flag this content is not encrypted: it says no more
+     * than `ended` does about a link nobody outside the room can name.
+     * Omitted or false, the event is byte-identical to 0.8.0's. */
+    destruct?: boolean;
     /** A conference room's end, in unix seconds: the tombstone carries the
      * same NIP-40 expiration as the invitation it retires, and lapses with it. */
     endsAt?: number;
@@ -176,10 +182,12 @@ export declare function encodeInvitationRetirement(opts: EncodeInvitationRetirem
 /** A valid tombstone never expires: invitation ids are random and unique,
  * and a retired bearer must not become usable again after a timeout. */
 export declare function decodeInvitationRetirement(event: Event, invitation: RoomInvitation): boolean;
-/** A valid retirement, and whether it says the room was ended. Undefined
- * for anything that is not a valid retirement of this invitation. */
+/** A valid retirement, whether it says the room was ended, and whether the
+ * ended room self-destructs (`destruct`, believed only beside `ended`).
+ * Undefined for anything that is not a valid retirement of this invitation. */
 export declare function decodeInvitationRetirementNotice(event: Event, invitation: RoomInvitation): {
     ended: boolean;
+    destruct?: true;
 } | undefined;
 /** The error a joiner rejects with on a retirement. */
 export declare function retirementError(notice: {

package/dist/invitation.js

@@ -279,11 +279,13 @@ export function encodeInvitationRetirement(opts) {
     if (!hexEquals(getPublicKey(opts.inviterSk), opts.invitation.inviter)) {
         throw new Error('only the root inviter can retire an invitation');
     }
+    if (opts.destruct && !opts.ended)
+        throw new Error('only an ended room can self-destruct');
     return finalizeEvent({
         kind: KINDS.INVITATION_RETIREMENT,
         created_at: opts.now,
         tags: withExpiration([['d', deriveInvitationId(opts.invitation)]], opts.endsAt),
-        content: JSON.stringify(opts.ended ? { v: 1, ended: true } : { v: 1 }),
+        content: JSON.stringify(opts.ended ? (opts.destruct ? { v: 1, ended: true, destruct: true } : { v: 1, ended: true }) : { v: 1 }),
     }, opts.inviterSk);
 }
 /** A valid tombstone never expires: invitation ids are random and unique,
@@ -291,8 +293,9 @@ export function encodeInvitationRetirement(opts) {
 export function decodeInvitationRetirement(event, invitation) {
     return decodeInvitationRetirementNotice(event, invitation) !== undefined;
 }
-/** A valid retirement, and whether it says the room was ended. Undefined
- * for anything that is not a valid retirement of this invitation. */
+/** A valid retirement, whether it says the room was ended, and whether the
+ * ended room self-destructs (`destruct`, believed only beside `ended`).
+ * Undefined for anything that is not a valid retirement of this invitation. */
 export function decodeInvitationRetirementNotice(event, invitation) {
     try {
         if (event.kind !== KINDS.INVITATION_RETIREMENT)
@@ -304,7 +307,9 @@ export function decodeInvitationRetirementNotice(event, invitation) {
         if (event.tags.find((tag) => tag[0] === 'd')?.[1] !== deriveInvitationId(invitation))
             return undefined;
         const body = JSON.parse(event.content);
-        return body.v === 1 ? { ended: body.ended === true } : undefined;
+        if (body.v !== 1)
+            return undefined;
+        return body.ended === true && body.destruct === true ? { ended: true, destruct: true } : { ended: body.ended === true };
     }
     catch {
         return undefined;

package/dist/member-epoch.d.ts

@@ -59,6 +59,10 @@ export interface RekeyEvidence {
     epoch: number;
     removed: string[];
     closed: boolean;
+    /** The closed room self-destructs: see `RekeyNotice.destruct`. */
+    destruct?: true;
+    /** A scheduled turn of the key: see `RekeyNotice.scheduled`. */
+    scheduled?: true;
     /** The epoch commitment, when the authority wrote one. */
     commit?: string;
     /** The authority's member list, when it wrote one. */
@@ -167,8 +171,11 @@ export interface MemberEpochGrant {
     /** The epochs between the requester's and `epoch`, oldest first, each
      *  proven by the next rekey in the chain decrypting under it. Empty for a
      *  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[];
+     *  in the epochs it skipped, and hand them on from its own member desk.
+     *  `leftAt` is the `created_at` of the authority's rekey out of each. */
+    passed: Array<RoomEpoch & {
+        leftAt?: number;
+    }>;
     /** The newest member list in the chain, when any rekey in it had one. */
     members?: string[];
 }

package/dist/member-epoch.js

@@ -117,6 +117,10 @@ export function readRekeyEvidence(event, opts) {
             removed: [...new Set(body.removed.map(normaliseHex))].sort(),
             closed: body.closed === true,
         };
+        if (body.destruct === true && evidence.closed)
+            evidence.destruct = true;
+        if (body.scheduled === true && evidence.removed.length === 0 && !evidence.closed)
+            evidence.scheduled = true;
         if (typeof body.commit === 'string' && HEX64.test(body.commit))
             evidence.commit = normaliseHex(body.commit);
         const members = readMemberList(body.members);
@@ -321,8 +325,10 @@ export function decodeMemberEpochGrant(event, opts) {
                     return null;
             }
             previous = deriveEpoch({ epoch: evidence.epoch, secret });
+            // The next rekey, signed and checked on the next turn, is when the
+            // room left this epoch.
             if (i < length - 1)
-                passed.push({ epoch: evidence.epoch, secret });
+                passed.push({ epoch: evidence.epoch, secret, leftAt: body.rekeys[i + 1].created_at });
         }
         return { epoch: { epoch: top, secret: secret }, removed: [...removed].sort(), passed, ...(members ? { members } : {}) };
     }

package/dist/persistent-invitation.d.ts

@@ -13,6 +13,9 @@ export interface PersistentRoomAdmission {
     /** The room's own relays, as its inviter signed them: every member's pool
      *  includes them. Absent from an invitation written before 0.4.0. */
     relays?: string[];
+    /** The room self-destructs: when it ends, every device deletes what it
+     *  wrote and forgets the room. Absent for a room that simply ends. */
+    destruct?: true;
 }
 /** Publish once before sharing. The link plus this envelope is a durable
  * bearer capability: anybody holding both can learn epoch 0. Retirement
@@ -30,6 +33,10 @@ export declare function encodePersistentInvitation(opts: {
      *  form (see `isInvitationRelays`), else it throws. Omitted, the body is
      *  byte-identical to 0.3.0's. */
     relays?: readonly string[];
+    /** The room self-destructs when it ends, by its time or by its authority
+     *  closing it. Written inside the encrypted body only, never as a tag.
+     *  Omitted or false, the event is byte-identical to 0.8.0's. */
+    destruct?: boolean;
 }): Event;
 export declare function decodePersistentInvitation(event: Event, invitation: RoomInvitation): PersistentRoomAdmission | null;
 /** Fetch the signed envelope and retirement in ONE stored-event query.

package/dist/persistent-invitation.js

@@ -30,7 +30,7 @@ export function encodePersistentInvitation(opts) {
         created_at: opts.now,
         tags: ends === undefined ? [['d', deriveInvitationId(opts.invitation)]] : [['d', deriveInvitationId(opts.invitation)], ['expiration', String(ends)]],
         content: nip44.v2.encrypt(JSON.stringify({
-            v: 3, room, secret: base64urlnopad.encode(opts.roomSecret), ...(ends === undefined ? {} : { ends }), ...(relays === undefined ? {} : { relays }),
+            v: 3, room, secret: base64urlnopad.encode(opts.roomSecret), ...(ends === undefined ? {} : { ends }), ...(opts.destruct ? { destruct: true } : {}), ...(relays === undefined ? {} : { relays }),
         }), welcomeKey(opts.invitation)),
     }, opts.inviterSk);
 }
@@ -62,9 +62,15 @@ export function decodePersistentInvitation(event, invitation) {
         // would write; a malformed one refuses the envelope rather than half of it.
         if (body.relays !== undefined && !isInvitationRelays(body.relays))
             return null;
+        // Self-destruct is `true` or absent; anything else is a malformed
+        // envelope, refused as a malformed end is.
+        if (body.destruct !== undefined && body.destruct !== true)
+            return null;
         const admission = ends === undefined ? { secret, persistent: true, epoch: 0 } : { secret, persistent: true, epoch: 0, endsAt: ends };
         if (body.relays !== undefined)
             admission.relays = [...body.relays];
+        if (body.destruct === true)
+            admission.destruct = true;
         return admission;
     }
     catch {
@@ -119,6 +125,10 @@ export function requestPersistentRoomAdmission(opts) {
                 // end stands, so a stale copy can never keep a room open longer.
                 if (admission?.endsAt !== undefined && (decoded.endsAt === undefined || decoded.endsAt > admission.endsAt))
                     decoded.endsAt = admission.endsAt;
+                // Two signed copies that disagree on self-destruct: it sticks, for
+                // the same reason, so a stale copy can never keep a room's content.
+                if (admission?.destruct)
+                    decoded.destruct = true;
                 // Two signed copies that disagree on the room's relays: the newest
                 // copy that names any stands. A copy naming none (an older writer)
                 // says nothing about them, and on equal timestamps the first heard stays.

package/llms.txt

@@ -68,6 +68,7 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `requestPersistentRoomAdmission(opts)` - joins from stored admission alone, no live desk needed
 - Conference rooms: `encodePersistentInvitation({ ..., endsAt })` puts `ends` in the body and `['expiration', String(endsAt)]` on the 1463; `decodePersistentInvitation` returns `endsAt` and is null when an `expiration` tag disagrees with the body; `encodeInvitationRetirement({ ..., endsAt })` tags the 1461 the same way
 - Room relays: `encodePersistentInvitation({ ..., relays })` puts the room's own relays (1-8 distinct canonical `wss://host/` URLs, else it throws) in the body after `ends`; the decoder returns `relays` and is null on a malformed list; `requestPersistentRoomAdmission` keeps the newest signed copy's list (a copy without one says nothing); `isInvitationRelays`, `requireInvitationRelays`, `MAX_INVITATION_RELAYS` (8)
+- Self-destructing rooms (see `docs/room-destruct.md`): `encodePersistentInvitation({ ..., destruct: true })` puts `"destruct": true` in the encrypted body after `ends` (valid without `ends`), never a tag; `decodePersistentInvitation` returns `destruct: true` and is null when the field is present and not `true`; `requestPersistentRoomAdmission` keeps `destruct` if any valid copy carries it (sticky, like the earliest `ends`). `encodeInvitationRetirement({ ..., ended: true, destruct: true })` writes `{"v":1,"ended":true,"destruct":true}` (plain JSON, like `ended`) and throws on `destruct` without `ended`; `decodeInvitationRetirementNotice` returns `{ ended, destruct?: true }`, believing `destruct` only beside `ended`. `encodeRekeyEvent({ ..., closed: true, destruct: true })` writes it in the encrypted body after `closed` and throws without `closed`; `RekeyNotice.destruct` / `RekeyEvidence.destruct` are set only on a closing body, and a flag on an open rekey is dropped, not refused. Without the flag every event is byte-identical to 0.8.0, and a 0.8.0 reader ignores it
 - `withExpiration(tags, expiresAt?)` - NIP-40 rule for a room that ends: add the tag, keep an earlier one, lower a later one; `isRoomEnds`, `requireRoomEnds(endsAt, now)`, `MAX_ROOM_ENDS_SECONDS` (30 days)
 - Epoch encoders (`encodeRekeyEvent`, `encodeEpochRequest`, `encodeEpochGrant`) and `hostRoomEpoch` / `requestRoomEpoch` take `expiresAt?` for a conference room
 
@@ -82,6 +83,7 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - 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
+- Scheduled rekeys and the history window (see `docs/scheduled-rekey.md`): `encodeRekeyEvent({ ..., scheduled: true })` writes `"scheduled": true` inside the encrypted body (never a tag), and throws beside a non-empty `removed` or `closed`; `decodeRekeyEvent` (`RekeyNotice.scheduled`) and `readRekeyEvidence` (`RekeyEvidence.scheduled`) report `true` only when `removed` is empty and the room is not closed, so a contradictory body is still announced. `HISTORY_WINDOW_SECONDS` (30 days) and `MAX_HISTORY_EPOCHS` (16); `epochsInWindow(left, now)` keeps entries with `leftAt >= now - HISTORY_WINDOW_SECONDS`, newest first by epoch, first of a doubled epoch, at most 16, never throws. `encodeEpochGrant({ ..., passed })` takes `LeftEpoch[]` (`{ epoch, secret, leftAt }`) and writes `passed: [{ epoch, secret (base64url), left }]` oldest first, only when non-empty; it throws on more than 16, epoch 0 (the room secret is never carried), an epoch not below the granted one, a doubled epoch, a non-32-byte secret or a bad `leftAt`. `hostRoomEpoch({ past })` is asked on every grant, filtered to what the encoder accepts and to `epochsInWindow`, so a bad `past()` costs the history, not the grant. `decodeEpochGrant` returns `EpochGrant.passed` (`leftAt` set) only when the list is exactly in that form, else drops the field and keeps the grant; `decodeMemberEpochGrant` sets `leftAt` on each passed epoch from the next rekey's `created_at`. `MAX_MEMBER_EPOCH_CHAIN` (32) is a different limit. Without the marker and `passed` every event is byte-identical to 0.7.0, and a 0.7.0 reader ignores both
 - `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.7.0",
+  "version": "0.9.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",
@@ -22,6 +22,8 @@
     "vectors/circle-vectors.json",
     "vectors/member-epoch-vectors.json",
     "vectors/seal-vectors.json",
+    "vectors/schedule-vectors.json",
+    "vectors/destruct-vectors.json",
     "LICENSE",
     "README.md",
     "llms.txt"
@@ -35,6 +37,8 @@
     "generate-fold": "node scripts/generate-fold.mjs",
     "generate-member-epoch": "node scripts/generate-member-epoch.mjs",
     "generate-seal": "node scripts/generate-seal.mjs",
+    "generate-schedule": "node scripts/generate-schedule.mjs",
+    "generate-destruct": "node scripts/generate-destruct.mjs",
     "bundle-check": "node scripts/bundle-check.mjs",
     "tarball-smoke": "node scripts/tarball-smoke.mjs",
     "vectors": "vitest run vectors/",