@forgesworn/fold-kit 0.9.0 → 0.12.0

package/README.md

@@ -13,10 +13,12 @@ vectors (see EXTRACTION.md). Framework-free: owns no storage, UI, relay
 defaults or identity keys, and no relay I/O of its own - callers inject a
 transport.
 
-**Status:** T1 extraction complete (see EXTRACTION.md). Not yet published to
-npm under this API; pin an immutable Git commit until it is (see Install).
-KithMoot itself has not cut over to this kit yet - it still carries its own
-copy of these modules.
+**Status:** Version 0.12.0 on `main`. Published on npm as
+`@forgesworn/fold-kit`, but `main` can run ahead of the npm `latest` release, so
+compare `npm view @forgesworn/fold-kit version` with this repository's
+`package.json` before relying on an API listed here. KithMoot has cut over to
+this kit and pins an exact npm version; its moved files are re-export shims
+(see EXTRACTION.md).
 
 ## Install
 
@@ -24,14 +26,12 @@ copy of these modules.
 npm install @forgesworn/fold-kit
 ```
 
-Not yet published to npm. Until it is, pin an immutable Git commit:
+To use a change that has not been released, pin an immutable Git commit (a full
+SHA, for example from `git ls-remote https://github.com/forgesworn/fold-kit main`).
+The package's `prepare` script builds `dist/` on install:
 
-```json
-{
-  "dependencies": {
-    "@forgesworn/fold-kit": "github:forgesworn/fold-kit#<commit>"
-  }
-}
+```bash
+npm install "github:forgesworn/fold-kit#<commit>"
 ```
 
 ### Peer dependencies
@@ -46,6 +46,12 @@ Not yet published to npm. Until it is, pin an immutable Git commit:
 }
 ```
 
+Install the peers yourself, keeping `@noble/hashes` on 1.x:
+
+```bash
+npm install "nostr-tools@>=2.24.2 <3" "@noble/hashes@^1.8.0" "@noble/curves@^2.0.1"
+```
+
 Peers, not dependencies, so a consumer such as KithMoot keeps a single copy
 of `nostr-tools` (guarded by its own `overrides` and version-guard test) and
 of the noble libraries, at the same versions KithMoot already pins.
@@ -57,12 +63,69 @@ satisfy this kit's imports as written.
 
 ESM only (`"type": "module"`). Node.js `>=22.13`.
 
+## Quick start
+
+Derive a room, then publish and load a stored group invitation through a
+`RelayTransport` you supply (this one is an in-memory stub; a real transport
+talks to relays and applies the filters):
+
+```ts
+import {
+  generateRoomSecret,
+  deriveRoom,
+  deriveEpoch,
+  localIdentity,
+  createRoomInvitation,
+  encodePersistentInvitation,
+  requestPersistentRoomAdmission,
+  type RelayTransport,
+} from '@forgesworn/fold-kit'
+import { generateSecretKey, type Event } from 'nostr-tools/pure'
+
+// The person: a local signer. An external one (NIP-07, NIP-46) fits the same seam.
+const me = localIdentity(generateSecretKey())
+
+// The room: one secret opens epoch 0; later epochs come from rekeys.
+const roomSecret = generateRoomSecret()
+const { roomId, roomKey } = deriveRoom(roomSecret)
+const epoch0 = deriveEpoch({ epoch: 0, secret: roomSecret }) // { epoch: 0, id: roomId, key: roomKey }
+
+// A RelayTransport stub: stores events, replays them on subscribe, then signals EOSE.
+const stored: Event[] = []
+const transport: RelayTransport = {
+  async publish(event) { stored.push(event) },
+  subscribe(_filters, onEvent, onEose) {
+    queueMicrotask(() => { for (const event of stored) onEvent(event); onEose?.() })
+    return () => {}
+  },
+  close() {},
+}
+
+// Invitation flow (v3 stored group invitation): the inviter publishes once, and a
+// guest holding the link loads it from the relays with no responder online.
+const { invitation, inviterSk } = createRoomInvitation(true)
+await transport.publish(encodePersistentInvitation({
+  invitation, inviterSk, roomSecret, now: Math.floor(Date.now() / 1000),
+}))
+const admission = await requestPersistentRoomAdmission({ transport, invitation })
+// admission.secret is the room secret: deriveRoom(admission.secret).roomId === roomId
+```
+
+Invitation versions: v1 (`encodeJoinUrl`, the room secret in the link) is
+legacy, and new links go through `createRoomInvitation`. Use
+`createRoomInvitation()` for the v2 live rendezvous, which needs a responder
+online (`hostRoomInvitation` answers, `requestRoomAdmissionCapability` joins),
+or `createRoomInvitation(true)` for the v3 stored group invitation above, which
+needs none.
+
 ## Exports
 
-Two entry points: `@forgesworn/fold-kit` (everything) and
+Four entry points: `@forgesworn/fold-kit` (circle primitives),
 `@forgesworn/fold-kit/lane` (just the lane helpers, for a consumer that only
 wants to classify a relay as `public`/`sheltered`/`direct` without pulling in
-the rest).
+the rest), `@forgesworn/fold-kit/mls-admission` (opt-in v4 evidence codec), and
+`@forgesworn/fold-kit/persistent-invitation-evidence` (bounded stored invitation
+observation and independent revalidation).
 
 ### Identity, verification, hex
 
@@ -104,13 +167,57 @@ the rest).
 
 ### Links and invitations
 
+`hostRoomInvitation` distinguishes approval from grant publication. Its
+`onGrantPublished(request)` and legacy `onAdmitted(device)` callbacks run only
+after the injected transport acknowledges the grant's publication.
+`onGrantFailed(request, error)` reports a rejected or throwing publication,
+or approval of a request which has expired;
+neither success callback runs for that failure. Closing or retiring the host
+suppresses callbacks from outstanding sends. Publication acknowledgement does
+not prove that a guest received the grant or joined; the guest validates its
+grant independently. Observer exceptions do not change the publish outcome. Fresh retries of the same
+signed request resend the exact cached grant after the configured quiet delay;
+overlapping approval, wait and publication work is coalesced. Approval and
+success callbacks each occur at most once per request. Failed sends may recover
+on a later retry. The host retains up to 256 live decisions, including declines;
+at capacity it refuses new work until settled requests expire. Close, retirement,
+request freshness and responder authority still gate every send.
+
+For a device that answers automatically, `grantDelayMs: [min, max]` waits a
+random time before each grant, and `coordinate: true` lets several delegated
+devices share one link: each waits (default 500 to 2000 ms) and stands down,
+at most once per request, if another responder's grant to the same
+requester appears. Both are off by default, and the wire format is
+unchanged. See `docs/quiet-replies.md`.
+
+An invitation request's `participant` is an unverified account claim.
+Automatic admission of a previously invited account must use
+`verifiedParticipant`, which is present only after a fresh signature check of
+an account proof bound to this invitation, ephemeral request device and request
+timestamp. `encodeInvitationAccountProof` creates that proof through the
+supplied matching `ParticipantIdentity`. It grants no room access itself and
+stays inside the bearer-encrypted request, rather than being published as a
+public account event. Invalid or missing proofs leave a request unverified;
+hosts can still make an explicit decision for anonymous and older clients.
+
+Pass `identity` to `requestRoomAdmissionCapability` (or `requestRoomAdmission`,
+its secret-only wrapper) to create the proof automatically. If `participant` is also supplied, it must
+match the signer; a signer failure rejects the request without falling back to
+another identity. `signal` cancels signing or waiting. Signing and relay waiting
+share one deadline, capped at the request's 90-second freshness window, and
+late signatures or grants cannot revive a cancelled, expired or retired request.
+Retrying publication uses the same signed request. A fresh human retry starts a
+new exchange. The helper copies a supplied `requesterSk` before signing and
+erases only its owned copy on settlement. Hosts recheck freshness when a human
+decision completes, so approval cannot extend an expired request's authority.
+
 - `parseRoomLink`, `encodeRoomLink`, `RoomLink` - the v1/v2/v3 link envelope
 - `createRoomInvitation`, `roomInvitation`, `deriveInvitationId`,
-  `encodeInvitationRequest`, `decodeInvitationRequest`,
+  `encodeInvitationAccountProof`, `encodeInvitationRequest`, `decodeInvitationRequest`,
   `verifyInvitationDelegation`, `encodeInvitationGrant`,
   `decodeRoomAdmissionGrant`, `encodeInvitationRetirement`,
   `decodeInvitationRetirementNotice`, `hostRoomInvitation`,
-  `requestRoomAdmission` - the v2 live rendezvous invitation, its delegation
+  `requestRoomAdmissionCapability`, `requestRoomAdmission` - the v2 live rendezvous invitation, its delegation
   chain and retirement
 - `encodePersistentInvitation`, `decodePersistentInvitation`,
   `requestPersistentRoomAdmission` - the v3 stored group invitation (1463).
@@ -118,6 +225,23 @@ 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
+- From `@forgesworn/fold-kit/persistent-invitation-evidence`,
+  `requestPersistentRoomAdmissionEvidence` and
+  `revalidatePersistentInvitationEvidence` retain and independently recheck a
+  bounded set of canonical signed invitation/retirement carriers, with exact
+  invitation and contributing event IDs. The additive evidence path holds on
+  conflicting newest equal-time relay lists; the legacy request is unchanged.
+  EOSE is local observation metadata, never proof of current membership or
+  global non-retirement. Persist the evidence in protected custody before
+  using its decoded fields. See [the evidence contract](docs/persistent-invitation-evidence.md).
+- The same optional entry exports `revalidatePersistentInvitationSource` for
+  an actual encoder event or its exact canonical retained string. It requires
+  the invitation capability and exact room-root pin, independently verifies
+  the signature and supported body/tags, and returns one canonical carrier
+  plus owned decoded fields. This single source has no EOSE, publication,
+  latest-selection or current-membership claim. Creators retain that event
+  and their publication intent before opening a pool, then retry the same
+  bytes; protected persistence and fresh effect guards belong to the client.
 - 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
@@ -152,6 +276,14 @@ the rest).
   catch-up for a device that missed a rekey
 - `hostRoomEpoch`, `requestRoomEpoch`, `EpochRefusedError` - the live
   request/grant desk
+- Quiet replies (`docs/quiet-replies.md`): `hostRoomEpoch` waits a random
+  `replyDelayMs` (default `[500, 2000]`) before any answer, sends a
+  participant a `removed` or `closed` refusal once per `refuseAgainAfter`
+  (default 3600 s) and `unknown` once per `reportUnknownEvery` (60 s), and
+  caps refusals at `maxRefusalsPerMinute` (20). Grants are never limited.
+  `RefusalLimiter`, `replyDelay` and the `DEFAULT_REPLY_DELAY_MS`,
+  `REFUSE_AGAIN_AFTER_SECONDS`, `MAX_REFUSALS_PER_MINUTE` and
+  `REFUSAL_LIMITER_CAPACITY` constants are exported
 - 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
@@ -263,3 +395,54 @@ There is no separate lint script.
 ## Licence
 
 MIT
+
+### Live persistent admission (opt-in codecs)
+
+`parseLivePersistentEvent` bounds raw event JSON and refuses duplicate fields.
+`encodeLivePersistentDescriptor` / `decodeLivePersistentDescriptor` carry
+routing metadata alongside an unchanged persistent invitation link.
+`encodeLivePersistentRequest` / `decodeLivePersistentRequest` and
+`encodeLivePersistentAnswer` / `decodeLivePersistentAnswer` implement a fresh,
+root-signed challenge/answer with no delegation. The answer retains epoch-zero
+capability separately from `epochHint`. Constants bound request/answer lifetimes
+to 90/30 seconds. `LIVE_PERSISTENT_ADMISSION_LABELS` freezes its distinct KDF.
+
+These functions are codecs, not an offline join API. The host must have exclusive
+durable lifecycle authority; the client must complete authenticated epoch
+admission before publishing, including at epoch zero. No application enables
+this profile automatically. See [the wire profile and integration gates](docs/live-persistent-admission.md).
+Frozen synthetic fixtures are in `vectors/live-persistent-vectors.json`; run
+`npm run build && npm run generate-live-persistent` to regenerate them.
+
+## Authenticated invitation refusal (0.12.0)
+
+`encodeInvitationDecline` and `decodeInvitationDecline` exchange a private,
+request-bound refusal from the pinned inviter or a current delegated responder.
+The version-3 refusal body uses reply kind 20467 and contains no room secret or
+new delegation. Legacy version-2 grant readers ignore it.
+`requestRoomAdmissionCapability` stops retries and rejects with
+`InvitationDeclinedError` after verifying a refusal. Existing host `admit` hooks
+returning false still leave requests unanswered; hosts must explicitly publish
+a refusal using their guarded, acknowledged decision path. No UI integration or
+physical acceptance is claimed by this protocol release.
+
+### MLS admission v4 evidence codec
+
+The separate opt-in v4 codec binds an encrypted account/device request to signed
+keeper consent and an expected MLS group. It uses existing 20466/20467 carriers,
+strict canonical arrays and a fixed payload bucket. Existing room links/codecs
+are unchanged. Import from `@forgesworn/fold-kit/mls-admission`; see [API and boundaries](docs/mls-admission-v4.md).
+
+Exports: `encodeMlsInvitationV4`, `readMlsInvitationV4`,
+`mlsAdmissionProofTemplatesV4`, `encodeMlsAdmissionRequestV4`,
+`decodeMlsAdmissionRequestV4`, `readMlsAdmissionRequestV4`,
+`encodeMlsAdmissionAnswerV4`, `decodeMlsAdmissionAnswerV4`,
+`readMlsAdmissionAnswerV4`, `MLS_ADMISSION_LABELS`,
+`MLS_ADMISSION_PLAINTEXT_BYTES`, `MLS_ADMISSION_CIPHERTEXT_CHARACTERS`;
+types `VerifiedMlsAdmissionRequest` and `VerifiedAdmissionAnswer`.
+
+Verified answers are evidence only. Actual admission requires new purpose-bound
+vault proof and authoritative live box/Link role-witness APIs, a conditional
+keeper revision at the effect boundary, current custody/consent, durable counter
+and one-shot operation storage, and VMLS/Welcome verification. No browser
+admission, authority factory, transport, storage or automatic retry is provided.

package/dist/epoch.d.ts

@@ -2,6 +2,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';
+import { type ReplyDelayRange, type ReplySchedule } from './quiet-reply.js';
 /**
  * Room epochs: how a member is removed.
  *
@@ -413,15 +414,34 @@ export interface HostRoomEpochOptions {
      *  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. */
+     *  reported again. Default 60. An `unknown` answer goes on the wire at
+     *  the same cadence: a fresh request inside it is reported to nobody and
+     *  answered with silence. */
     reportUnknownEvery?: number;
     policy?: RoomPolicy;
     legacyParticipants?: ReadonlySet<string>;
     now?: () => number;
     onGranted?: (request: EpochRequest) => void;
+    /** Called for every refusal, including one the limits below kept off the
+     *  wire. */
     onRefused?: (request: EpochRequest, why: EpochRefusal) => void;
     /** A conference room's end: every grant carries it as an expiration. */
     expiresAt?: number;
+    /** Seconds before the same participant is sent a `removed` or `closed`
+     *  refusal again. Default 3600 (`REFUSE_AGAIN_AFTER_SECONDS`). A request
+     *  inside it is not answered, so the asker times out instead. */
+    refuseAgainAfter?: number;
+    /** Refusals of any kind published in any 60 seconds, whoever asks.
+     *  Default 20 (`MAX_REFUSALS_PER_MINUTE`). Grants are never limited. */
+    maxRefusalsPerMinute?: number;
+    /** The random wait, in milliseconds, before any answer is published,
+     *  grant or refusal. Default `[500, 2000]` (`DEFAULT_REPLY_DELAY_MS`);
+     *  `[0, 0]` answers at once, as before. */
+    replyDelayMs?: ReplyDelayRange;
+    /** For tests: a source of numbers in [0, 1). Default `Math.random`. */
+    random?: () => number;
+    /** For tests: how the wait is timed. Default `setTimeout`. */
+    schedule?: ReplySchedule;
 }
 /**
  * The credential to seal an answer to: the one the request carries, unless
@@ -448,6 +468,13 @@ export declare function sealCredential(request: {
  * 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.
+ *
+ * Every answer waits a random `replyDelayMs` first, and refusals are
+ * rationed: one a participant per `refuseAgainAfter` (per
+ * `reportUnknownEvery` for `unknown`), and `maxRefusalsPerMinute` in all.
+ * A removed member who still holds the room key can otherwise ask with
+ * fresh requests for ever and time each signed reply, which tells them
+ * when the authority is online. What an answer says is unchanged.
  */
 export declare function hostRoomEpoch(opts: HostRoomEpochOptions): {
     close(): void;

package/dist/epoch.js

@@ -15,6 +15,7 @@ import { verifyEventUncached } from './verify.js';
 import { newerCredential, openSealed, sealTo } from './seal.js';
 import { withExpiration } from './expiration.js';
 import { epochCommitment } from './epoch-commit.js';
+import { DEFAULT_REPLY_DELAY_MS, REFUSE_AGAIN_AFTER_SECONDS, RefusalLimiter, defaultReplySchedule, replyDelay } from './quiet-reply.js';
 /**
  * Room epochs: how a member is removed.
  *
@@ -622,6 +623,13 @@ export function sealCredential(request, presented, credentialFor, roomId, now) {
  * 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.
+ *
+ * Every answer waits a random `replyDelayMs` first, and refusals are
+ * rationed: one a participant per `refuseAgainAfter` (per
+ * `reportUnknownEvery` for `unknown`), and `maxRefusalsPerMinute` in all.
+ * A removed member who still holds the room key can otherwise ask with
+ * fresh requests for ever and time each signed reply, which tells them
+ * when the authority is online. What an answer says is unchanged.
  */
 export function hostRoomEpoch(opts) {
     require32(opts.authoritySk, 'authority secret key');
@@ -640,6 +648,13 @@ export function hostRoomEpoch(opts) {
         if (set.size > 256)
             set.delete(set.values().next().value);
     };
+    const refusals = new RefusalLimiter({ perMinute: opts.maxRefusalsPerMinute });
+    const delayRange = opts.replyDelayMs ?? DEFAULT_REPLY_DELAY_MS;
+    const random = opts.random ?? Math.random;
+    const schedule = opts.schedule ?? defaultReplySchedule;
+    /** Requests waiting out their delay, each with how to cancel it. Bounded:
+     *  a request turned away while it is full is answered on its retry. */
+    const pending = new Map();
     let closed = false;
     const unsub = opts.transport.subscribe([{ kinds: [KINDS.EPOCH_REQUEST], '#d': [roomId], '#p': [authority] }], (event) => {
         if (closed)
@@ -652,80 +667,104 @@ export function hostRoomEpoch(opts) {
             policy: opts.policy,
             legacyParticipants: opts.legacyParticipants,
         });
-        if (!read || answered.has(read.request.request))
+        if (!read || answered.has(read.request.request) || pending.has(read.request.request))
             return;
         const request = read.request;
-        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))
+        const reply = () => {
+            pending.delete(request.request);
+            if (closed)
                 return;
-            waiting.add(request.request);
-            bound(waiting);
-        }
-        else {
-            waiting.delete(request.request);
-            answered.add(request.request);
-            bound(answered);
-        }
-        let grant;
-        try {
-            if (refused) {
-                grant = encodeEpochGrant({
-                    roomId,
-                    authoritySk: opts.authoritySk,
-                    device: request.device,
-                    request: request.request,
-                    now: now(),
-                    refused,
-                    credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
-                    expiresAt: opts.expiresAt,
-                });
+            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 {
-                const epoch = opts.current();
-                grant = encodeEpochGrant({
-                    roomId,
-                    authoritySk: opts.authoritySk,
-                    device: request.device,
-                    request: request.request,
-                    now: now(),
-                    epoch,
-                    removed: [...opts.removed()],
-                    ...(opts.members ? { members: [...opts.members()] } : {}),
-                    ...(opts.past ? { passed: passedFor(opts.past, epoch.epoch, now()) } : {}),
-                    credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
-                    expiresAt: opts.expiresAt,
-                });
+                waiting.delete(request.request);
+                answered.add(request.request);
+                bound(answered);
             }
-        }
-        catch {
+            const quiet = refused !== undefined && !refusals.allow(request.participant, refused === 'unknown' ? (opts.reportUnknownEvery ?? REPORT_UNKNOWN_EVERY_SECONDS) : (opts.refuseAgainAfter ?? REFUSE_AGAIN_AFTER_SECONDS), now());
+            if (!quiet) {
+                let grant;
+                try {
+                    if (refused) {
+                        grant = encodeEpochGrant({
+                            roomId,
+                            authoritySk: opts.authoritySk,
+                            device: request.device,
+                            request: request.request,
+                            now: now(),
+                            refused,
+                            credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
+                            expiresAt: opts.expiresAt,
+                        });
+                    }
+                    else {
+                        const epoch = opts.current();
+                        grant = encodeEpochGrant({
+                            roomId,
+                            authoritySk: opts.authoritySk,
+                            device: request.device,
+                            request: request.request,
+                            now: now(),
+                            epoch,
+                            removed: [...opts.removed()],
+                            ...(opts.members ? { members: [...opts.members()] } : {}),
+                            ...(opts.past ? { passed: passedFor(opts.past, epoch.epoch, now()) } : {}),
+                            credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
+                            expiresAt: opts.expiresAt,
+                        });
+                    }
+                }
+                catch {
+                    return;
+                }
+                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)
+                refusals.forget(request.participant);
+            if (refused)
+                opts.onRefused?.(request, refused);
+            else
+                opts.onGranted?.(request);
+        };
+        const delay = replyDelay(delayRange, random);
+        if (delay === 0) {
+            reply();
             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
-            opts.onGranted?.(request);
+        if (pending.size >= 256)
+            return;
+        pending.set(request.request, () => { });
+        const cancel = schedule(reply, delay);
+        if (pending.has(request.request))
+            pending.set(request.request, cancel);
     });
     return {
         close() {
             if (closed)
                 return;
             closed = true;
+            for (const cancel of pending.values())
+                cancel();
+            pending.clear();
             unsub();
         },
     };

package/dist/index.d.ts

@@ -18,8 +18,10 @@ export { MAX_RELAY_HINTS, MAX_ICE_HINTS, MAX_NETWORK_HINT_LENGTH, isSafeRelayUrl
 export { sanitiseDisplayName, MAX_DISPLAY_NAME_LENGTH } from './display-name.js';
 export { issueKindredProof, evaluateAccess, ACCESS_LABELS, } from './access.js';
 export type { IssueKindredProofOptions } 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 type { RoomInvitation, RoomInvitationHost, InvitationDelegation, RoomInvitationDelegate, RoomAdmission, EncodeInvitationRequestOptions, InvitationRequest, DecodeInvitationRequestOptions, EncodeInvitationGrantOptions, DecodeInvitationGrantOptions, HostRoomInvitationOptions, EncodeInvitationRetirementOptions, RequestRoomAdmissionOptions, } from './invitation.js';
+export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationAccountProof, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
+export type { RoomInvitation, RoomInvitationHost, InvitationDelegation, RoomInvitationDelegate, RoomAdmission, EncodeInvitationAccountProofOptions, EncodeInvitationRequestOptions, InvitationRequest, DecodeInvitationRequestOptions, EncodeInvitationGrantOptions, DecodeInvitationGrantOptions, HostRoomInvitationOptions, EncodeInvitationRetirementOptions, RequestRoomAdmissionOptions, } from './invitation.js';
+export { encodeInvitationDecline, decodeInvitationDecline, InvitationDeclinedError } from './invitation-decline.js';
+export type { EncodeInvitationDeclineOptions, InvitationDecline } from './invitation-decline.js';
 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';
@@ -28,9 +30,12 @@ export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from '.
 export type { RoomLink } from './link.js';
 export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, HISTORY_WINDOW_SECONDS, MAX_HISTORY_EPOCHS, epochsInWindow, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, sealCredential, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
 export type { RoomEpoch, EpochKeys, EncodeRekeyOptions, RekeyRecipient, RekeyNotice, PeekRekeyOptions, DecodeRekeyOptions, LeftEpoch, EpochRequestAdmissionOptions, EncodeEpochRequestOptions, DecodeEpochRequestOptions, EpochRequest, EpochRefusal, EncodeEpochGrantOptions, DecodeEpochGrantOptions, EpochGrant, HostRoomEpochOptions, RequestRoomEpochOptions, SignAdminsOptions, SignChannelsOptions, VerifyChannelsOptions, VerifyAdminsOptions, } from './epoch.js';
+export { DEFAULT_REPLY_DELAY_MS, REFUSE_AGAIN_AFTER_SECONDS, MAX_REFUSALS_PER_MINUTE, REFUSAL_LIMITER_CAPACITY, RefusalLimiter, replyDelay, } from './quiet-reply.js';
+export type { ReplyDelayRange, ReplySchedule, RefusalLimiterOptions } from './quiet-reply.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';
+export * from "./live-persistent-admission.js";

package/dist/index.js

@@ -12,13 +12,17 @@ export { generateRoomSecret, deriveRoom, encodeJoinUrl, decodeJoinUrl, parseRoom
 export { MAX_RELAY_HINTS, MAX_ICE_HINTS, MAX_NETWORK_HINT_LENGTH, isSafeRelayUrl, safeRelayUrls, isSafeIceUrl, safeIceUrls, assertNetworkHintBounds, } from './network-hints.js';
 export { sanitiseDisplayName, MAX_DISPLAY_NAME_LENGTH } from './display-name.js';
 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 { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationAccountProof, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
+export { encodeInvitationDecline, decodeInvitationDecline, InvitationDeclinedError } from './invitation-decline.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, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, HISTORY_WINDOW_SECONDS, MAX_HISTORY_EPOCHS, epochsInWindow, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, sealCredential, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export { DEFAULT_REPLY_DELAY_MS, REFUSE_AGAIN_AFTER_SECONDS, MAX_REFUSALS_PER_MINUTE, REFUSAL_LIMITER_CAPACITY, RefusalLimiter, replyDelay, } from './quiet-reply.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';
+// Opt-in live persistent capability exchange; host lifecycle and epoch gates remain required.
+export * from "./live-persistent-admission.js";

package/dist/invitation-decline.d.ts

@@ -0,0 +1,26 @@
+import { type Event } from 'nostr-tools/pure';
+import type { DecodeInvitationGrantOptions, InvitationDelegation, RoomInvitation } from './invitation.js';
+export interface EncodeInvitationDeclineOptions {
+    invitation: RoomInvitation;
+    inviterSk: Uint8Array;
+    requester: string;
+    request: string;
+    now: number;
+    /** Root-to-responder chain; empty only for the pinned root inviter. */
+    delegation?: InvitationDelegation[];
+}
+export interface InvitationDecline {
+    request: string;
+    responder: string;
+}
+export declare class InvitationDeclinedError extends Error {
+    constructor();
+}
+/** A private refusal, carrying no room secret or new responder delegation.
+ * Version 3 distinguishes it from version-2 grants on the same reply kind.
+ * Older readers ignore it and continue their existing bounded wait. */
+export declare function encodeInvitationDecline(opts: EncodeInvitationDeclineOptions): Event;
+/** Only a fresh, request-bound refusal from the pinned root or a currently
+ * delegated responder can stop this guest's wait. A bearer holder has no
+ * authority to refuse someone else. No room capability is returned. */
+export declare function decodeInvitationDecline(event: Event, opts: DecodeInvitationGrantOptions): InvitationDecline | null;