@forgesworn/fold-kit 0.13.0 → 0.14.0

package/dist/persistent-invitation-evidence.js

@@ -2,17 +2,38 @@ 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 { getEventHash, 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 { isInvitationStorage } from './invitation-storage.js';
 import { deriveRoom } from './room.js';
 import { KINDS } from './kinds.js';
 import { verifyEventUncached } from './verify.js';
+import { MAX_PERSISTENT_INVITATION_EVENT_BYTES, MAX_EVIDENCE_CARRIER_TAGS, MAX_EVIDENCE_CARRIER_TAG_STRINGS } from './evidence-carrier.js';
 export const MAX_PERSISTENT_INVITATION_EVIDENCE_EVENTS = 64;
-export const MAX_PERSISTENT_INVITATION_EVENT_BYTES = 16_384;
+export { MAX_PERSISTENT_INVITATION_EVENT_BYTES };
 export const MAX_PERSISTENT_INVITATION_EVIDENCE_BYTES = 262_144;
+/** Raw deliveries one query reads, counted before anything is parsed: every
+ * relay's copy of every event, repeats, other authors and junk alike. It bounds
+ * parse work only. It is eight times the retained-event limit, so 64 events
+ * from each of eight relays still fit. Past it the query fails closed, because
+ * an event that could matter may be among those it did not read. */
+export const MAX_PERSISTENT_INVITATION_EVIDENCE_DELIVERIES = 512;
+/** Signature checks one query is charged. Only an event that is in scope and
+ * not already held or refused costs one, so a repeat costs none. It is twice
+ * the retained-event limit: room for 64 retained events and 64 more in-scope
+ * events that fail (forged, over the evidence size limits, or signed but not a
+ * supported body). Beyond it the query fails closed rather than skip an
+ * unchecked event.
+ *
+ * It bounds checks, not Schnorr verifications. A retained retirement is
+ * verified twice (its scope check, then the retirement decoder), and the
+ * finished query revalidates every retained event, so the worst case is
+ * 128 + 64 verifications on a query that succeeds. A forgery fails at its
+ * first verification, so a hostile relay can cause at most 128. */
+export const MAX_PERSISTENT_INVITATION_EVIDENCE_VERIFICATIONS = 128;
 /** Incomplete observations are bounded diagnostic custody only. They are
  * never accepted by revalidatePersistentInvitationEvidence. */
 export class PersistentInvitationEvidenceQueryError extends Error {
@@ -27,8 +48,9 @@ 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) {
+/** JSON string byte cost including escaping, without serialising content.
+ * `limited` throws past the per-event ceiling; unlimited only measures. */
+function jsonStringBytes(value, limited = true) {
     let bytes = 2;
     for (let i = 0; i < value.length; i++) {
         const c = value.charCodeAt(i);
@@ -48,7 +70,7 @@ function jsonStringBytes(value) {
             bytes += 6;
         else
             bytes += 3;
-        if (bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+        if (limited && bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
             throw new Error('oversized evidence event');
     }
     return bytes;
@@ -82,37 +104,53 @@ function dataArray(raw, limit) {
     return values;
 }
 /** Fresh carrier copy, with no trusted verification-cache symbol. Bounds
- * precede copying or serialising potentially large strings/tag arrays. */
-function carrier(raw) {
+ * precede copying or serialising potentially large strings/tag arrays.
+ *
+ * `tolerant` lifts only the size ceilings (bytes, tag count, tag width): every
+ * plain-data, prototype, type and hex refusal stays. The copy of an event that
+ * exceeds a ceiling comes back with `over` set and no canonical form, because
+ * it can never be retained as evidence. The query uses that to check whether
+ * the authority signed it. */
+function carrier(raw, tolerant = false) {
+    let over = false;
+    const exceed = (message) => { if (!tolerant)
+        throw new Error(message); over = true; };
     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)
+        typeof d.content !== 'string')
         throw new Error('invalid or oversized evidence event');
+    if (d.content.length > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+        exceed('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);
+        String(d.created_at).length + String(d.kind).length + jsonStringBytes(d.id) + jsonStringBytes(d.pubkey) + jsonStringBytes(d.sig) + jsonStringBytes(d.content, !tolerant);
     if (bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
-        throw new Error('oversized evidence event');
-    const outer = dataArray(d.tags, 64);
+        exceed('oversized evidence event');
+    const outer = dataArray(d.tags, tolerant ? Infinity : MAX_EVIDENCE_CARRIER_TAGS);
+    if (outer.length > MAX_EVIDENCE_CARRIER_TAGS)
+        over = true;
     bytes += 2 + Math.max(0, outer.length - 1);
     const tags = outer.map(tag => {
-        const inner = dataArray(tag, 8);
+        const inner = dataArray(tag, tolerant ? Infinity : MAX_EVIDENCE_CARRIER_TAG_STRINGS);
+        if (inner.length > MAX_EVIDENCE_CARRIER_TAG_STRINGS)
+            over = true;
         bytes += 2 + Math.max(0, inner.length - 1);
         return inner.map(value => {
-            if (typeof value !== 'string' || value.length > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+            if (typeof value !== 'string')
                 throw new Error('invalid or oversized evidence tag');
-            bytes += jsonStringBytes(value);
+            if (value.length > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
+                exceed('invalid or oversized evidence tag');
+            bytes += jsonStringBytes(value, !tolerant);
             if (bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
-                throw new Error('oversized evidence event');
+                exceed('oversized evidence event');
             return value;
         });
     });
     if (bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES)
-        throw new Error('oversized evidence event');
+        exceed('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 };
+    return { event, canonical: over ? '' : JSON.stringify(event), bytes, over };
 }
 function copyInvitation(invitation) {
     if (!invitation.persistent || !(invitation.bearer instanceof Uint8Array) || invitation.bearer.length !== 32 || !hex32.test(invitation.inviter))
@@ -124,10 +162,16 @@ function roomId(secret) {
     room.roomKey.fill(0);
     return room.roomId;
 }
+/** The cheap, unsigned part of scope: the authority, a source kind and exactly
+ * one two-element `d` tag naming this invitation. No crypto. */
+function inAuthorityScope(event, inviter, invitationId) {
+    if (event.pubkey !== inviter || (event.kind !== KINDS.GROUP_INVITATION && event.kind !== KINDS.INVITATION_RETIREMENT))
+        return false;
+    const d = event.tags.filter(tag => tag[0] === 'd');
+    return d.length === 1 && d[0].length === 2 && d[0][1] === invitationId;
+}
 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);
+    return inAuthorityScope(event, invitation.inviter, deriveInvitationId(invitation)) && verifyEventUncached(event);
 }
 /** Strict evidence path accepts exactly the bodies/tags of supported writers;
  * permissive legacy decoding and its public request remain unchanged. */
@@ -142,19 +186,21 @@ function decodeEvidenceEvent(event, invitation) {
     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']);
+        const body = dataRecord(JSON.parse(plaintext), ['v', 'room', 'secret', 'ends', 'destruct', 'relays', 'storage']);
         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)))
+            (body.destruct !== undefined && body.destruct !== true) || (body.relays !== undefined && !isInvitationRelays(body.relays)) ||
+            (body.storage !== undefined && !isInvitationStorage(body.storage)))
             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] }) };
+            ...(body.relays === undefined ? {} : { relays: [...body.relays] }),
+            ...(body.storage === undefined ? {} : { storage: [...body.storage], storageAt: event.created_at }) };
         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 }) });
+            ...(decoded.relays === undefined ? {} : { relays: decoded.relays }), ...(decoded.storage === undefined ? {} : { storage: decoded.storage }) });
         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;
@@ -277,12 +323,20 @@ export function revalidatePersistentInvitationEvidence(opts) {
         if (new Set(winners.map(d => JSON.stringify(d.admission.relays))).size > 1)
             return held('conflicting-relays');
         const relays = winners[0]?.admission.relays;
+        const storageEvents = decoded.filter(d => d.admission.storage !== undefined);
+        const newestStorage = storageEvents.length ? Math.max(...storageEvents.map(d => d.event.created_at)) : undefined;
+        const storageWinners = storageEvents.filter(d => d.event.created_at === newestStorage);
+        if (new Set(storageWinners.map(d => JSON.stringify(d.admission.storage))).size > 1)
+            return held('conflicting-storage');
+        const storage = storageWinners[0]?.admission.storage;
         const admission = { secret: first.slice(), persistent: true, epoch: 0,
             ...(endsAt === undefined ? {} : { endsAt }), ...(destruct.length ? { destruct: true } : {}),
-            ...(relays === undefined ? {} : { relays: [...relays] }) };
+            ...(relays === undefined ? {} : { relays: [...relays] }),
+            ...(storage === undefined ? {} : { storage: [...storage], storageAt: newestStorage }) };
         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)) });
+            destruct: Object.freeze(destruct.map(d => d.event.id)), relays: Object.freeze(winners.map(d => d.event.id)),
+            ...(storageWinners.length ? { storage: Object.freeze(storageWinners.map(d => d.event.id)) } : {}) });
         return Object.freeze({ evidence, outcome: Object.freeze({ status: 'admitted', admission, contributors }) });
     }
     finally {
@@ -333,29 +387,61 @@ export async function requestPersistentRoomAdmissionEvidence(opts) {
                 return;
             }
             try {
-                unsub = opts.transport.subscribe([{ kinds: [KINDS.GROUP_INVITATION, KINDS.INVITATION_RETIREMENT], authors: [invitation.inviter], '#d': [deriveInvitationId(invitation)] }], event => {
+                const invitationId = deriveInvitationId(invitation);
+                // Canonical forms that were checked and refused, so a repeat of one costs no crypto.
+                const refused = new Set();
+                let verifications = 0;
+                unsub = opts.transport.subscribe([{ kinds: [KINDS.GROUP_INVITATION, KINDS.INVITATION_RETIREMENT], authors: [invitation.inviter], '#d': [invitationId] }], 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');
+                        // Every delivery is charged first and bounds parse work. Retained
+                        // events, retained bytes and signature checks have their own limits.
+                        if (received >= MAX_PERSISTENT_INVITATION_EVIDENCE_DELIVERIES)
+                            throw new Error('invitation evidence query capacity exceeded: too many deliveries');
                         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');
+                        let c;
+                        try {
+                            c = carrier(event, true);
+                        }
+                        catch {
+                            return;
+                        } // malformed beyond size: not evidence, not a failure
+                        if (!inAuthorityScope(c.event, invitation.inviter, invitationId))
+                            return;
+                        // An id already held was verified, so any other carrier with that id
+                        // has the same signed fields and nothing new to say. A carrier that
+                        // only claims it cannot verify. Dropping it loses no signed event.
+                        // An over-limit carrier is remembered by its computed hash and signature,
+                        // never by the id it claims: a tampered copy that claims a real event's
+                        // id and signature has a different hash, so it cannot mask the real one.
+                        const overKey = c.over ? `${getEventHash(c.event)}:${c.event.sig}` : '';
+                        if (events.has(c.event.id) || refused.has(c.over ? overKey : c.canonical))
+                            return;
+                        if (verifications >= MAX_PERSISTENT_INVITATION_EVIDENCE_VERIFICATIONS)
+                            throw new Error('invitation evidence query capacity exceeded: too many signature checks');
+                        verifications++;
+                        if (c.over) {
+                            // Over the size limits, so it can never be retained. If the authority
+                            // signed it, it may be a retirement or a newer list that this query
+                            // cannot hold: fail closed rather than select without it. An event
+                            // that only claims the authority's key is dropped.
+                            if (verifyEventUncached(c.event))
+                                throw new Error('invitation evidence query refused an event signed by the authority that exceeds the evidence size limits');
+                            refused.add(overKey);
                             return;
                         }
                         const decoded = decodeEvidenceEvent(c.event, invitation);
-                        if (!decoded)
+                        if (!decoded) {
+                            refused.add(c.canonical);
                             return;
+                        }
                         if (decoded !== 'retired')
                             decoded.secret.fill(0);
+                        // A valid authority event that no longer fits fails the query: never evict or truncate.
+                        if (events.size >= MAX_PERSISTENT_INVITATION_EVIDENCE_EVENTS || bytes + c.bytes > MAX_PERSISTENT_INVITATION_EVIDENCE_BYTES)
+                            throw new Error('invitation evidence query capacity exceeded');
+                        bytes += c.bytes;
                         events.set(c.event.id, c.canonical);
                     }
                     catch (error) {

package/dist/persistent-invitation.d.ts

@@ -16,6 +16,13 @@ export interface PersistentRoomAdmission {
     /** The room self-destructs: when it ends, every device deletes what it
      *  wrote and forgets the room. Absent for a room that simply ends. */
     destruct?: true;
+    /** The room's group storage nodes, as its authority last signed them; `[]`
+     *  when it withdrew them all. Absent from an invitation written before
+     *  0.14.0, or when no copy names them. */
+    storage?: string[];
+    /** The `created_at` of the copy whose `storage` stood: present exactly when
+     *  `storage` is. A client uses it as the record's version. */
+    storageAt?: number;
 }
 /** Publish once before sharing. The link plus this envelope is a durable
  * bearer capability: anybody holding both can learn epoch 0. Retirement
@@ -33,6 +40,11 @@ export declare function encodePersistentInvitation(opts: {
      *  form (see `isInvitationRelays`), else it throws. Omitted, the body is
      *  byte-identical to 0.3.0's. */
     relays?: readonly string[];
+    /** The room's group storage nodes: zero to eight canonical node base URLs,
+     *  one per host (see `isInvitationStorage`), else it throws. `[]` says the
+     *  authority withdrew every node. Written after `relays`. Omitted, the body
+     *  is byte-identical to 0.13.0's. */
+    storage?: readonly string[];
     /** The room self-destructs when it ends, by its time or by its authority
      *  closing it. Written inside the encrypted body only, never as a tag.
      *  Omitted or false, the event is byte-identical to 0.8.0's. */

package/dist/persistent-invitation.js

@@ -9,6 +9,8 @@ import { deriveRoom } from './room.js';
 import { verifyEventUncached } from './verify.js';
 import { isRoomEnds, requireRoomEnds } from './expiration.js';
 import { isInvitationRelays, requireInvitationRelays } from './invitation-relays.js';
+import { isInvitationStorage, requireInvitationStorage } from './invitation-storage.js';
+import { requireEvidenceCarrierLimits } from './evidence-carrier.js';
 function welcomeKey(invitation) {
     if (!invitation.persistent)
         throw new Error('a persistent group invitation is required');
@@ -25,14 +27,15 @@ export function encodePersistentInvitation(opts) {
     const room = deriveRoom(opts.roomSecret).roomId;
     const ends = opts.endsAt === undefined ? undefined : requireRoomEnds(opts.endsAt, opts.now);
     const relays = opts.relays === undefined ? undefined : requireInvitationRelays(opts.relays);
-    return finalizeEvent({
+    const storage = opts.storage === undefined ? undefined : requireInvitationStorage(opts.storage);
+    return requireEvidenceCarrierLimits(finalizeEvent({
         kind: KINDS.GROUP_INVITATION,
         created_at: opts.now,
         tags: ends === undefined ? [['d', deriveInvitationId(opts.invitation)]] : [['d', deriveInvitationId(opts.invitation)], ['expiration', String(ends)]],
         content: nip44.v2.encrypt(JSON.stringify({
-            v: 3, room, secret: base64urlnopad.encode(opts.roomSecret), ...(ends === undefined ? {} : { ends }), ...(opts.destruct ? { destruct: true } : {}), ...(relays === undefined ? {} : { relays }),
+            v: 3, room, secret: base64urlnopad.encode(opts.roomSecret), ...(ends === undefined ? {} : { ends }), ...(opts.destruct ? { destruct: true } : {}), ...(relays === undefined ? {} : { relays }), ...(storage === undefined ? {} : { storage }),
         }), welcomeKey(opts.invitation)),
-    }, opts.inviterSk);
+    }, opts.inviterSk), 'group invitation');
 }
 export function decodePersistentInvitation(event, invitation) {
     try {
@@ -62,6 +65,10 @@ export function decodePersistentInvitation(event, invitation) {
         // would write; a malformed one refuses the envelope rather than half of it.
         if (body.relays !== undefined && !isInvitationRelays(body.relays))
             return null;
+        // The same for the room's storage nodes: `[]` is valid (withdrawn), a
+        // malformed list refuses the envelope.
+        if (body.storage !== undefined && !isInvitationStorage(body.storage))
+            return null;
         // Self-destruct is `true` or absent; anything else is a malformed
         // envelope, refused as a malformed end is.
         if (body.destruct !== undefined && body.destruct !== true)
@@ -69,6 +76,10 @@ export function decodePersistentInvitation(event, invitation) {
         const admission = ends === undefined ? { secret, persistent: true, epoch: 0 } : { secret, persistent: true, epoch: 0, endsAt: ends };
         if (body.relays !== undefined)
             admission.relays = [...body.relays];
+        if (body.storage !== undefined) {
+            admission.storage = [...body.storage];
+            admission.storageAt = event.created_at;
+        }
         if (body.destruct === true)
             admission.destruct = true;
         return admission;
@@ -89,6 +100,7 @@ export function requestPersistentRoomAdmission(opts) {
         let settled = false;
         let admission;
         let relaysAt = -1;
+        let storageAt = -1;
         let unsub = () => { };
         const timer = setTimeout(() => finish(new Error('the group invitation could not be loaded from its relays')), opts.timeoutMs ?? 15_000);
         function finish(error) {
@@ -136,6 +148,16 @@ export function requestPersistentRoomAdmission(opts) {
                     relaysAt = event.created_at;
                 else if (admission?.relays !== undefined)
                     decoded.relays = admission.relays;
+                // The storage nodes merge the same way, independently of the relays:
+                // the newest copy that names them stands, `[]` included; a copy that
+                // names none says nothing, so the keeper's plain copy never erases
+                // the list; on equal timestamps the first heard stays.
+                if (decoded.storage !== undefined && event.created_at > storageAt)
+                    storageAt = event.created_at;
+                else if (admission?.storage !== undefined) {
+                    decoded.storage = admission.storage;
+                    decoded.storageAt = admission.storageAt;
+                }
                 admission = decoded;
             }, () => {
                 if (admission)

package/docs/persistent-invitation-evidence.md

@@ -49,17 +49,50 @@ Unknown fields, non-data descriptors, custom prototypes, sparse arrays and
 noncanonical reload strings are refused. JavaScript proxies are outside this
 plain-data transport boundary; callers must not pass executable objects.
 
-Queries admit at most 64 delivered candidates, including invalid candidates and
-duplicates, with 16,384 UTF-8 bytes per canonical carrier and 262,144 UTF-8 bytes
-across all delivered canonical candidates. Work/bytes are charged before crypto;
-candidate 65 is refused before carrier copying. Retained evidence has the same
-limits. Event tags are bounded to 64 arrays of at most eight strings. These are
-evidence-profile limits, not new wire limits for the legacy API. Exact duplicates
-cost no additional retained capacity but consume query work and byte budget;
-the same ID with a different carrier fails the entire query. Capacity is checked
-before admitting another candidate, with no eviction or truncated success.
-Malformed/oversized object framing fails the query. Well-framed events that
-fail signature, capability or scope validation are ignored, never retained.
+Retained evidence holds at most 64 events, with 16,384 UTF-8 bytes per
+canonical carrier and 262,144 UTF-8 bytes across all retained carriers. Event
+tags are bounded to 64 arrays of at most eight strings. These are
+evidence-profile limits, not new wire limits for the legacy API.
+
+A query reads at most 512 deliveries
+(`MAX_PERSISTENT_INVITATION_EVIDENCE_DELIVERIES`): every relay's copy of every
+event, repeats, other authors and junk alike, each charged before it is parsed.
+Past that the query fails, because an event that could matter may be among
+those it did not read; delivery 513 is never inspected. The bound limits parse
+work only. It is eight times the retained limit so that 64 events heard from
+each of eight relays still fit.
+
+What is delivered is then sorted cheaply, before any signature check:
+
+- A malformed carrier (not plain data, a wrong type, bad hex), an event not by the inviter, not kind 1463
+  or 1461, or without exactly one `d` tag naming the invitation, is dropped.
+  It is not evidence and it does not fail the query.
+- An exact repeat, another carrier under an id already held, and a carrier
+  already checked and refused, are dropped. A held id was verified, so a second
+  carrier with it has the same signed fields.
+- An event in scope but over the carrier size limits (16,384 bytes, 64 tags,
+  eight strings in a tag) can never be retained. It is hashed and verified once,
+  charged to the signature bound below. If the authority signed it, the query
+  fails, because it may be a retirement or a newer list that no evidence can
+  hold. If not, it is dropped, and a repeat of it costs nothing.
+- Anything else in scope costs one signature check. A query is charged at most
+  128 (`MAX_PERSISTENT_INVITATION_EVIDENCE_VERIFICATIONS`): room for 64 retained
+  events and 64 more in-scope events that fail, forged or not a supported body.
+  The 129th is never checked and the query fails. The bound counts checks, not
+  Schnorr verifications. A retained retirement is verified twice, and the
+  finished query revalidates every event it kept, so a query that succeeds can
+  do up to 128 + 64 verifications. A forgery fails at its first, so a hostile
+  relay can cause at most 128.
+- A checked, valid authority event is retained. If that would be a 65th event
+  or pass 262,144 bytes, the query fails. Nothing is evicted or truncated.
+
+An in-scope, well-formed, validly signed authority event is never dropped, and
+neither is an over-limit one: each is retained or fails the query. What the
+query drops is what cannot be an authority event (malformed, out of scope,
+unsigned by the authority) or repeats what it already holds.
+`encodePersistentInvitation` refuses to sign an event over the size limits, so
+only another writer can produce one. The failures above reject with
+`PersistentInvitationEvidenceQueryError`.
 
 Evidence records, carrier strings and ID arrays are frozen owned copies.
 String memory is not claimed securely erased. Each admitted result has a fresh
@@ -102,8 +135,8 @@ custody and later independent revalidation.
 ## Completion and failure
 
 The query waits for the transport's EOSE even after an invitation or retirement
-arrives. Timeout, abort, subscription failure, contradictory duplicate or
-capacity failure rejects with `PersistentInvitationEvidenceQueryError`.
+arrives. Timeout, abort, subscription failure or a capacity failure (deliveries,
+signature checks, retained events or retained bytes) rejects with `PersistentInvitationEvidenceQueryError`.
 Its bounded `observation` is explicitly `completion: 'incomplete'`, diagnostic
 custody only. The revalidator always refuses incomplete observations. They
 cannot be relabelled to establish completeness; completion metadata itself is

package/docs/seal-key.md

@@ -121,8 +121,8 @@ it costs the epoch. So `oneTimeSender` stays off in every writer until readers
 have shipped on every client and had a release in the field. Off, every
 event is byte-identical to before.
 
-`hostRoomEpoch` has no switch for it yet; adding one is part of turning
-writers on, alongside the keeper's own rekeys.
+`hostRoomEpoch` takes `oneTimeSender` too and passes it to every grant it
+writes; it is off by default, like the encoders.
 
 ## Vectors
 

package/llms.txt

@@ -10,7 +10,7 @@ ESM-only, Node.js 22.13+. Four entry points: `@forgesworn/fold-kit` (circle prim
 npm install @forgesworn/fold-kit
 ```
 
-This file describes `main` (version 0.13.0), which can run ahead of the npm `latest` release; compare `npm view @forgesworn/fold-kit version` with the version of the API you need. To use an unreleased change, pin an immutable Git commit (a full SHA, for example from `git ls-remote https://github.com/forgesworn/fold-kit main`); the `prepare` script builds `dist/` on install:
+This file describes `main` (version 0.14.0), which can run ahead of the npm `latest` release; compare `npm view @forgesworn/fold-kit version` with the version of the API you need. To use an unreleased change, pin an immutable Git commit (a full SHA, for example from `git ls-remote https://github.com/forgesworn/fold-kit main`); the `prepare` script builds `dist/` on install:
 
 ```bash
 npm install "github:forgesworn/fold-kit#<commit>"
@@ -124,6 +124,7 @@ Invitation versions: v1 (`encodeJoinUrl`, the room secret in the link) is legacy
 - Same optional entry: `revalidatePersistentInvitationSource({ event, invitation, expectedRoomSecret })` independently authenticates one actual encoder Event or exact canonical stored carrier against a mandatory room-root pin. Returns a frozen `PersistentInvitationSource` with `version`, `invitationId`, `inviter`, `eventId`, `createdAt`, `event` string and owned `admission`. No completion/EOSE, publication, newest-selection, currentness or non-retirement claim. Rejects retirement, unsupported bodies/tags, forged signature caches, noncanonical strings and oversize before parsing/crypto. Creator clients retain exact event bytes and publication intent before pools; retry those bytes under fresh effect guards. Erase returned admission.secret after use.
 - Conference rooms: `encodePersistentInvitation({ ..., endsAt })` puts `ends` in the body and `['expiration', String(endsAt)]` on the 1463; `decodePersistentInvitation` returns `endsAt` and is null when an `expiration` tag disagrees with the body; `encodeInvitationRetirement({ ..., endsAt })` tags the 1461 the same way
 - Room relays: `encodePersistentInvitation({ ..., relays })` puts the room's own relays (1-8 distinct canonical `wss://host/` URLs, else it throws) in the body after `ends`; the decoder returns `relays` and is null on a malformed list; `requestPersistentRoomAdmission` keeps the newest signed copy's list (a copy without one says nothing); `isInvitationRelays`, `requireInvitationRelays`, `MAX_INVITATION_RELAYS` (8)
+- Room storage nodes: `encodePersistentInvitation({ ..., storage })` puts the room's group storage nodes (0-8 canonical base URLs on distinct hosts, e.g. `https://grove.example.net`; `http` only for `localhost`, `127.x.y.z` or an onion host; no default port, no trailing slash, no user info, query or fragment; else it throws) last in the body after `relays`, never a tag; `[]` means the authority withdrew every node, an absent key says nothing and leaves the body byte-identical to 0.13.0's. The decoder returns `storage` and `storageAt` (the `created_at` of the copy whose list stood) and is null on a malformed list; `requestPersistentRoomAdmission` and the strict evidence path keep the newest signed copy that names storage (a copy without the key says nothing), independently of `relays`; the strict path holds a same-second disagreement as `conflicting-storage` and `contributors.storage` names the copy that stood (present only when a copy names storage). `storageNodeFromBase(text)` → `{ base, server }` canonicalises an operator's URL (throws a message fit to show an operator); `storageNodeServer(base)` → the `server` (host) of a canonical base by grammar alone, `undefined` when not canonical, no URL parser; `isStorageNodeBase`, `isInvitationStorage`, `requireInvitationStorage`, `MAX_INVITATION_STORAGE_NODES` (8), `MAX_STORAGE_NODE_URL_LENGTH` (256). Vectors: `vectors/storage-vectors.json`
 - Self-destructing rooms (see `docs/room-destruct.md`): `encodePersistentInvitation({ ..., destruct: true })` puts `"destruct": true` in the encrypted body after `ends` (valid without `ends`), never a tag; `decodePersistentInvitation` returns `destruct: true` and is null when the field is present and not `true`; `requestPersistentRoomAdmission` keeps `destruct` if any valid copy carries it (sticky, like the earliest `ends`). `encodeInvitationRetirement({ ..., ended: true, destruct: true })` writes `{"v":1,"ended":true,"destruct":true}` (plain JSON, like `ended`) and throws on `destruct` without `ended`; `decodeInvitationRetirementNotice` returns `{ ended, destruct?: true }`, believing `destruct` only beside `ended`. `encodeRekeyEvent({ ..., closed: true, destruct: true })` writes it in the encrypted body after `closed` and throws without `closed`; `RekeyNotice.destruct` / `RekeyEvidence.destruct` are set only on a closing body, and a flag on an open rekey is dropped, not refused. Without the flag every event is byte-identical to 0.8.0, and a 0.8.0 reader ignores it
 - `withExpiration(tags, expiresAt?)` - NIP-40 rule for a room that ends: add the tag, keep an earlier one, lower a later one; `isRoomEnds`, `requireRoomEnds(endsAt, now)`, `MAX_ROOM_ENDS_SECONDS` (30 days)
 - Epoch encoders (`encodeRekeyEvent`, `encodeEpochRequest`, `encodeEpochGrant`) and `hostRoomEpoch` / `requestRoomEpoch` take `expiresAt?` for a conference room
@@ -139,7 +140,7 @@ Invitation versions: v1 (`encodeJoinUrl`, the room secret in the link) is legacy
 - Quiet replies (see `docs/quiet-replies.md`): `hostRoomEpoch` waits a random `replyDelayMs` (`[min, max]` ms, default `DEFAULT_REPLY_DELAY_MS` = `[500, 2000]`, `[0, 0]` answers at once) before every grant or refusal, deciding when the wait ends; closing cancels waits. A participant is sent `removed`/`closed` at most once per `refuseAgainAfter` seconds (default `REFUSE_AGAIN_AFTER_SECONDS` = 3600) and `unknown` once per `reportUnknownEvery` (60); at most `maxRefusalsPerMinute` refusals (default `MAX_REFUSALS_PER_MINUTE` = 20) go out in any minute in all. Grants are never limited. A suppressed refusal still calls `onRefused`/`onUnknown`; its asker times out with the plain error. `random` and `schedule` (`ReplySchedule`) are injectable. `RefusalLimiter` (bounded to `REFUSAL_LIMITER_CAPACITY` = 256 keys) and `replyDelay(range, random)` are exported. Events and vectors are unchanged
 - Member epoch catch-up (see `docs/member-epoch-catch-up.md`): `encodeRekeyEvent({ ..., commit: true })` writes `epochCommitment(roomId, epoch, secret)` into the rekey body; `hostMemberEpochDesk(opts)` lets any current member answer; `requestRoomEpoch({ ..., members: memberEpochSource(opts) })` asks the authority and members, first verifiable answer wins; `requestMemberEpoch(opts)` asks members alone. Kinds `MEMBER_EPOCH_KINDS` = `{ REQUEST: 20471, GRANT: 20472 }`. A member grant carries the authority-signed rekeys from the asker's epoch to the current one; the asker verifies the chain itself (`decodeMemberEpochGrant`) and refuses a last epoch with no commitment (legacy: authority only), a chain that removes it or closes the room, and one that stops short of `expected`. A verified grant is `{ epoch, removed, passed }`: `passed` holds the epochs between the asker's and `epoch`, oldest first, and `requestRoomEpoch` carries it as an optional `passed` when a member answered. Codecs: `encodeMemberEpochRequest`, `decodeMemberEpochRequest`, `encodeMemberEpochGrant`, `readRekeyEvidence`, `deriveMemberEpochRequestKey`, `MAX_MEMBER_EPOCH_CHAIN` (32)
 - The known-members gate (#207, see `docs/member-epoch-catch-up.md`): once a room has removed anybody (`removed()` not empty), `hostRoomEpoch` and `hostMemberEpochDesk` grant only to a participant for which `known(participant)` is true; anybody else is reported through `onUnknown` (once per participant, and again every `reportUnknownEvery` seconds, default `REPORT_UNKNOWN_EVERY_SECONDS` = 60, while they keep asking) and refused: the authority answers `refused: 'unknown'` (an `EpochRefusal`), a member stays silent. `unknown` is not final: `requestRoomEpoch` keeps asking, calls its `onUnknown` once, and rejects with `EpochRefusedError('unknown')` only at its timeout; a desk looks at the requester's next ask afresh, so letting somebody in is making `known` say yes. No `known` after a removal means nobody is known. Member lists: `encodeRekeyEvent({ members })` writes the authority's list (removed dropped, sorted) into the body, read back as `RekeyNotice.members` and `RekeyEvidence.members`, and as `MemberEpochGrant.members` (newest in the chain); `hostRoomEpoch({ members })` puts it in its grants (`EpochGrant.members`). `readMemberList(raw)` reads one, undefined when malformed. Without `members` and with no removal every event is byte-identical to 0.5.1
-- Seal keys (see `docs/seal-key.md`): `createDeviceCredential({ ..., seal })` appends `["seal", <x-only pubkey>]` last, under the participant's signature; mint a fresh one per credential with `generateSealKey()` and keep its secret as you keep the device key (old copies are sealed to old seal keys; healing needs only that each new one is fresh). `encodeRekeyEvent` recipients may be `{ device, credential }`; `encodeEpochGrant` and `encodeMemberEpochGrant` take `credential`; each copy is sealed to `sealTarget(device, credential)`: the credential's seal key, else the device key (never back to the device key because the credential lapsed). Readers take `sealSks` (`decodeRekeyEvent`, `decodeEpochGrant`, `decodeMemberEpochGrant`) or a `sealSks()` getter (`requestRoomEpoch`, `memberEpochSource`) and try them before the device key (`openSealed`); a rekey copy nothing opens reads as no copy. Desks take `credentialFor(device)`, the newest credential the room has seen (keep it monotone), and seal to the newer of that and the presented one (`sealCredential`, `newerCredential`: later expiration, then later created_at). `credentialSeal(c)` is the pubkey, undefined for none, null when doubled or off the curve (sealed to the device key). Without seal keys every event is byte-identical to 0.6.0 - One-time senders (see `docs/seal-key.md`, "One-time senders"): `encodeRekeyEvent` and `encodeEpochGrant` take `oneTimeSender: true`, sealing every copy from a fresh key named in one `["from", <x-only pubkey>]` tag (still authority-signed) and zeroing it, so a later copy of the authority key opens no past copy; readers open with `sealSender(event)` (the `from` key, else the signer; null when doubled or off the curve: a rekey reads without a secret, a grant is refused). Keep writers off until every client's readers have shipped; off, events are byte-identical to 0.12.0.
+- Seal keys (see `docs/seal-key.md`): `createDeviceCredential({ ..., seal })` appends `["seal", <x-only pubkey>]` last, under the participant's signature; mint a fresh one per credential with `generateSealKey()` and keep its secret as you keep the device key (old copies are sealed to old seal keys; healing needs only that each new one is fresh). `encodeRekeyEvent` recipients may be `{ device, credential }`; `encodeEpochGrant` and `encodeMemberEpochGrant` take `credential`; each copy is sealed to `sealTarget(device, credential)`: the credential's seal key, else the device key (never back to the device key because the credential lapsed). Readers take `sealSks` (`decodeRekeyEvent`, `decodeEpochGrant`, `decodeMemberEpochGrant`) or a `sealSks()` getter (`requestRoomEpoch`, `memberEpochSource`) and try them before the device key (`openSealed`); a rekey copy nothing opens reads as no copy. Desks take `credentialFor(device)`, the newest credential the room has seen (keep it monotone), and seal to the newer of that and the presented one (`sealCredential`, `newerCredential`: later expiration, then later created_at). `credentialSeal(c)` is the pubkey, undefined for none, null when doubled or off the curve (sealed to the device key). Without seal keys every event is byte-identical to 0.6.0 - One-time senders (see `docs/seal-key.md`, "One-time senders"): `encodeRekeyEvent` and `encodeEpochGrant` take `oneTimeSender: true`, sealing every copy from a fresh key named in one `["from", <x-only pubkey>]` tag (still authority-signed) and zeroing it, so a later copy of the authority key opens no past copy; readers open with `sealSender(event)` (the `from` key, else the signer; null when doubled or off the curve: a rekey reads without a secret, a grant is refused). `hostRoomEpoch({ oneTimeSender: true })` does the same for every grant the desk writes. Keep writers off until every client's readers have shipped; off, events are byte-identical to 0.12.0.
 - Scheduled rekeys and the history window (see `docs/scheduled-rekey.md`): `encodeRekeyEvent({ ..., scheduled: true })` writes `"scheduled": true` inside the encrypted body (never a tag), and throws beside a non-empty `removed` or `closed`; `decodeRekeyEvent` (`RekeyNotice.scheduled`) and `readRekeyEvidence` (`RekeyEvidence.scheduled`) report `true` only when `removed` is empty and the room is not closed, so a contradictory body is still announced. `HISTORY_WINDOW_SECONDS` (30 days) and `MAX_HISTORY_EPOCHS` (16); `epochsInWindow(left, now)` keeps entries with `leftAt >= now - HISTORY_WINDOW_SECONDS`, newest first by epoch, first of a doubled epoch, at most 16, never throws. `encodeEpochGrant({ ..., passed })` takes `LeftEpoch[]` (`{ epoch, secret, leftAt }`) and writes `passed: [{ epoch, secret (base64url), left }]` oldest first, only when non-empty; it throws on more than 16, epoch 0 (the room secret is never carried), an epoch not below the granted one, a doubled epoch, a non-32-byte secret or a bad `leftAt`. `hostRoomEpoch({ past })` is asked on every grant, filtered to what the encoder accepts and to `epochsInWindow`, so a bad `past()` costs the history, not the grant. `decodeEpochGrant` returns `EpochGrant.passed` (`leftAt` set) only when the list is exactly in that form, else drops the field and keeps the grant; `decodeMemberEpochGrant` sets `leftAt` on each passed epoch from the next rekey's `created_at`. `MAX_MEMBER_EPOCH_CHAIN` (32) is a different limit. Without the marker and `passed` every event is byte-identical to 0.7.0, and a 0.7.0 reader ignores both
 - `canonicalAdmins(admins)` / `signAdmins(opts)` / `verifyAdmins(opts)` - the authority's signed admin list
 - `canonicalChannels(channels)` / `signChannels(opts)` / `verifyChannels(opts)` - the authority's signed channel list; `CHANNEL_NAME`, `RESERVED_CHANNELS`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/fold-kit",
-  "version": "0.13.0",
+  "version": "0.14.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",
@@ -32,6 +32,7 @@
     "vectors/seal-vectors.json",
     "vectors/schedule-vectors.json",
     "vectors/destruct-vectors.json",
+    "vectors/storage-vectors.json",
     "LICENSE",
     "README.md",
     "llms.txt",
@@ -55,6 +56,7 @@
     "generate-seal": "node scripts/generate-seal.mjs",
     "generate-schedule": "node scripts/generate-schedule.mjs",
     "generate-destruct": "node scripts/generate-destruct.mjs",
+    "generate-storage": "node scripts/generate-storage.mjs",
     "bundle-check": "node scripts/bundle-check.mjs",
     "tarball-smoke": "node scripts/tarball-smoke.mjs",
     "vectors": "vitest run vectors/",