@forgesworn/fold-kit 0.7.0 → 0.8.0

package/README.md

@@ -168,6 +168,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,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. */
@@ -139,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. */
@@ -179,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
@@ -269,6 +305,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 +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;
@@ -332,6 +382,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,8 @@ 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);
@@ -157,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,
@@ -223,6 +226,8 @@ 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;
@@ -252,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
 // ---------------------------------------------------------------------------
 /**
@@ -385,6 +425,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 +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,
@@ -456,12 +548,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 +670,8 @@ export function hostRoomEpoch(opts) {
         }
         let grant;
         try {
-            grant = refused
-                ? encodeEpochGrant({
+            if (refused) {
+                grant = encodeEpochGrant({
                     roomId,
                     authoritySk: opts.authoritySk,
                     device: request.device,
@@ -561,19 +680,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/member-epoch.d.ts

@@ -59,6 +59,8 @@ export interface RekeyEvidence {
     epoch: number;
     removed: string[];
     closed: boolean;
+    /** 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 +169,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,8 @@ export function readRekeyEvidence(event, opts) {
             removed: [...new Set(body.removed.map(normaliseHex))].sort(),
             closed: body.closed === 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 +323,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/llms.txt

@@ -82,6 +82,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.8.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,7 @@
     "vectors/circle-vectors.json",
     "vectors/member-epoch-vectors.json",
     "vectors/seal-vectors.json",
+    "vectors/schedule-vectors.json",
     "LICENSE",
     "README.md",
     "llms.txt"
@@ -35,6 +36,7 @@
     "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",
     "bundle-check": "node scripts/bundle-check.mjs",
     "tarball-smoke": "node scripts/tarball-smoke.mjs",
     "vectors": "vitest run vectors/",