@forgesworn/fold-kit 0.3.0 → 0.5.0

package/README.md

@@ -118,6 +118,14 @@ the rest).
   conference room: the encrypted body carries `ends` and the event a NIP-40
   `expiration` tag, so relays drop it when the room ends; the decoder returns
   `endsAt` and refuses a tag that disagrees with the body
+- Room relays: pass `relays` (one to eight distinct safe relay URLs in
+  canonical `normalizeURL` form, e.g. `wss://relay.example.com/`) and the
+  encrypted body carries them after `ends`. Every member's pool includes
+  them, so members never land on disjoint relays. The decoder returns
+  `relays` and refuses the whole envelope on a malformed list;
+  `requestPersistentRoomAdmission` keeps the relays of the newest signed
+  copy that names any. `isInvitationRelays`, `requireInvitationRelays` and
+  `MAX_INVITATION_RELAYS` are the rule
 - `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
@@ -134,6 +142,18 @@ the rest).
   catch-up for a device that missed a rekey
 - `hostRoomEpoch`, `requestRoomEpoch`, `EpochRefusedError` - the live
   request/grant desk
+- Member epoch catch-up (`docs/member-epoch-catch-up.md`): any current
+  member can bring an admitted, non-removed device up to date when the
+  authority is offline, and the device checks the answer against the
+  authority's own signatures rather than trusting the member.
+  `encodeRekeyEvent({ commit: true })` writes the epoch commitment
+  (`epochCommitment`) into the rekey body; `hostMemberEpochDesk` answers
+  member requests (kinds 20471/20472, `MEMBER_EPOCH_KINDS`);
+  `requestRoomEpoch({ members: memberEpochSource(...) })` asks members as
+  well as the authority, and `requestMemberEpoch` asks members alone. Codecs:
+  `encodeMemberEpochRequest`, `decodeMemberEpochRequest`,
+  `encodeMemberEpochGrant`, `decodeMemberEpochGrant`, `readRekeyEvidence`,
+  `deriveMemberEpochRequestKey`. Vectors: `vectors/member-epoch-vectors.json`
 - `canonicalAdmins`, `signAdmins`, `verifyAdmins` - the authority's signed
   admin list
 - `canonicalChannels`, `signChannels`, `verifyChannels`, `CHANNEL_NAME`,

package/dist/epoch-commit.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The epoch commitment: what lets a member who is not the authority hand an
+ * epoch on, and the requester check it without trusting that member.
+ *
+ * A rekey event already commits to the secret of the epoch it LEAVES: its
+ * body is NIP-44 under that epoch's key, the authority signed the result,
+ * and NIP-44's HMAC verifies under no other key. What it does not commit
+ * to, in a form a third party can check, is the secret of the epoch it
+ * ENTERS - that rides only in the per-device seals, which nobody but the
+ * authority and the sealed device can open. This closes that one gap: an
+ * optional `commit` field in the (encrypted) rekey body, written by
+ * `encodeRekeyEvent` when asked, equal to
+ *
+ *   HMAC-SHA256(key = secret, "kithmoot/v1/epoch-commit:" + roomId + ":" + epoch)
+ *
+ * as lower-case hex, `roomId` in lower-case hex and `epoch` in decimal. A
+ * PRF keyed by the secret, so the value reveals nothing about it, and bound
+ * to the room and the number so a commitment cannot be moved between them.
+ * It lives inside the body, not in a tag, so a relay still sees nothing
+ * but a number; and it is used nowhere else on the wire, so a removed
+ * member who reads the body learns nothing it could find traffic by.
+ *
+ * Its own module, with no imports from `epoch.ts`, so that `epoch.ts` and
+ * `member-epoch.ts` can both use it without an import cycle. See
+ * `docs/member-epoch-catch-up.md`.
+ */
+export declare const EPOCH_COMMIT_PREFIX = "kithmoot/v1/epoch-commit:";
+/** The commitment a rekey to `epoch` carries for `secret` in `roomId`. */
+export declare function epochCommitment(roomId: string, epoch: number, secret: Uint8Array): string;
+/** Every wire-format literal this module owns, frozen for `src/labels.test.ts`. */
+export declare const EPOCH_COMMIT_LABELS: readonly ["kithmoot/v1/epoch-commit:"];

package/dist/epoch-commit.js

@@ -0,0 +1,46 @@
+import { hmac } from '@noble/hashes/hmac';
+import { sha256 } from '@noble/hashes/sha2';
+import { bytesToHex } from '@noble/hashes/utils';
+/**
+ * The epoch commitment: what lets a member who is not the authority hand an
+ * epoch on, and the requester check it without trusting that member.
+ *
+ * A rekey event already commits to the secret of the epoch it LEAVES: its
+ * body is NIP-44 under that epoch's key, the authority signed the result,
+ * and NIP-44's HMAC verifies under no other key. What it does not commit
+ * to, in a form a third party can check, is the secret of the epoch it
+ * ENTERS - that rides only in the per-device seals, which nobody but the
+ * authority and the sealed device can open. This closes that one gap: an
+ * optional `commit` field in the (encrypted) rekey body, written by
+ * `encodeRekeyEvent` when asked, equal to
+ *
+ *   HMAC-SHA256(key = secret, "kithmoot/v1/epoch-commit:" + roomId + ":" + epoch)
+ *
+ * as lower-case hex, `roomId` in lower-case hex and `epoch` in decimal. A
+ * PRF keyed by the secret, so the value reveals nothing about it, and bound
+ * to the room and the number so a commitment cannot be moved between them.
+ * It lives inside the body, not in a tag, so a relay still sees nothing
+ * but a number; and it is used nowhere else on the wire, so a removed
+ * member who reads the body learns nothing it could find traffic by.
+ *
+ * Its own module, with no imports from `epoch.ts`, so that `epoch.ts` and
+ * `member-epoch.ts` can both use it without an import cycle. See
+ * `docs/member-epoch-catch-up.md`.
+ */
+export const EPOCH_COMMIT_PREFIX = 'kithmoot/v1/epoch-commit:';
+const HEX64 = /^[0-9a-f]{64}$/i;
+/** The commitment a rekey to `epoch` carries for `secret` in `roomId`. */
+export function epochCommitment(roomId, epoch, secret) {
+    if (!HEX64.test(roomId))
+        throw new Error('room id must be 32-byte hex');
+    if (!Number.isSafeInteger(epoch) || epoch < 1)
+        throw new Error('only an epoch after 0 has a commitment');
+    if (secret.length !== 32)
+        throw new Error('epoch secret must be 32 bytes');
+    const message = new TextEncoder().encode(`${EPOCH_COMMIT_PREFIX}${roomId.toLowerCase()}:${epoch}`);
+    return bytesToHex(hmac(sha256, secret, message));
+}
+/** Every wire-format literal this module owns, frozen for `src/labels.test.ts`. */
+export const EPOCH_COMMIT_LABELS = [
+    "kithmoot/v1/epoch-commit:",
+];

package/dist/epoch.d.ts

@@ -1,6 +1,7 @@
 import { type Event } from 'nostr-tools/pure';
 import type { RelayTransport } from './transport.js';
 import type { DeviceCredential, KindredProof, RoomPolicy } from './types.js';
+import type { MemberEpochSource } from './member-epoch.js';
 /**
  * Room epochs: how a member is removed.
  *
@@ -103,6 +104,10 @@ 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;
+    /** 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. */
+    commit?: boolean;
     now: number;
     /** A conference room's end, in unix seconds: the event carries it as a
      *  NIP-40 expiration (see `withExpiration`). Omit for a room with no end. */
@@ -307,6 +312,9 @@ export interface RequestRoomEpochOptions {
     retryMs?: number;
     /** A conference room's end: the request carries it as an expiration. */
     expiresAt?: number;
+    /** Ask the room's current members too (`memberEpochSource`): the first
+     *  answer that checks out, the authority's or a member's, settles it. */
+    members?: MemberEpochSource;
 }
 /** Thrown when the authority answered, and the answer was no. */
 export declare class EpochRefusedError extends Error {

package/dist/epoch.js

@@ -13,6 +13,7 @@ import { verifyDeviceCredential } from './credential.js';
 import { evaluateAccess } from './access.js';
 import { verifyEventUncached } from './verify.js';
 import { withExpiration } from './expiration.js';
+import { epochCommitment } from './epoch-commit.js';
 /**
  * Room epochs: how a member is removed.
  *
@@ -140,6 +141,7 @@ export function encodeRekeyEvent(opts) {
         removed,
         ...(opts.by !== undefined ? { by: requireHex32(opts.by, 'admin') } : {}),
         ...(opts.closed ? { closed: true } : {}),
+        ...(opts.commit ? { commit: epochCommitment(roomId, epoch, opts.next.secret) } : {}),
         keys,
     };
     return finalizeEvent({
@@ -520,6 +522,7 @@ export function requestRoomEpoch(opts) {
         let retry;
         let expiry;
         let unsub = () => { };
+        let stopMembers = () => { };
         const finish = (settle) => {
             if (settled)
                 return;
@@ -529,6 +532,7 @@ export function requestRoomEpoch(opts) {
             if (expiry !== undefined)
                 clearTimeout(expiry);
             unsub();
+            stopMembers();
             settle();
         };
         unsub = opts.transport.subscribe([{ kinds: [KINDS.EPOCH_GRANT], '#d': [roomId], '#p': [device] }], (event) => {
@@ -542,6 +546,11 @@ export function requestRoomEpoch(opts) {
         });
         if (settled)
             unsub();
+        if (opts.members && !settled) {
+            stopMembers = opts.members.start((grant) => finish(() => resolve(grant)));
+            if (settled)
+                stopMembers();
+        }
         const ask = () => {
             if (!settled)
                 opts.transport.publish(request).catch(() => { });

package/dist/index.d.ts

@@ -21,10 +21,14 @@ export type { RoomInvitation, RoomInvitationHost, InvitationDelegation, RoomInvi
 export { encodePersistentInvitation, decodePersistentInvitation, requestPersistentRoomAdmission, PERSISTENT_INVITATION_LABELS, } from './persistent-invitation.js';
 export type { PersistentRoomAdmission } from './persistent-invitation.js';
 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 type { RoomLink } from './link.js';
 export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
 export type { RoomEpoch, EpochKeys, EncodeRekeyOptions, RekeyNotice, PeekRekeyOptions, DecodeRekeyOptions, EpochRequestAdmissionOptions, EncodeEpochRequestOptions, DecodeEpochRequestOptions, EpochRequest, EpochRefusal, EncodeEpochGrantOptions, DecodeEpochGrantOptions, EpochGrant, HostRoomEpochOptions, RequestRoomEpochOptions, SignAdminsOptions, SignChannelsOptions, VerifyChannelsOptions, VerifyAdminsOptions, } from './epoch.js';
+export { EPOCH_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';
 export { deriveChannel, CHANNEL_ID_INFO, CHANNEL_KEY_INFO, MAX_CHANNEL_NAME_LENGTH, CHANNEL_LABELS } from './channel.js';
 export { LANES, LANE_MEANING, LANE_LABEL, LANE_GLYPH, isLane, laneOfRelayUrl, laneOfRelays, weakestLane, isDowngrade, } from './lane.js';
 export type { Lane } from './lane.js';

package/dist/index.js

@@ -14,7 +14,10 @@ export { issueKindredProof, evaluateAccess, ACCESS_LABELS, } from './access.js';
 export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
 export { encodePersistentInvitation, decodePersistentInvitation, requestPersistentRoomAdmission, PERSISTENT_INVITATION_LABELS, } from './persistent-invitation.js';
 export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } from './expiration.js';
+export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
 export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export { EPOCH_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';
 export { LANES, LANE_MEANING, LANE_LABEL, LANE_GLYPH, isLane, laneOfRelayUrl, laneOfRelays, weakestLane, isDowngrade, } from './lane.js';

package/dist/invitation-relays.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A room's own relays, carried in its signed group invitation (kind 1463).
+ *
+ * The relays a room is created on are its meeting place: every member's pool
+ * includes them, whatever else that member uses, so two members can never
+ * end up on disjoint relays. A link's relay hints are unsigned and drift as
+ * links are re-shared; the invitation's list is signed by the inviter, so a
+ * stale bookmark converges on it.
+ *
+ * The list is strict: one to `MAX_INVITATION_RELAYS` distinct URLs, each a
+ * safe relay URL already in canonical form (`normalizeURL` from
+ * `nostr-tools/utils`: lower-case host, no default port, no trailing slash
+ * except the root's, sorted query), with no credentials. Anything else
+ * refuses the whole envelope; a list is never silently trimmed.
+ */
+/** At most this many room relays: the same bound as a link's relay hints. */
+export declare const MAX_INVITATION_RELAYS = 8;
+/** True for a list of room relays the invitation may carry. Never throws. */
+export declare function isInvitationRelays(value: unknown): value is string[];
+/** Throws unless `relays` is a list the invitation may carry; returns a copy. */
+export declare function requireInvitationRelays(relays: readonly string[]): string[];

package/dist/invitation-relays.js

@@ -0,0 +1,52 @@
+import { normalizeURL } from 'nostr-tools/utils';
+import { isSafeRelayUrl, MAX_RELAY_HINTS } from './network-hints.js';
+/**
+ * A room's own relays, carried in its signed group invitation (kind 1463).
+ *
+ * The relays a room is created on are its meeting place: every member's pool
+ * includes them, whatever else that member uses, so two members can never
+ * end up on disjoint relays. A link's relay hints are unsigned and drift as
+ * links are re-shared; the invitation's list is signed by the inviter, so a
+ * stale bookmark converges on it.
+ *
+ * The list is strict: one to `MAX_INVITATION_RELAYS` distinct URLs, each a
+ * safe relay URL already in canonical form (`normalizeURL` from
+ * `nostr-tools/utils`: lower-case host, no default port, no trailing slash
+ * except the root's, sorted query), with no credentials. Anything else
+ * refuses the whole envelope; a list is never silently trimmed.
+ */
+/** At most this many room relays: the same bound as a link's relay hints. */
+export const MAX_INVITATION_RELAYS = MAX_RELAY_HINTS;
+function isCanonicalRelayUrl(value) {
+    if (typeof value !== 'string' || !isSafeRelayUrl(value))
+        return false;
+    try {
+        const parsed = new URL(value);
+        if (parsed.username || parsed.password)
+            return false;
+        return normalizeURL(value) === value;
+    }
+    catch {
+        return false;
+    }
+}
+/** True for a list of room relays the invitation may carry. Never throws. */
+export function isInvitationRelays(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_INVITATION_RELAYS)
+        return false;
+    return value.every(isCanonicalRelayUrl) && new Set(value).size === value.length;
+}
+/** Throws unless `relays` is a list the invitation may carry; returns a copy. */
+export function requireInvitationRelays(relays) {
+    if (!Array.isArray(relays) || relays.length === 0)
+        throw new Error('a room relay list needs at least one relay');
+    if (relays.length > MAX_INVITATION_RELAYS)
+        throw new Error(`a room can list at most ${MAX_INVITATION_RELAYS} relays`);
+    for (const url of relays) {
+        if (!isCanonicalRelayUrl(url))
+            throw new Error(`room relays must be wss:// URLs (ws:// only on localhost) in canonical form, without credentials: ${String(url)}`);
+    }
+    if (new Set(relays).size !== relays.length)
+        throw new Error('room relays must not repeat');
+    return [...relays];
+}

package/dist/member-epoch.d.ts

@@ -0,0 +1,273 @@
+import { type Event } from 'nostr-tools/pure';
+import { type EpochKeys, type EpochRefusal, type RoomEpoch } from './epoch.js';
+import type { RelayTransport } from './transport.js';
+import type { DeviceCredential, KindredProof, RoomPolicy } from './types.js';
+/**
+ * Member-to-member epoch catch-up: any current member can bring an
+ * admitted, non-removed member up to date.
+ *
+ * `hostRoomEpoch` answers an epoch request only where the authority's key
+ * is, and the request is ephemeral, so a device that missed a rekey - a
+ * phone that came back with a new device key, which no stored rekey seals
+ * to - recovers only while the authority's device is online with the room
+ * open. Every other member at the current epoch holds the secret and, until
+ * now, could not pass it on in a form the requester could check.
+ *
+ * It can now, because the requester does not trust the member at all. The
+ * grant carries the authority-signed rekey events from the requester's
+ * epoch to the current one, and the secret of every epoch in between:
+ *
+ * - each rekey's signature is the authority's (`peekRekeyEvent`);
+ * - each rekey decrypts under the key of the epoch before it, starting from
+ *   the requester's own - and NIP-44's MAC verifies under no other key, so
+ *   a decrypting rekey j+1 proves the secret offered for epoch j is the one
+ *   the authority encrypted under;
+ * - the last epoch, which has no successor to vouch for it, is checked
+ *   against the commitment the authority wrote into its rekey body
+ *   (`epochCommitment`, `encodeRekeyEvent({ commit: true })`). A last rekey
+ *   with no commitment - every rekey written before this existed - is not
+ *   accepted from a member: that epoch stays authority-only.
+ *
+ * The removed and closed facts come from the same authority-signed bodies,
+ * so a member can neither hide a removal from the requester nor invent
+ * one. Answerers refuse the removed and a closed room by not answering at
+ * all; only the authority's refusal is something a requester can believe.
+ * See `docs/member-epoch-catch-up.md` for the threat model.
+ */
+/** The member path's two kinds. Ephemeral, like 20468/20469: a live
+ *  handshake, never a record. */
+export declare const MEMBER_EPOCH_KINDS: {
+    /** A device behind the room asking any current member for the epochs it
+     *  missed. Encrypted under a key from the epoch-0 room key, so any
+     *  admitted device can read it and a relay cannot. */
+    readonly REQUEST: 20471;
+    /** A member's answer, signed by a one-time key made for that grant and
+     *  sealed to the asking device: secrets plus the authority-signed rekeys
+     *  that prove them. */
+    readonly GRANT: 20472;
+};
+/** HKDF info for the key a member epoch request's body is sealed under. */
+export declare const MEMBER_EPOCH_REQUEST_KEY_INFO = "kithmoot/v1/member-epoch-request-key";
+/** The most epochs one member grant will carry. A device further behind
+ *  than this asks the authority. */
+export declare const MAX_MEMBER_EPOCH_CHAIN = 32;
+/** The key a member epoch request is sealed under: the epoch-0 room key,
+ *  expanded under its own info string. */
+export declare function deriveMemberEpochRequestKey(roomKey: Uint8Array): Uint8Array;
+/** What a rekey body says, read with the key of the epoch it leaves. */
+export interface RekeyEvidence {
+    epoch: number;
+    removed: string[];
+    closed: boolean;
+    /** The epoch commitment, when the authority wrote one. */
+    commit?: string;
+}
+/**
+ * Read an authority-signed rekey with the key of the epoch it leaves,
+ * without needing a seal of one's own. Null for anything that does not
+ * check out: not the authority, not this room, not epoch `previous.epoch
+ * + 1`, or not encrypted under `previous.key`. What both sides of a member
+ * grant use to check the chain.
+ */
+export declare function readRekeyEvidence(event: Event, opts: {
+    roomId: string;
+    authority: string;
+    previous: EpochKeys;
+}): RekeyEvidence | null;
+export interface EncodeMemberEpochRequestOptions {
+    roomId: string;
+    /** The room's authority: bound into the admission proof. */
+    authority: string;
+    deviceSk: Uint8Array;
+    /** The epoch-0 room key: seals the body and makes the admission proof. */
+    roomKey: Uint8Array;
+    credential: DeviceCredential;
+    proof?: KindredProof;
+    /** The epoch this device is at. */
+    have: number;
+    now: number;
+    expiresAt?: number;
+}
+/** Ask any current member for the epochs after `have`. */
+export declare function encodeMemberEpochRequest(opts: EncodeMemberEpochRequestOptions): Event;
+export interface DecodeMemberEpochRequestOptions {
+    roomId: string;
+    authority: string;
+    roomKey: Uint8Array;
+    now: number;
+    policy?: RoomPolicy;
+    maxAgeSeconds?: number;
+}
+export interface MemberEpochRequest {
+    device: string;
+    participant: string;
+    request: string;
+    have: number;
+}
+/** Null for anything malformed, stale, from a device that cannot prove
+ *  which participant it speaks for, or that cannot prove admission. */
+export declare function decodeMemberEpochRequest(event: Event, opts: DecodeMemberEpochRequestOptions): MemberEpochRequest | null;
+export interface EncodeMemberEpochGrantOptions {
+    roomId: string;
+    /** The asking device. */
+    device: string;
+    request: string;
+    /** Epochs have+1 .. current, in order. */
+    epochs: RoomEpoch[];
+    /** The authority's rekey event for each of `epochs`, in the same order. */
+    rekeys: Event[];
+    now: number;
+    expiresAt?: number;
+}
+/**
+ * Answer one member epoch request with the epochs it missed.
+ *
+ * The grant is signed, and sealed to the asking device, by a fresh key made
+ * for it alone and then dropped, not by the answering member's device key.
+ * Nothing about a grant is trusted on its signer (the authority's
+ * signatures are what the requester checks), so the member's key would add
+ * nothing but a public line from that device to the room id in the `d` tag.
+ */
+export declare function encodeMemberEpochGrant(opts: EncodeMemberEpochGrantOptions): Event;
+export interface DecodeMemberEpochGrantOptions {
+    roomId: string;
+    authority: string;
+    /** The asking device's key. */
+    deviceSk: Uint8Array;
+    /** The ids of this device's own outstanding member requests. */
+    requests: ReadonlySet<string>;
+    /** Where this device is: the chain starts from this epoch's key. */
+    current: EpochKeys;
+    /** The participant this device speaks for: a chain that removes it is
+     *  refused. */
+    participant: string;
+    /** The cumulative removed set this device already knows. Read once per
+     *  call. */
+    removed?: Iterable<string>;
+    /** The highest epoch this device has seen a valid rekey for. A grant
+     *  that stops short of it is refused, so a member removed at that epoch
+     *  cannot hold the requester one epoch back on a key it still has. */
+    expected?: number;
+    now: number;
+    maxAgeSeconds?: number;
+}
+/** A member grant, verified. */
+export interface MemberEpochGrant {
+    epoch: RoomEpoch;
+    /** Cumulative: `opts.removed` plus every removal in the chain. */
+    removed: string[];
+}
+/**
+ * Verify a member's answer to one of this device's member requests. Null
+ * for anything that does not check out - see the module comment and
+ * `docs/member-epoch-catch-up.md` "Verification rules" for each check.
+ */
+export declare function decodeMemberEpochGrant(event: Event, opts: DecodeMemberEpochGrantOptions): MemberEpochGrant | null;
+export interface HostMemberEpochDeskOptions {
+    transport: RelayTransport;
+    roomId: string;
+    authority: string;
+    /** This member's device key: the desk ignores requests from it. Grants
+     *  are signed by a one-time key each (see `encodeMemberEpochGrant`). */
+    deviceSk: Uint8Array;
+    /** The epoch-0 room key: opens requests and checks admission proofs. */
+    roomKey: Uint8Array;
+    /** Where this device is now, or undefined while it is not in step (behind,
+     *  removed, leaving). Asked on every request. */
+    current: () => RoomEpoch | undefined;
+    /** The secret of an earlier epoch this device still holds, for a
+     *  requester more than one epoch behind. Optional: without it this desk
+     *  serves only requesters exactly one epoch behind. */
+    secretAt?: (epoch: number) => Uint8Array | undefined;
+    /** The authority's rekey event into `epoch`, as this device stored it. */
+    rekeyAt: (epoch: number) => Event | undefined;
+    /** The cumulative removed set, as the authority's rekeys told this device. */
+    removed: () => ReadonlySet<string>;
+    /** True once the room has been closed. */
+    closed?: () => boolean;
+    policy?: RoomPolicy;
+    now?: () => number;
+    /** Upper bound of the random wait before answering, so several members do
+     *  not all answer at once. 0 answers at once. Default 1500. */
+    jitterMs?: number;
+    /** For tests: a source of numbers in [0, 1). Default `Math.random`. */
+    random?: () => number;
+    /** The largest serialised grant this desk will publish. Default 60000:
+     *  under the 64 KiB many relays enforce. A longer chain is left to the
+     *  authority. */
+    maxGrantBytes?: number;
+    onGranted?: (request: MemberEpochRequest) => void;
+    /** Called when this desk declines a removed participant or a closed room.
+     *  Nothing is published either way: a member's refusal is not something a
+     *  requester could believe, so it is not sent. */
+    onRefused?: (request: MemberEpochRequest, why: EpochRefusal) => void;
+    expiresAt?: number;
+}
+/**
+ * Answer member epoch requests for as long as the handle is open: what any
+ * member at the current epoch runs beside its session. It answers only an
+ * admitted, credentialled device that is not removed, in a room that is not
+ * closed, and only when it can hand over the whole chain from the
+ * requester's epoch to its own with the authority's rekeys to prove it.
+ *
+ * Anti-amplification: each answer waits a random `[0, jitterMs)`, and is
+ * dropped if another member's grant to the same device appears meanwhile.
+ * It is dropped at most once per requesting device: the requester asks again
+ * with a fresh request if what it got did not verify, and the second time
+ * every desk answers, so a stranger posting junk grants costs one round.
+ */
+export declare function hostMemberEpochDesk(opts: HostMemberEpochDeskOptions): {
+    close(): void;
+};
+export interface MemberEpochRequestOptions {
+    transport: RelayTransport;
+    roomId: string;
+    authority: string;
+    deviceSk: Uint8Array;
+    /** The epoch-0 room key. */
+    roomKey: Uint8Array;
+    credential: DeviceCredential;
+    proof?: KindredProof;
+    /** Where this device is now. Asked each time a request goes out. */
+    current: EpochKeys | (() => EpochKeys);
+    /** The cumulative removed set this device already knows. A function is
+     *  asked on every grant; anything else is read once, when the source is
+     *  made, so a generator or other one-shot iterable is not used up by the
+     *  first grant and seen as empty by the next. */
+    removed?: Iterable<string> | (() => Iterable<string>);
+    /** The highest epoch a valid rekey has been seen for: see
+     *  `DecodeMemberEpochGrantOptions.expected`. The source also watches the
+     *  room's rekeys on `transport` itself and floors every grant at the
+     *  newest authority-signed one it sees, so this is only for what the
+     *  caller learnt elsewhere. */
+    expected?: number | (() => number | undefined);
+    now?: () => number;
+    /** How often a fresh request goes out. Default 4000 ms. */
+    retryMs?: number;
+    expiresAt?: number;
+}
+/** What `requestRoomEpoch({ members })` takes: a second source of answers
+ *  that starts when the request does and stops when it settles. */
+export interface MemberEpochSource {
+    start(onGrant: (grant: MemberEpochGrant) => void): () => void;
+}
+/**
+ * The member side of a catch-up, for `requestRoomEpoch({ members })`. Each
+ * round publishes a fresh request (a new id, so a desk that stood down once
+ * answers it), and the first grant that verifies is handed to `onGrant`.
+ *
+ * It subscribes to the room's rekeys (kind 1462) before it asks, and refuses
+ * any grant that stops short of the newest one the authority signed: rule 3
+ * of `docs/member-epoch-catch-up.md`, enforced here rather than left to the
+ * caller, because a member removed at epoch E still holds E-1 and every
+ * rekey up to it, and would otherwise hold the requester on a key it shares.
+ */
+export declare function memberEpochSource(opts: MemberEpochRequestOptions): MemberEpochSource;
+/** Ask the room's current members alone (no authority) for the epochs this
+ *  device missed. Rejects with a plain error when no verifiable answer comes
+ *  inside the timeout. Most callers want `requestRoomEpoch({ members })`. */
+export declare function requestMemberEpoch(opts: MemberEpochRequestOptions & {
+    timeoutMs?: number;
+}): Promise<MemberEpochGrant>;
+/** Every wire-format literal this module owns, frozen for `src/labels.test.ts`. */
+export declare const MEMBER_EPOCH_LABELS: readonly ["kithmoot/v1/member-epoch-request-key"];