@forgesworn/fold-kit 0.9.0 → 0.12.0

package/dist/persistent-invitation-evidence.js

@@ -0,0 +1,381 @@
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha2';
+import { base64urlnopad } from '@scure/base';
+import { nip44 } from 'nostr-tools';
+import { verifiedSymbol } from 'nostr-tools/pure';
+import { deriveInvitationId, roomInvitation, decodeInvitationRetirementNotice } from './invitation.js';
+import { PERSISTENT_INVITATION_LABELS } from './persistent-invitation.js';
+import { isRoomEnds } from './expiration.js';
+import { isInvitationRelays } from './invitation-relays.js';
+import { deriveRoom } from './room.js';
+import { KINDS } from './kinds.js';
+import { verifyEventUncached } from './verify.js';
+export const MAX_PERSISTENT_INVITATION_EVIDENCE_EVENTS = 64;
+export const MAX_PERSISTENT_INVITATION_EVENT_BYTES = 16_384;
+export const MAX_PERSISTENT_INVITATION_EVIDENCE_BYTES = 262_144;
+/** Incomplete observations are bounded diagnostic custody only. They are
+ * never accepted by revalidatePersistentInvitationEvidence. */
+export class PersistentInvitationEvidenceQueryError extends Error {
+    observation;
+    constructor(message, observation) {
+        super(message);
+        this.name = 'PersistentInvitationEvidenceQueryError';
+        this.observation = observation;
+    }
+}
+const fields = ['id', 'pubkey', 'created_at', 'kind', 'tags', 'content', 'sig'];
+const utf8 = new TextEncoder();
+const hex32 = /^[0-9a-f]{64}$/;
+const hex64 = /^[0-9a-f]{128}$/;
+/** JSON string byte cost including escaping, without serialising content. */
+function jsonStringBytes(value) {
+    let bytes = 2;
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        if (c === 34 || c === 92)
+            bytes += 2;
+        else if (c < 32)
+            bytes += [8, 9, 10, 12, 13].includes(c) ? 2 : 6;
+        else if (c < 128)
+            bytes++;
+        else if (c < 2048)
+            bytes += 2;
+        else if (c >= 0xd800 && c <= 0xdbff && value.charCodeAt(i + 1) >= 0xdc00 && value.charCodeAt(i + 1) <= 0xdfff) {
+            bytes += 4;
+            i++;
+        }
+        else if (c >= 0xd800 && c <= 0xdfff)
+            bytes += 6;
+        else
+            bytes += 3;
+        if (bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+            throw new Error('oversized evidence event');
+    }
+    return bytes;
+}
+function dataRecord(raw, allowed, ignoredSymbol) {
+    if (!raw || typeof raw !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(raw)))
+        throw new Error('invalid evidence record');
+    const descriptors = Object.getOwnPropertyDescriptors(raw);
+    for (const key of Reflect.ownKeys(descriptors)) {
+        if ((typeof key === 'symbol' ? key !== ignoredSymbol : !allowed.includes(key)) || !('value' in descriptors[key]))
+            throw new Error('invalid evidence field');
+    }
+    const result = Object.create(null);
+    for (const key of allowed)
+        if (descriptors[key])
+            result[key] = descriptors[key].value;
+    return result;
+}
+function dataArray(raw, limit) {
+    if (!Array.isArray(raw) || Object.getPrototypeOf(raw) !== Array.prototype || raw.length > limit)
+        throw new Error('invalid evidence array');
+    const descriptors = Object.getOwnPropertyDescriptors(raw);
+    if (Reflect.ownKeys(descriptors).length !== raw.length + 1)
+        throw new Error('invalid evidence array fields');
+    const values = [];
+    for (let i = 0; i < raw.length; i++) {
+        if (!descriptors[i] || !('value' in descriptors[i]))
+            throw new Error('invalid evidence array item');
+        values.push(descriptors[i].value);
+    }
+    return values;
+}
+/** Fresh carrier copy, with no trusted verification-cache symbol. Bounds
+ * precede copying or serialising potentially large strings/tag arrays. */
+function carrier(raw) {
+    const d = dataRecord(raw, fields, verifiedSymbol);
+    if (Object.keys(d).length !== fields.length || typeof d.id !== 'string' || !hex32.test(d.id) ||
+        typeof d.pubkey !== 'string' || !hex32.test(d.pubkey) || typeof d.sig !== 'string' || !hex64.test(d.sig) ||
+        !Number.isSafeInteger(d.created_at) || d.created_at < 0 || !Number.isSafeInteger(d.kind) || d.kind < 0 ||
+        typeof d.content !== 'string' || d.content.length > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+        throw new Error('invalid or oversized evidence event');
+    let bytes = '{"id":,"pubkey":,"created_at":,"kind":,"tags":,"content":,"sig":}'.length +
+        String(d.created_at).length + String(d.kind).length + jsonStringBytes(d.id) + jsonStringBytes(d.pubkey) + jsonStringBytes(d.sig) + jsonStringBytes(d.content);
+    if (bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+        throw new Error('oversized evidence event');
+    const outer = dataArray(d.tags, 64);
+    bytes += 2 + Math.max(0, outer.length - 1);
+    const tags = outer.map(tag => {
+        const inner = dataArray(tag, 8);
+        bytes += 2 + Math.max(0, inner.length - 1);
+        return inner.map(value => {
+            if (typeof value !== 'string' || value.length > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+                throw new Error('invalid or oversized evidence tag');
+            bytes += jsonStringBytes(value);
+            if (bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+                throw new Error('oversized evidence event');
+            return value;
+        });
+    });
+    if (bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+        throw new Error('oversized evidence event');
+    const event = { id: d.id, pubkey: d.pubkey, created_at: d.created_at, kind: d.kind, tags, content: d.content, sig: d.sig };
+    const canonical = JSON.stringify(event);
+    return { event, canonical, bytes };
+}
+function copyInvitation(invitation) {
+    if (!invitation.persistent || !(invitation.bearer instanceof Uint8Array) || invitation.bearer.length !== 32 || !hex32.test(invitation.inviter))
+        throw new Error('a canonical persistent invitation is required');
+    return roomInvitation(invitation.bearer.slice(), invitation.inviter, true);
+}
+function roomId(secret) {
+    const room = deriveRoom(secret);
+    room.roomKey.fill(0);
+    return room.roomId;
+}
+function signedScope(event, invitation) {
+    return event.pubkey === invitation.inviter && (event.kind === KINDS.GROUP_INVITATION || event.kind === KINDS.INVITATION_RETIREMENT) &&
+        event.tags.filter(tag => tag[0] === 'd').length === 1 && event.tags.find(tag => tag[0] === 'd')?.length === 2 &&
+        event.tags.find(tag => tag[0] === 'd')?.[1] === deriveInvitationId(invitation) && verifyEventUncached(event);
+}
+/** Strict evidence path accepts exactly the bodies/tags of supported writers;
+ * permissive legacy decoding and its public request remain unchanged. */
+function decodeEvidenceEvent(event, invitation) {
+    if (!signedScope(event, invitation))
+        return null;
+    if (event.kind === KINDS.INVITATION_RETIREMENT) {
+        const notice = decodeInvitationRetirementNotice(event, invitation);
+        return notice ? 'retired' : null;
+    }
+    let accepted = false, secret;
+    const key = hkdf(sha256, invitation.bearer, undefined, PERSISTENT_INVITATION_LABELS[0], 32);
+    try {
+        const plaintext = nip44.v2.decrypt(event.content, key);
+        const body = dataRecord(JSON.parse(plaintext), ['v', 'room', 'secret', 'ends', 'destruct', 'relays']);
+        if (body.v !== 3 || typeof body.secret !== 'string' || (body.ends !== undefined && !isRoomEnds(body.ends)) ||
+            (body.destruct !== undefined && body.destruct !== true) || (body.relays !== undefined && !isInvitationRelays(body.relays)))
+            return null;
+        secret = base64urlnopad.decode(body.secret);
+        if (secret.length !== 32 || body.room !== roomId(secret))
+            return null;
+        const decoded = { secret, persistent: true, epoch: 0,
+            ...(body.ends === undefined ? {} : { endsAt: body.ends }), ...(body.destruct ? { destruct: true } : {}),
+            ...(body.relays === undefined ? {} : { relays: [...body.relays] }) };
+        const expected = JSON.stringify({ v: 3, room: body.room, secret: base64urlnopad.encode(secret),
+            ...(decoded.endsAt === undefined ? {} : { ends: decoded.endsAt }), ...(decoded.destruct ? { destruct: true } : {}),
+            ...(decoded.relays === undefined ? {} : { relays: decoded.relays }) });
+        const tags = decoded.endsAt === undefined ? [['d', deriveInvitationId(invitation)]] : [['d', deriveInvitationId(invitation)], ['expiration', String(decoded.endsAt)]];
+        accepted = plaintext === expected && JSON.stringify(event.tags) === JSON.stringify(tags);
+        return accepted ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        key.fill(0);
+        if (!accepted)
+            secret?.fill(0);
+    }
+}
+/** Validate an actual encoder Event or its exact retained canonical carrier.
+ * A room-root pin is mandatory. No signing, query, storage or publication is
+ * performed. In particular, this cannot manufacture one-event EOSE evidence. */
+export function revalidatePersistentInvitationSource(opts) {
+    const invitation = copyInvitation(opts.invitation);
+    let root, admission;
+    let transferred = false;
+    try {
+        const expected = opts.expectedRoomSecret;
+        if (!(expected instanceof Uint8Array) || expected.length !== 32)
+            throw new Error('invalid expected room root');
+        root = expected.slice();
+        const raw = opts.event;
+        let c;
+        if (typeof raw === 'string') {
+            if (raw.length > MAX_PERSISTENT_INVITATION_EVENT_BYTES || utf8.encode(raw).length > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+                throw new Error('oversized invitation source carrier');
+            c = carrier(JSON.parse(raw));
+            if (c.canonical !== raw)
+                throw new Error('noncanonical invitation source carrier');
+        }
+        else
+            c = carrier(raw);
+        if (c.event.kind !== KINDS.GROUP_INVITATION)
+            throw new Error('a group invitation source is required');
+        const decoded = decodeEvidenceEvent(c.event, invitation);
+        if (!decoded || decoded === 'retired')
+            throw new Error('invalid signed invitation source');
+        admission = decoded;
+        if (!admission.secret.every((byte, i) => byte === root[i]))
+            throw new Error('wrong invitation source room root');
+        const result = Object.freeze({ version: 1,
+            invitationId: deriveInvitationId(invitation), inviter: invitation.inviter,
+            eventId: c.event.id, createdAt: c.event.created_at, event: c.canonical, admission });
+        transferred = true;
+        return result;
+    }
+    finally {
+        if (!transferred)
+            admission?.secret.fill(0);
+        root?.fill(0);
+        invitation.bearer.fill(0);
+    }
+}
+function observation(invitation, events, completion) {
+    const ids = [...events.keys()].sort();
+    return Object.freeze({ version: 1, invitationId: deriveInvitationId(invitation), inviter: invitation.inviter, completion,
+        eventIds: Object.freeze(ids), events: Object.freeze(ids.map(id => events.get(id))) });
+}
+/** Reverify all carriers and reproduce selection from protected evidence.
+ * Optional expectedRoomSecret binds an existing physical room to its exact
+ * root, not merely the invitation's current or historical room label. */
+export function revalidatePersistentInvitationEvidence(opts) {
+    const invitation = copyInvitation(opts.invitation);
+    const decoded = [];
+    try {
+        if (opts.expectedRoomSecret !== undefined && (!(opts.expectedRoomSecret instanceof Uint8Array) || opts.expectedRoomSecret.length !== 32))
+            throw new Error('invalid expected room root');
+        const d = dataRecord(opts.evidence, ['version', 'invitationId', 'inviter', 'completion', 'eventIds', 'events']);
+        if (d.version !== 1 || d.invitationId !== deriveInvitationId(invitation) || d.inviter !== invitation.inviter || d.completion !== 'eose')
+            throw new Error('invalid invitation evidence binding or completion');
+        const ids = dataArray(d.eventIds, MAX_PERSISTENT_INVITATION_EVIDENCE_EVENTS);
+        const raw = dataArray(d.events, MAX_PERSISTENT_INVITATION_EVIDENCE_EVENTS);
+        if (ids.length !== raw.length)
+            throw new Error('invalid invitation evidence identities');
+        const retained = new Map(), retired = [];
+        let bytes = 0;
+        for (let i = 0; i < raw.length; i++) {
+            const text = raw[i];
+            if (typeof text !== 'string' || text.length > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+                throw new Error('invalid evidence carrier');
+            const carrierBytes = utf8.encode(text).length;
+            if (carrierBytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+                throw new Error('oversized evidence carrier');
+            bytes += carrierBytes;
+            if (bytes > MAX_PERSISTENT_INVITATION_EVIDENCE_BYTES)
+                throw new Error('invitation evidence capacity exceeded');
+            const c = carrier(JSON.parse(text));
+            if (c.canonical !== text || c.event.id !== ids[i] || (i > 0 && ids[i - 1] >= c.event.id))
+                throw new Error('noncanonical invitation evidence');
+            const admission = decodeEvidenceEvent(c.event, invitation);
+            if (!admission)
+                throw new Error('invalid signed invitation evidence');
+            retained.set(c.event.id, text);
+            if (admission === 'retired')
+                retired.push(c.event.id);
+            else
+                decoded.push({ event: c.event, admission });
+        }
+        const evidence = observation(invitation, retained, 'eose');
+        const held = (reason) => Object.freeze({ evidence, outcome: Object.freeze({ status: 'held', reason, retirementEventIds: Object.freeze(retired) }) });
+        if (retired.length)
+            return held('retired');
+        if (!decoded.length)
+            return held('unavailable');
+        const first = decoded[0].admission.secret;
+        if (decoded.some(d => !d.admission.secret.every((b, i) => b === first[i])))
+            return held('conflicting-rooms');
+        if (opts.expectedRoomSecret !== undefined && !first.every((b, i) => b === opts.expectedRoomSecret[i]))
+            return held('wrong-room');
+        const ends = decoded.filter(d => d.admission.endsAt !== undefined);
+        const endsAt = ends.length ? Math.min(...ends.map(d => d.admission.endsAt)) : undefined;
+        const destruct = decoded.filter(d => d.admission.destruct);
+        const relayEvents = decoded.filter(d => d.admission.relays !== undefined);
+        const newest = relayEvents.length ? Math.max(...relayEvents.map(d => d.event.created_at)) : undefined;
+        const winners = relayEvents.filter(d => d.event.created_at === newest);
+        if (new Set(winners.map(d => JSON.stringify(d.admission.relays))).size > 1)
+            return held('conflicting-relays');
+        const relays = winners[0]?.admission.relays;
+        const admission = { secret: first.slice(), persistent: true, epoch: 0,
+            ...(endsAt === undefined ? {} : { endsAt }), ...(destruct.length ? { destruct: true } : {}),
+            ...(relays === undefined ? {} : { relays: [...relays] }) };
+        const contributors = Object.freeze({ room: Object.freeze(decoded.map(d => d.event.id)),
+            ends: Object.freeze(ends.filter(d => d.admission.endsAt === endsAt).map(d => d.event.id)),
+            destruct: Object.freeze(destruct.map(d => d.event.id)), relays: Object.freeze(winners.map(d => d.event.id)) });
+        return Object.freeze({ evidence, outcome: Object.freeze({ status: 'admitted', admission, contributors }) });
+    }
+    finally {
+        for (const d of decoded)
+            d.admission.secret.fill(0);
+        invitation.bearer.fill(0);
+    }
+}
+/** Additive evidence query. No publication, storage, relay defaults or
+ * membership authority. Only a complete bounded query can yield a result. */
+export async function requestPersistentRoomAdmissionEvidence(opts) {
+    const invitation = copyInvitation(opts.invitation);
+    const timeout = opts.timeoutMs ?? 15_000;
+    if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 2_147_483_647) {
+        invitation.bearer.fill(0);
+        throw new Error('invalid invitation evidence timeout');
+    }
+    try {
+        return await new Promise((resolve, reject) => {
+            const events = new Map();
+            let bytes = 0, received = 0, settled = false, unsub = () => { };
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                opts.signal?.removeEventListener('abort', abort);
+                try {
+                    unsub();
+                }
+                catch { /* Observer cleanup cannot revive a query. */ }
+                if (error)
+                    reject(new PersistentInvitationEvidenceQueryError(error instanceof Error ? error.message : String(error), observation(invitation, events, 'incomplete')));
+                else {
+                    try {
+                        resolve(revalidatePersistentInvitationEvidence({ evidence: observation(invitation, events, 'eose'), invitation }));
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                }
+            };
+            const abort = () => finish(new Error('invitation evidence query cancelled'));
+            const timer = setTimeout(() => finish(new Error('invitation evidence query did not complete')), timeout);
+            opts.signal?.addEventListener('abort', abort, { once: true });
+            if (opts.signal?.aborted) {
+                abort();
+                return;
+            }
+            try {
+                unsub = opts.transport.subscribe([{ kinds: [KINDS.GROUP_INVITATION, KINDS.INVITATION_RETIREMENT], authors: [invitation.inviter], '#d': [deriveInvitationId(invitation)] }], event => {
+                    if (settled)
+                        return;
+                    try {
+                        // Charge invalid candidates and duplicates before carrier/crypto.
+                        if (received >= MAX_PERSISTENT_INVITATION_EVIDENCE_EVENTS)
+                            throw new Error('invitation evidence query capacity exceeded');
+                        received++;
+                        const c = carrier(event);
+                        if (bytes + c.bytes > MAX_PERSISTENT_INVITATION_EVIDENCE_BYTES)
+                            throw new Error('invitation evidence query capacity exceeded');
+                        bytes += c.bytes;
+                        const prior = events.get(c.event.id);
+                        if (prior !== undefined) {
+                            if (prior !== c.canonical)
+                                throw new Error('conflicting duplicate invitation event identity');
+                            return;
+                        }
+                        const decoded = decodeEvidenceEvent(c.event, invitation);
+                        if (!decoded)
+                            return;
+                        if (decoded !== 'retired')
+                            decoded.secret.fill(0);
+                        events.set(c.event.id, c.canonical);
+                    }
+                    catch (error) {
+                        finish(error);
+                    }
+                }, () => finish());
+                // A synchronous transport can finish before returning its handle.
+                if (settled) {
+                    try {
+                        unsub();
+                    }
+                    catch { /* Already terminal. */ }
+                }
+            }
+            catch (error) {
+                finish(error);
+            }
+        });
+    }
+    finally {
+        invitation.bearer.fill(0);
+    }
+}

package/dist/quiet-reply.d.ts

@@ -0,0 +1,45 @@
+/** A wait range in milliseconds: `[min, max]`, drawn uniformly. */
+export type ReplyDelayRange = readonly [min: number, max: number];
+/** Run `fn` after `ms` milliseconds; the returned function cancels it. For
+ *  tests, so a desk's wait is driven without real time passing. */
+export type ReplySchedule = (fn: () => void, ms: number) => () => void;
+/** The wait before an automatic reply, unless the caller says otherwise. */
+export declare const DEFAULT_REPLY_DELAY_MS: ReplyDelayRange;
+/** How long the authority desk waits before refusing the same participant
+ *  again: a removed member asking with fresh requests learns nothing new
+ *  from a second refusal inside it. */
+export declare const REFUSE_AGAIN_AFTER_SECONDS = 3600;
+/** At most this many refusals a minute from one authority desk, whoever
+ *  asks: a participant key is anyone's to mint, so a limit per participant
+ *  alone does not stop a room-key holder asking as somebody new each time. */
+export declare const MAX_REFUSALS_PER_MINUTE = 20;
+/** How many participants a refusal limiter remembers. The oldest is
+ *  forgotten first; the per-minute budget still holds after that. */
+export declare const REFUSAL_LIMITER_CAPACITY = 256;
+/** `setTimeout`, unreferenced so a pending reply never holds a process open. */
+export declare const defaultReplySchedule: ReplySchedule;
+/** A wait drawn from `range`: whole milliseconds, never negative. A range
+ *  that is not two finite numbers is read as no wait; one given backwards
+ *  is put the right way round. */
+export declare function replyDelay(range: ReplyDelayRange, random?: () => number): number;
+export interface RefusalLimiterOptions {
+    /** Refusals allowed in any 60 seconds, across every key. Default
+     *  `MAX_REFUSALS_PER_MINUTE`. */
+    perMinute?: number;
+    /** Keys remembered. Default `REFUSAL_LIMITER_CAPACITY`. */
+    capacity?: number;
+}
+/** Decides whether a refusal goes on the wire: once per key per `every`
+ *  seconds, and no more than `perMinute` in any minute overall. Memory is
+ *  bounded by `capacity` keys plus `perMinute` timestamps. */
+export declare class RefusalLimiter {
+    #private;
+    constructor(opts?: RefusalLimiterOptions);
+    /** Keys remembered now. */
+    get size(): number;
+    /** True, and recorded, when a refusal to `key` may be sent at `now`
+     *  (unix seconds); false leaves nothing recorded. */
+    allow(key: string, every: number, now: number): boolean;
+    /** Forget `key`, as when the participant is granted. */
+    forget(key: string): void;
+}

package/dist/quiet-reply.js

@@ -0,0 +1,82 @@
+// Quiet automatic replies: the wait before a desk answers, and the limit on
+// how often it refuses. New in this kit, not moved from KithMoot (see
+// EXTRACTION.md "Quiet automatic replies").
+//
+// A desk that answers the instant a request lands, under a key that stays
+// the same, tells anyone who can make it answer when the device holding
+// that key is online and how quickly it is running ("Careless Whisper"
+// style timing). Nothing here changes what a reply says: only whether one
+// is sent, and when.
+/** The wait before an automatic reply, unless the caller says otherwise. */
+export const DEFAULT_REPLY_DELAY_MS = [500, 2000];
+/** How long the authority desk waits before refusing the same participant
+ *  again: a removed member asking with fresh requests learns nothing new
+ *  from a second refusal inside it. */
+export const REFUSE_AGAIN_AFTER_SECONDS = 3600;
+/** At most this many refusals a minute from one authority desk, whoever
+ *  asks: a participant key is anyone's to mint, so a limit per participant
+ *  alone does not stop a room-key holder asking as somebody new each time. */
+export const MAX_REFUSALS_PER_MINUTE = 20;
+/** How many participants a refusal limiter remembers. The oldest is
+ *  forgotten first; the per-minute budget still holds after that. */
+export const REFUSAL_LIMITER_CAPACITY = 256;
+/** `setTimeout`, unreferenced so a pending reply never holds a process open. */
+export const defaultReplySchedule = (fn, ms) => {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+};
+/** A wait drawn from `range`: whole milliseconds, never negative. A range
+ *  that is not two finite numbers is read as no wait; one given backwards
+ *  is put the right way round. */
+export function replyDelay(range, random = Math.random) {
+    const [a, b] = range;
+    if (!Number.isFinite(a) || !Number.isFinite(b))
+        return 0;
+    const min = Math.max(0, Math.min(a, b));
+    const max = Math.max(0, a, b);
+    if (max <= min)
+        return Math.floor(min);
+    const r = random();
+    const unit = Number.isFinite(r) ? Math.min(Math.max(r, 0), 1) : 0;
+    return Math.floor(min + unit * (max - min));
+}
+/** Decides whether a refusal goes on the wire: once per key per `every`
+ *  seconds, and no more than `perMinute` in any minute overall. Memory is
+ *  bounded by `capacity` keys plus `perMinute` timestamps. */
+export class RefusalLimiter {
+    #last = new Map();
+    #sent = [];
+    #perMinute;
+    #capacity;
+    constructor(opts = {}) {
+        this.#perMinute = Math.max(0, Math.floor(opts.perMinute ?? MAX_REFUSALS_PER_MINUTE));
+        this.#capacity = Math.max(1, Math.floor(opts.capacity ?? REFUSAL_LIMITER_CAPACITY));
+    }
+    /** Keys remembered now. */
+    get size() {
+        return this.#last.size;
+    }
+    /** True, and recorded, when a refusal to `key` may be sent at `now`
+     *  (unix seconds); false leaves nothing recorded. */
+    allow(key, every, now) {
+        const last = this.#last.get(key);
+        if (last !== undefined && now - last < every)
+            return false;
+        while (this.#sent.length > 0 && now - this.#sent[0] >= 60)
+            this.#sent.shift();
+        if (this.#sent.length >= this.#perMinute)
+            return false;
+        this.#sent.push(now);
+        // Re-inserted so the map's order is oldest-refused first.
+        this.#last.delete(key);
+        this.#last.set(key, now);
+        if (this.#last.size > this.#capacity)
+            this.#last.delete(this.#last.keys().next().value);
+        return true;
+    }
+    /** Forget `key`, as when the participant is granted. */
+    forget(key) {
+        this.#last.delete(key);
+    }
+}

package/docs/extraction-plan-excerpt.md

@@ -0,0 +1,56 @@
+# Extraction plan excerpt
+
+This kit was extracted from KithMoot under a private planning document that
+also covers work outside this repository's scope (a downstream app that
+consumes this kit, not itself part of the public KithMoot/fold-kit
+ecosystem). This file carries the parts of that plan needed to understand
+decisions recorded in this repository's own docs (EXTRACTION.md, AGENTS.md,
+source comments), without naming or linking the private document itself.
+
+## Module list and splits (plan §1.1)
+
+Moves to the kit, byte-identical bodies, only import paths changed: `hex`,
+`verify`, `identity`, `kinds` (subset), `types` (subset), `credential`,
+`room`, `network-hints`, `display-name`, `access` (split), `invitation`,
+`persistent-invitation`, `link`, `epoch`, `channel` (one function extracted
+from `chat.ts`), `lane`. A `relay` subpath (relay pool, relay auth,
+anonymous routing) is a separate, later move once its churn settles.
+
+`access.ts` split: `issueKindredProof`, `evaluateAccess` and the kindred
+message move; `evaluateAgentAccess` stays with the app, since it needs
+`ownership.ts` and a roster type that did not move.
+
+`chat.ts` split: `deriveChannel` only moves (into the kit's own
+`channel.ts`); `ChatLog` and the chat event codecs stay with the app.
+
+## Decisions relevant to this repository
+
+- Board events (a downstream app's own event kind for its own collaborative
+  documents) share KithMoot's chat kind (1460) under a scoped `d` tag, so a
+  relay cannot tell a board from a chat. This is why the kit's `KINDS`
+  registry keeps `CHAT` even though nothing in the kit itself sends chat
+  messages - it is there for a downstream app to reuse the same kind
+  number, deliberately, rather than mint its own.
+- The kit repository is public from the start.
+- The relay pool moves to the kit in a later step, after its churn settles.
+
+## Corrections after the source vector review
+
+- The kit's kinds subset must include chat kind 1460 (see the board-events
+  decision above).
+- `types.ts` imports a `Reachability` type used by roster and media types
+  that did not move; the split leaves that type, and everything that
+  depends on it, in the app that keeps it.
+- The relay transport interface (`RelayTransport`) lives in the module that
+  moves later with the relay pool; the kit declares the transport interface
+  it needs itself, rather than importing the app's.
+- Every module that owns a `kithmoot/` wire string exports a frozen
+  `*_LABELS` list; after any future cutover, the app's own label test would
+  import the kit's lists rather than re-declare them.
+
+## Peer dependency rationale (plan §3.4)
+
+Until an npm release exists, a consumer pins an exact Git commit. Once
+published, `nostr-tools` and the noble libraries are peer dependencies so
+a consumer keeps a single copy of each rather than a second one nested
+under this kit.