@forgesworn/fold-kit 0.5.1 → 0.6.0

package/README.md

@@ -154,6 +154,12 @@ the rest).
   `encodeMemberEpochRequest`, `decodeMemberEpochRequest`,
   `encodeMemberEpochGrant`, `decodeMemberEpochGrant`, `readRekeyEvidence`,
   `deriveMemberEpochRequestKey`. Vectors: `vectors/member-epoch-vectors.json`
+- The known-members gate (#207, `docs/member-epoch-catch-up.md`): once a
+  room has removed anybody, both desks grant only to participants the room
+  knows (`known`), and send anybody else to approval (`onUnknown`; the
+  authority answers `refused: 'unknown'`, which `requestRoomEpoch` waits
+  through). `encodeRekeyEvent({ members })` and `hostRoomEpoch({ members })`
+  carry the authority's member list (`readMemberList` reads one)
 - `canonicalAdmins`, `signAdmins`, `verifyAdmins` - the authority's signed
   admin list
 - `canonicalChannels`, `signChannels`, `verifyChannels`, `CHANNEL_NAME`,

package/dist/epoch.d.ts

@@ -73,6 +73,10 @@ export interface EpochKeys {
     /** The cipher key. The room key in epoch 0. */
     key: Uint8Array;
 }
+/** A participant list as a body carries it: lower-case, deduplicated and
+ *  sorted, or undefined when the field is absent or is not a list of keys.
+ *  Undefined is the safe reading, since it makes nobody known. */
+export declare function readMemberList(raw: unknown): string[] | undefined;
 /** A fresh secret for the next epoch. */
 export declare function generateEpochSecret(): Uint8Array;
 /**
@@ -108,6 +112,11 @@ export interface EncodeRekeyOptions {
      *  bring a device that missed this rekey up to date (see
      *  `member-epoch.ts`). Omitted, the event is byte-identical to before. */
     commit?: boolean;
+    /** Every participant the authority knows to be in the room, not only the
+     *  ones present now: a member who is offline as the room rekeys is still
+     *  a member. Removed participants are dropped. Omitted, the event is
+     *  byte-identical to before. */
+    members?: string[];
     now: number;
     /** A conference room's end, in unix seconds: the event carries it as a
      *  NIP-40 expiration (see `withExpiration`). Omit for a room with no end. */
@@ -125,6 +134,9 @@ export interface RekeyNotice {
      *  device that was removed, or that was not in the room when the
      *  authority rekeyed. */
     secret?: Uint8Array;
+    /** The participants the authority listed as in the room. Absent from a
+     *  rekey written without the list. */
+    members?: string[];
     /** True for a current-state grant, whose removed list is cumulative.
      *  It synchronises this session; it does not describe a new removal. */
     catchUp?: true;
@@ -225,8 +237,14 @@ export interface EpochRequest {
  *  cannot prove which participant it speaks for in this room, or from one
  *  that cannot prove it was admitted to the room at all. */
 export declare function decodeEpochRequest(event: Event, opts: DecodeEpochRequestOptions): EpochRequest | null;
-/** Why the authority would not hand an epoch over. */
-export type EpochRefusal = 'removed' | 'closed';
+/** How often a desk reports the same unknown participant while they keep
+ *  asking: often enough that a missed "let them in?" comes back, rarely
+ *  enough that it is not a nag. */
+export declare const REPORT_UNKNOWN_EVERY_SECONDS = 60;
+/** Why the authority would not hand an epoch over. `unknown` is not final:
+ *  the room has removed somebody, and does not yet know this participant,
+ *  so it waits for a member to let them in (#207). */
+export type EpochRefusal = 'removed' | 'closed' | 'unknown';
 export interface EncodeEpochGrantOptions {
     roomId: string;
     authoritySk: Uint8Array;
@@ -236,6 +254,9 @@ export interface EncodeEpochGrantOptions {
     /** The current epoch. Omitted when refusing. */
     epoch?: RoomEpoch;
     removed?: string[];
+    /** The participants the authority knows, so the requester's own member
+     *  desk knows them too. Omitted, the body is as before. */
+    members?: string[];
     refused?: EpochRefusal;
     /** 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. */
@@ -261,6 +282,8 @@ export type EpochGrant = {
      *  the epochs it carried between the requester's and `epoch`. See
      *  `MemberEpochGrant.passed`. The authority's own answer has none. */
     passed?: RoomEpoch[];
+    /** The participants the room knows, when the answer carried them. */
+    members?: string[];
     refused?: undefined;
 } | {
     refused: EpochRefusal;
@@ -281,6 +304,24 @@ export interface HostRoomEpochOptions {
     removed: () => ReadonlySet<string>;
     /** True once the room has been closed: every request is refused. */
     closed?: () => boolean;
+    /**
+     * Whether the room knows this participant: on the authority's member
+     * list, in the room now, or let in. Consulted only once somebody has been
+     * removed, and then everybody else is answered `unknown` (#207). Without
+     * it, after a removal, nobody is known. Asked on every request.
+     */
+    known?: (participant: string) => boolean;
+    /** The participants to tell a granted device about, so its own member
+     *  desk knows them too. Asked on every grant. */
+    members?: () => readonly string[];
+    /** Somebody the room does not know asked, after a removal: what an app
+     *  turns into "let them in?". Called once per participant, and again
+     *  every `reportUnknownEvery` seconds while they keep asking. Letting them in
+     *  is making `known` say yes; the requester's next ask is then granted. */
+    onUnknown?: (request: EpochRequest) => void;
+    /** Seconds before a participant still unknown and still asking is
+     *  reported again. Default 60. */
+    reportUnknownEvery?: number;
     policy?: RoomPolicy;
     legacyParticipants?: ReadonlySet<string>;
     now?: () => number;
@@ -298,6 +339,13 @@ export interface HostRoomEpochOptions {
  * *secret*, which opens epoch 0 and nothing after it. A request with no
  * admission proof, or one made under some other key, is not answered at
  * all: a stranger learns nothing, not even that a desk is here.
+ *
+ * The admission proof is made under the epoch-0 room key, which a removed
+ * member still holds, so removal by participant alone is undone by a fresh
+ * key (#207). Once anyone has been removed the desk therefore grants only
+ * to participants the room knows (`known`), and answers anybody else
+ * `unknown` until a member lets them in. A room that has never removed
+ * anybody is answered exactly as before.
  */
 export declare function hostRoomEpoch(opts: HostRoomEpochOptions): {
     close(): void;
@@ -319,6 +367,9 @@ export interface RequestRoomEpochOptions {
     /** Ask the room's current members too (`memberEpochSource`): the first
      *  answer that checks out, the authority's or a member's, settles it. */
     members?: MemberEpochSource;
+    /** The authority said the room does not know this participant yet. Not
+     *  final: the ask goes on, and a member letting them in settles it. */
+    onUnknown?: () => void;
 }
 /** Thrown when the authority answered, and the answer was no. */
 export declare class EpochRefusedError extends Error {
@@ -327,7 +378,8 @@ export declare class EpochRefusedError extends Error {
 }
 /** Ask the authority where the room is, and wait for the answer. Rejects
  *  with `EpochRefusedError` on a refusal, and with a plain error when
- *  nobody answers inside the timeout. */
+ *  nobody answers inside the timeout. `unknown` is not final: the ask goes
+ *  on, and only a timeout after it rejects, with `EpochRefusedError`. */
 export declare function requestRoomEpoch(opts: RequestRoomEpochOptions): Promise<Exclude<EpochGrant, {
     refused: EpochRefusal;
 }>>;

package/dist/epoch.js

@@ -80,6 +80,14 @@ function require32(bytes, what) {
     if (bytes.length !== 32)
         throw new Error(`${what} must be 32 bytes`);
 }
+/** A participant list as a body carries it: lower-case, deduplicated and
+ *  sorted, or undefined when the field is absent or is not a list of keys.
+ *  Undefined is the safe reading, since it makes nobody known. */
+export function readMemberList(raw) {
+    if (!Array.isArray(raw) || !raw.every((p) => typeof p === 'string' && HEX64.test(p)))
+        return undefined;
+    return [...new Set(raw.map(normaliseHex))].sort();
+}
 function requireHex32(value, what) {
     if (!HEX64.test(value))
         throw new Error(`${what} must be 32-byte hex`);
@@ -119,6 +127,12 @@ export function deriveEpoch(epoch) {
         key: hkdf(sha256, epoch.secret, undefined, `${EPOCH_KEY_INFO}/${n}`, 32),
     };
 }
+function memberListOf(members, removed) {
+    const out = new Set(members.map((p) => requireHex32(p, 'member participant')));
+    for (const p of removed)
+        out.delete(normaliseHex(p));
+    return [...out].sort();
+}
 /** Announce the next epoch. See the module comment for what this is. */
 export function encodeRekeyEvent(opts) {
     require32(opts.authoritySk, 'authority secret key');
@@ -142,6 +156,7 @@ export function encodeRekeyEvent(opts) {
         ...(opts.by !== undefined ? { by: requireHex32(opts.by, 'admin') } : {}),
         ...(opts.closed ? { closed: true } : {}),
         ...(opts.commit ? { commit: epochCommitment(roomId, epoch, opts.next.secret) } : {}),
+        ...(opts.members !== undefined ? { members: memberListOf(opts.members, removed) } : {}),
         keys,
     };
     return finalizeEvent({
@@ -206,6 +221,9 @@ export function decodeRekeyEvent(event, opts) {
         };
         if (typeof body.by === 'string' && HEX64.test(body.by))
             notice.by = normaliseHex(body.by);
+        const members = readMemberList(body.members);
+        if (members)
+            notice.members = members;
         const device = getPublicKey(opts.deviceSk);
         const mine = Object.entries(body.keys).find(([to]) => hexEquals(to, device))?.[1];
         if (typeof mine === 'string') {
@@ -346,6 +364,10 @@ export function decodeEpochRequest(event, opts) {
         return null;
     }
 }
+/** How often a desk reports the same unknown participant while they keep
+ *  asking: often enough that a missed "let them in?" comes back, rarely
+ *  enough that it is not a nag. */
+export const REPORT_UNKNOWN_EVERY_SECONDS = 60;
 /** Answer one request: the current epoch sealed to the asking device, or a
  *  refusal it alone can read. */
 export function encodeEpochGrant(opts) {
@@ -366,6 +388,8 @@ export function encodeEpochGrant(opts) {
             body.secret = base64urlnopad.encode(opts.epoch.secret);
         }
         body.removed = [...new Set((opts.removed ?? []).map((p) => requireHex32(p, 'removed participant')))].sort();
+        if (opts.members !== undefined)
+            body.members = memberListOf(opts.members, body.removed);
     }
     return finalizeEvent({
         kind: KINDS.EPOCH_GRANT,
@@ -399,21 +423,23 @@ export function decodeEpochGrant(event, opts) {
         const body = JSON.parse(nip44.v2.decrypt(event.content, nip44.v2.utils.getConversationKey(opts.deviceSk, event.pubkey)));
         if (body.v !== 1 || typeof body.request !== 'string' || !hexEquals(body.request, opts.request))
             return null;
-        if (body.refused === 'removed' || body.refused === 'closed')
+        if (body.refused === 'removed' || body.refused === 'closed' || body.refused === 'unknown')
             return { refused: body.refused };
         if (!Number.isSafeInteger(body.epoch) || body.epoch < 0 || body.epoch > MAX_EPOCH)
             return null;
         const removed = Array.isArray(body.removed)
             ? [...new Set(body.removed.filter((p) => typeof p === 'string' && HEX64.test(p)).map(normaliseHex))].sort()
             : [];
+        const members = readMemberList(body.members);
+        const listed = members ? { members } : {};
         if (body.epoch === 0)
-            return { epoch: { epoch: 0 }, removed };
+            return { epoch: { epoch: 0 }, removed, ...listed };
         if (typeof body.secret !== 'string')
             return null;
         const secret = base64urlnopad.decode(body.secret);
         if (secret.length !== 32)
             return null;
-        return { epoch: { epoch: body.epoch, secret }, removed };
+        return { epoch: { epoch: body.epoch, secret }, removed, ...listed };
     }
     catch {
         return null;
@@ -428,6 +454,13 @@ export function decodeEpochGrant(event, opts) {
  * *secret*, which opens epoch 0 and nothing after it. A request with no
  * admission proof, or one made under some other key, is not answered at
  * all: a stranger learns nothing, not even that a desk is here.
+ *
+ * The admission proof is made under the epoch-0 room key, which a removed
+ * member still holds, so removal by participant alone is undone by a fresh
+ * key (#207). Once anyone has been removed the desk therefore grants only
+ * to participants the room knows (`known`), and answers anybody else
+ * `unknown` until a member lets them in. A room that has never removed
+ * anybody is answered exactly as before.
  */
 export function hostRoomEpoch(opts) {
     require32(opts.authoritySk, 'authority secret key');
@@ -436,6 +469,16 @@ export function hostRoomEpoch(opts) {
     const authority = getPublicKey(opts.authoritySk);
     const now = opts.now ?? (() => Math.floor(Date.now() / 1000));
     const answered = new Set();
+    /** Requests answered `unknown`, which the requester sends again while it
+     *  waits: answered again only once they are known. */
+    const waiting = new Set();
+    /** When each unknown participant was last reported through `onUnknown`,
+     *  so one still waiting is reported again only after `reportUnknownEvery`. */
+    const reported = new Map();
+    const bound = (set) => {
+        if (set.size > 256)
+            set.delete(set.values().next().value);
+    };
     let closed = false;
     const unsub = opts.transport.subscribe([{ kinds: [KINDS.EPOCH_REQUEST], '#d': [roomId], '#p': [authority] }], (event) => {
         if (closed)
@@ -450,14 +493,24 @@ export function hostRoomEpoch(opts) {
         });
         if (!request || answered.has(request.request))
             return;
-        answered.add(request.request);
-        if (answered.size > 256)
-            answered.delete(answered.values().next().value);
         let refused;
         if (opts.closed?.())
             refused = 'closed';
         else if (opts.removed().has(request.participant))
             refused = 'removed';
+        else if (opts.removed().size > 0 && !opts.known?.(request.participant))
+            refused = 'unknown';
+        if (refused === 'unknown') {
+            if (waiting.has(request.request))
+                return;
+            waiting.add(request.request);
+            bound(waiting);
+        }
+        else {
+            waiting.delete(request.request);
+            answered.add(request.request);
+            bound(answered);
+        }
         let grant;
         try {
             grant = refused
@@ -470,6 +523,7 @@ export function hostRoomEpoch(opts) {
                     now: now(),
                     epoch: opts.current(),
                     removed: [...opts.removed()],
+                    ...(opts.members ? { members: [...opts.members()] } : {}),
                     expiresAt: opts.expiresAt,
                 });
         }
@@ -477,6 +531,14 @@ export function hostRoomEpoch(opts) {
             return;
         }
         opts.transport.publish(grant).catch(() => { });
+        if (refused === 'unknown' && now() - (reported.get(request.participant) ?? -Infinity) >= (opts.reportUnknownEvery ?? REPORT_UNKNOWN_EVERY_SECONDS)) {
+            reported.set(request.participant, now());
+            if (reported.size > 256)
+                reported.delete(reported.keys().next().value);
+            opts.onUnknown?.(request);
+        }
+        if (!refused)
+            reported.delete(request.participant);
         if (refused)
             opts.onRefused?.(request, refused);
         else
@@ -495,14 +557,19 @@ export function hostRoomEpoch(opts) {
 export class EpochRefusedError extends Error {
     refused;
     constructor(refused) {
-        super(refused === 'removed' ? 'you were removed from this room' : 'this room has been closed');
+        super(refused === 'removed'
+            ? 'you were removed from this room'
+            : refused === 'unknown'
+                ? 'nobody in this room has let you in yet'
+                : 'this room has been closed');
         this.name = 'EpochRefusedError';
         this.refused = refused;
     }
 }
 /** Ask the authority where the room is, and wait for the answer. Rejects
  *  with `EpochRefusedError` on a refusal, and with a plain error when
- *  nobody answers inside the timeout. */
+ *  nobody answers inside the timeout. `unknown` is not final: the ask goes
+ *  on, and only a timeout after it rejects, with `EpochRefusedError`. */
 export function requestRoomEpoch(opts) {
     const now = opts.now ?? (() => Math.floor(Date.now() / 1000));
     const roomId = requireHex32(opts.roomId, 'room id');
@@ -523,6 +590,7 @@ export function requestRoomEpoch(opts) {
         let expiry;
         let unsub = () => { };
         let stopMembers = () => { };
+        let unknown = false;
         const finish = (settle) => {
             if (settled)
                 return;
@@ -539,7 +607,12 @@ export function requestRoomEpoch(opts) {
             const grant = decodeEpochGrant(event, { roomId, authority: opts.authority, deviceSk: opts.deviceSk, request: request.id, now: now() });
             if (!grant)
                 return;
-            if (grant.refused)
+            if (grant.refused === 'unknown') {
+                if (!unknown)
+                    opts.onUnknown?.();
+                unknown = true;
+            }
+            else if (grant.refused)
                 finish(() => reject(new EpochRefusedError(grant.refused)));
             else
                 finish(() => resolve(grant));
@@ -555,7 +628,7 @@ export function requestRoomEpoch(opts) {
             if (!settled)
                 opts.transport.publish(request).catch(() => { });
         };
-        expiry = setTimeout(() => finish(() => reject(new Error('the room has moved to a newer epoch and its keeper is not answering'))), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        expiry = setTimeout(() => finish(() => reject(unknown ? new EpochRefusedError('unknown') : new Error('the room has moved to a newer epoch and its keeper is not answering'))), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
         expiry.unref?.();
         retry = setInterval(ask, opts.retryMs ?? DEFAULT_RETRY_MS);
         retry.unref?.();

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } fr
 export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
 export type { RoomLink } from './link.js';
-export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
 export type { RoomEpoch, EpochKeys, EncodeRekeyOptions, RekeyNotice, PeekRekeyOptions, DecodeRekeyOptions, EpochRequestAdmissionOptions, EncodeEpochRequestOptions, DecodeEpochRequestOptions, EpochRequest, EpochRefusal, EncodeEpochGrantOptions, DecodeEpochGrantOptions, EpochGrant, HostRoomEpochOptions, RequestRoomEpochOptions, SignAdminsOptions, SignChannelsOptions, VerifyChannelsOptions, VerifyAdminsOptions, } from './epoch.js';
 export { EPOCH_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';

package/dist/index.js

@@ -16,7 +16,7 @@ export { encodePersistentInvitation, decodePersistentInvitation, requestPersiste
 export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } from './expiration.js';
 export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
-export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, 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

@@ -61,6 +61,8 @@ export interface RekeyEvidence {
     closed: boolean;
     /** The epoch commitment, when the authority wrote one. */
     commit?: string;
+    /** The authority's member list, when it wrote one. */
+    members?: string[];
 }
 /**
  * Read an authority-signed rekey with the key of the epoch it leaves,
@@ -161,6 +163,8 @@ export interface MemberEpochGrant {
      *  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[];
+    /** The newest member list in the chain, when any rekey in it had one. */
+    members?: string[];
 }
 /**
  * Verify a member's answer to one of this device's member requests. Null
@@ -190,6 +194,21 @@ export interface HostMemberEpochDeskOptions {
     removed: () => ReadonlySet<string>;
     /** True once the room has been closed. */
     closed?: () => boolean;
+    /**
+     * Whether the room knows this participant: on the authority's latest
+     * member list, in the room's current roster, or let in from this device.
+     * Consulted only once somebody has been removed; then nobody else is
+     * answered (#207). Without it, after a removal, nobody is known.
+     */
+    known?: (participant: string) => boolean;
+    /** Somebody the room does not know asked, after a removal. Called once
+     *  per participant, and again every `reportUnknownEvery` seconds while
+     *  they keep asking; nothing is published. Letting them in is making `known`
+     *  say yes, and their next ask is answered. */
+    onUnknown?: (request: MemberEpochRequest) => void;
+    /** Seconds before a participant still unknown and still asking is
+     *  reported again. Default 60 (`REPORT_UNKNOWN_EVERY_SECONDS`). */
+    reportUnknownEvery?: number;
     policy?: RoomPolicy;
     now?: () => number;
     /** Upper bound of the random wait before answering, so several members do
@@ -212,8 +231,10 @@ export interface HostMemberEpochDeskOptions {
  * 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.
+ * closed, from a participant the room knows once anybody has been removed
+ * (see `hostRoomEpoch` for why), 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.

package/dist/member-epoch.js

@@ -10,7 +10,7 @@ import { verifyEventUncached } from './verify.js';
 import { withExpiration } from './expiration.js';
 import { epochCommitment } from './epoch-commit.js';
 import { KINDS } from './kinds.js';
-import { MAX_EPOCH, deriveEpoch, epochRequestAdmission, peekRekeyEvent, } from './epoch.js';
+import { MAX_EPOCH, REPORT_UNKNOWN_EVERY_SECONDS, deriveEpoch, epochRequestAdmission, peekRekeyEvent, readMemberList, } from './epoch.js';
 /**
  * Member-to-member epoch catch-up: any current member can bring an
  * admitted, non-removed member up to date.
@@ -118,6 +118,9 @@ export function readRekeyEvidence(event, opts) {
         };
         if (typeof body.commit === 'string' && HEX64.test(body.commit))
             evidence.commit = normaliseHex(body.commit);
+        const members = readMemberList(body.members);
+        if (members)
+            evidence.members = members;
         return evidence;
     }
     catch {
@@ -279,6 +282,7 @@ export function decodeMemberEpochGrant(event, opts) {
         let previous = opts.current;
         let secret;
         const passed = [];
+        let members;
         for (let i = 0; i < length; i += 1) {
             const evidence = readRekeyEvidence(body.rekeys[i], { roomId, authority: opts.authority, previous });
             if (!evidence)
@@ -289,6 +293,8 @@ export function decodeMemberEpochGrant(event, opts) {
                 return null;
             for (const p of evidence.removed)
                 removed.add(p);
+            if (evidence.members)
+                members = evidence.members;
             const raw = body.secrets[i];
             if (typeof raw !== 'string')
                 return null;
@@ -308,7 +314,7 @@ export function decodeMemberEpochGrant(event, opts) {
             if (i < length - 1)
                 passed.push({ epoch: evidence.epoch, secret });
         }
-        return { epoch: { epoch: top, secret: secret }, removed: [...removed].sort(), passed };
+        return { epoch: { epoch: top, secret: secret }, removed: [...removed].sort(), passed, ...(members ? { members } : {}) };
     }
     catch {
         return null;
@@ -318,8 +324,10 @@ export function decodeMemberEpochGrant(event, opts) {
  * 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.
+ * closed, from a participant the room knows once anybody has been removed
+ * (see `hostRoomEpoch` for why), 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.
@@ -344,6 +352,10 @@ export function hostMemberEpochDesk(opts) {
     const grantSeen = new Set();
     /** Requesting devices this desk has already stood down for once. */
     const stoodDown = new Set();
+    /** When each unknown participant was last reported. A requester asks
+     *  afresh every `retryMs` while it waits, so this is by participant, not
+     *  by request: one "let them in?" a `reportUnknownEvery`, not one a retry. */
+    const reported = new Map();
     /** Ids of the grants this desk published: each is signed by a one-time
      *  key, so its own grants are told apart by id, not by signer. */
     const mine = new Set();
@@ -386,6 +398,12 @@ export function hostMemberEpochDesk(opts) {
         }
         return { epochs, rekeys };
     };
+    const admissible = (request) => {
+        const removed = opts.removed();
+        if ([...removed].some((p) => hexEquals(p, request.participant)))
+            return false;
+        return removed.size === 0 || opts.known?.(request.participant) === true;
+    };
     const answer = (request) => {
         if (closed)
             return;
@@ -398,7 +416,7 @@ export function hostMemberEpochDesk(opts) {
         // Asked again, now that the wait is over: the room may have moved.
         if (opts.closed?.())
             return;
-        if ([...opts.removed()].some((p) => hexEquals(p, request.participant)))
+        if (!admissible(request))
             return;
         const current = opts.current();
         if (!current || request.have >= current.epoch)
@@ -443,16 +461,32 @@ export function hostMemberEpochDesk(opts) {
         const request = decodeMemberEpochRequest(event, { roomId, authority, roomKey: opts.roomKey, now: now(), policy: opts.policy });
         if (!request || answered.has(request.request))
             return;
-        answered.add(request.request);
-        bound(answered);
         if (opts.closed?.()) {
+            answered.add(request.request);
+            bound(answered);
             opts.onRefused?.(request, 'closed');
             return;
         }
         if ([...opts.removed()].some((p) => hexEquals(p, request.participant))) {
+            answered.add(request.request);
+            bound(answered);
             opts.onRefused?.(request, 'removed');
             return;
         }
+        if (!admissible(request)) {
+            const last = reported.get(request.participant);
+            if (last !== undefined && now() - last < (opts.reportUnknownEvery ?? REPORT_UNKNOWN_EVERY_SECONDS))
+                return;
+            reported.set(request.participant, now());
+            if (reported.size > 256)
+                reported.delete(reported.keys().next().value);
+            opts.onUnknown?.(request);
+            opts.onRefused?.(request, 'unknown');
+            return;
+        }
+        reported.delete(request.participant);
+        answered.add(request.request);
+        bound(answered);
         const current = opts.current();
         if (!current || request.have >= current.epoch)
             return;

package/llms.txt

@@ -80,6 +80,7 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `epochRequestAdmission(opts)`, `deriveEpochRequestKey(roomKey)`
 - `hostRoomEpoch(opts)` / `requestRoomEpoch(opts)` / `EpochRefusedError` - the live request/grant desk, both sides
 - 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
 - `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.5.1",
+  "version": "0.6.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",

package/vectors/member-epoch-vectors.json

@@ -136,6 +136,70 @@
           }
         }
       },
+      {
+        "name": "rekey-with-members",
+        "kind": "positive",
+        "note": "The rekey to epoch 2 with the authority's member list (`encodeRekeyEvent({ members })`, #207): the participants it knows to be in the room, the removed ones dropped even when passed in, lower-case, deduplicated and sorted. Body key order: v, epoch, removed, commit, members, keys. A desk hands an epoch on, once anybody has been removed, only to a participant the room knows; this list is where a member learns who that is. A list that is not an array of 32-byte hex keys is read as absent, which makes nobody known.",
+        "input": {
+          "roomId": "76c7081ef2322b7619d5cb5e690779fb942d63964f0b819e3d852db6c6a264f9",
+          "authority": "a5098de007349f8c12d6a854dfc069074b803470f59484697c50c5211b13c810",
+          "previousEpoch": 1,
+          "previousSecretHex": "cf6c5602daa51ecab29fbcbcef0da517b303cd59ee2904c15e226b7dd00e7752",
+          "previousKeyHex": "e038a7fca65628eebee35c562410ac63cce191b776ba0e8e5a1d241d9417f733",
+          "next": {
+            "epoch": 2,
+            "secretHex": "d4f5a0426e6880797fa29d914bb6977d193dfcd4f46b2a3acc576226eeec3ac9"
+          },
+          "recipients": [
+            "ef4396c842882c47ad1106d846d5c7e712c8928b69c92bc1798fa63deb9dd76b"
+          ],
+          "removed": [
+            "298cf780bc6d1b93c4900b20c89a911286ee3488ab94f543d96d567c70eb9ed2"
+          ],
+          "members": [
+            "588c59130ea8b9d81e836d0c5a89daa6b888923357c1415359b48595b4937f53",
+            "298cf780bc6d1b93c4900b20c89a911286ee3488ab94f543d96d567c70eb9ed2"
+          ],
+          "authoritySkHex": "825cf62829b0262bc5b46870d5cc054d6049e54a68cf1ea393c3da56226c456b",
+          "createdAt": 1799999002,
+          "event": {
+            "id": "d8d5c810c2e22d87493d8a10f908e38e68b5e4611ad5a230103ca01d5ba7a954",
+            "pubkey": "a5098de007349f8c12d6a854dfc069074b803470f59484697c50c5211b13c810",
+            "created_at": 1799999002,
+            "kind": 1462,
+            "tags": [
+              [
+                "d",
+                "76c7081ef2322b7619d5cb5e690779fb942d63964f0b819e3d852db6c6a264f9"
+              ],
+              [
+                "epoch",
+                "2"
+              ]
+            ],
+            "content": "AjCp1V9xfa32TYx5FAmMp1toqAM2yKrdBWdygJs+bFNGNIls48ZUufb0m3Cs51qusvmVJF51AEvXiW82LyhO6o/2J9Sra65b80+cyj8Km+LrLCXx6qyLPIYjKdISORDS6UhDKXa9UInbnZnGf87KKruDujB82QKDo26ImrXPbzy246dYMCvon7dYLGa+y3Qk9u5OLVKSrYVhDhFRHZX2XMltl478SRQ7GuvzbibZbFrNz1EvWSJOqbxf8YLpvYzbq55xmr9CA1rjk9vBKTzaHGX23ZvPPdaQFHh53YXCzYGN4+p54P/gH9PgZREZt+5Jel5kDhVfk8YMinaSzaBQ7MvEUEEIGDUPc6xbmZ3twlam+y/4H0vuugQtOm85tU7sozohPj65hlpaxRmTdenWivldIAWyPAEsUjOtGcvnFur5Hbg9H+WEsyXAX6tLZZV3jNFcCPLkoWB9O3iFasN3m2P0larhRTr9lhReqzt3UxtGBp14rErj0uZEZlwrz4n3ZiFgH/qc1X/pFlskh4dQJV/PGCEe6F7v7fd4aChiYHA1ghq2cy4fKW44+FU2EKPEezWcD96sOshiCoh0xWxHJoNbWhKJ5P8EcyK7TCH9UJVk9OyAiGVYnnxh+cuDgVfCOdRR6VbxWopqclvhlV+NGBullxSv5aQJSj6fS5O+QxSCwZrR8DA2SMKRSFU+kXHQxOgEvZW1cPdHWMtUr1dwsRrMd3ayNyZqSIjjyktqzsmrD+Pl6Ikk5tbE3kyNYdWHX7Mz",
+            "sig": "90c5666a5ca4c5d4c1a0e4b3b4422aa7462d4300986f82afff435a88edb48a41e3191192c6404b17401712204de56ba2269a6b4376f0ef224ad9798728550710"
+          },
+          "randomHex": [
+            "ff9c267263a44961a1d49a09c831ef35fa2d53e4d4cfc572d72f506478e61045",
+            "30a9d55f717dadf64d8c7914098ca75b68a80336c8aadd056772809b3e6c5346",
+            "11ae6ba1ae1e25f1493588462e919538089a63c28e68b7f5734bd0df2ba395e3"
+          ]
+        },
+        "output": {
+          "evidence": {
+            "epoch": 2,
+            "removed": [
+              "298cf780bc6d1b93c4900b20c89a911286ee3488ab94f543d96d567c70eb9ed2"
+            ],
+            "closed": false,
+            "commit": "3472885df839fc5d48d809476e28e36c458c3e4717e35c2ec0d69bbbdf94f896",
+            "members": [
+              "588c59130ea8b9d81e836d0c5a89daa6b888923357c1415359b48595b4937f53"
+            ]
+          }
+        }
+      },
       {
         "name": "member-request",
         "kind": "positive",