@forgesworn/fold-kit 0.12.0 → 0.14.0

package/dist/invitation-storage.js

@@ -0,0 +1,217 @@
+/**
+ * A room's own storage nodes, carried in its signed group invitation (kind 1463).
+ *
+ * A room that keeps its files on its own computers lists their base URLs
+ * here, so a client can upload to the group's own nodes instead of a public
+ * server. The list is signed by the room's authority and rides in the
+ * encrypted body, after `relays`; a body without it says nothing about
+ * storage.
+ *
+ * An entry is one string, a node's canonical base URL, and nothing else: the
+ * `server` a token names is its host, and scopes, ceilings and expiry belong
+ * to the grant. Canonical is defined by this grammar, not by what a URL parser
+ * prints, and the wire answer is the grammar's alone: no URL parser is
+ * consulted when a list is read or written, so a port written in another
+ * language gets the same answer from the same bytes. (`new URL` is used only
+ * to read an operator's text in `storageNodeFromBase`, whose output must
+ * itself pass the grammar.) A client that cannot parse a listed host when it
+ * makes a request skips that node.
+ *
+ *     entry   = scheme "://" host [ ":" port ] *( "/" segment )
+ *     scheme  = "https" / "http"
+ *     host    = label *( "." label )            ; 1 to 253 characters
+ *     label   = 1*63( a-z / 0-9 / "-" )         ; not starting or ending with "-"
+ *     port    = "1"-"9" *4DIGIT                 ; 1 to 65535, no leading zero
+ *     segment = 1*( A-Z / a-z / 0-9 / "." / "_" / "~" / "-" ) ; not "." or ".."
+ *
+ * and: at most 256 characters; `http` only for `localhost`, a loopback
+ * address `127.a.b.c` or an onion v3 host; no default port; a host whose last
+ * label is all digits or `0x` hex must be exactly four decimal octets with no
+ * leading zero; no trailing slash; no user info, query or fragment.
+ *
+ * The list is strict: 0 to `MAX_INVITATION_STORAGE_NODES` entries, no two on
+ * one host (grants are per host), order preserved and significant. `[]` means
+ * the authority withdrew every node. Anything else refuses the whole envelope.
+ */
+/** At most this many group storage nodes in a room's invitation. */
+export const MAX_INVITATION_STORAGE_NODES = 8;
+/** The longest canonical node base URL. */
+export const MAX_STORAGE_NODE_URL_LENGTH = 256;
+const MAX_HOST_LENGTH = 253;
+const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const PORT = /^[1-9][0-9]{0,4}$/;
+const SEGMENT = /^[A-Za-z0-9._~-]+$/;
+const OCTET = /^(?:0|[1-9][0-9]{0,2})$/;
+const HEX_LABEL = /^0x[0-9a-f]*$/;
+const DIGITS = /^[0-9]+$/;
+const LOOPBACK = /^127\.[0-9]+\.[0-9]+\.[0-9]+$/;
+const ONION_V3 = /^[a-z2-7]{56}\.onion$/;
+/** Entry as written: scheme, host characters, optional port, path segments. */
+const ENTRY = /^(https?):\/\/([a-z0-9.-]+)(?::([0-9]*))?((?:\/[^/]*)*)$/;
+/** A host the grammar allows, with the "ends in a number" rule applied. */
+function isCanonicalHost(host) {
+    if (host.length < 1 || host.length > MAX_HOST_LENGTH)
+        return false;
+    const labels = host.split('.');
+    if (!labels.every(label => LABEL.test(label)))
+        return false;
+    const last = labels[labels.length - 1];
+    if (DIGITS.test(last) || HEX_LABEL.test(last)) {
+        if (labels.length !== 4)
+            return false;
+        return labels.every(label => OCTET.test(label) && Number(label) <= 255);
+    }
+    return true;
+}
+/** True for a host that may be reached over plain http. */
+function isPlainHttpHost(host) {
+    return host === 'localhost' || LOOPBACK.test(host) || ONION_V3.test(host);
+}
+function isCanonicalPort(port) {
+    return PORT.test(port) && Number(port) <= 65_535;
+}
+function isCanonicalPath(path) {
+    if (path === '')
+        return true;
+    // Every segment is non-empty (so no trailing slash, no "//"), and neither "." nor "..".
+    return path.slice(1).split('/').every(segment => SEGMENT.test(segment) && segment !== '.' && segment !== '..');
+}
+/** The host of a canonical entry. Only for a value `isStorageNodeBase` accepted. */
+function hostOf(entry) {
+    return ENTRY.exec(entry)[2];
+}
+/** True when `value` is a canonical node base URL. Never throws. */
+export function isStorageNodeBase(value) {
+    if (typeof value !== 'string' || value.length > MAX_STORAGE_NODE_URL_LENGTH)
+        return false;
+    const m = ENTRY.exec(value);
+    if (!m)
+        return false;
+    const [, scheme, host, port, path] = m;
+    if (!isCanonicalHost(host) || !isCanonicalPath(path))
+        return false;
+    if (scheme === 'http' && !isPlainHttpHost(host))
+        return false;
+    if (port !== undefined) {
+        if (!isCanonicalPort(port))
+            return false;
+        if ((scheme === 'https' && port === '443') || (scheme === 'http' && port === '80'))
+            return false;
+    }
+    // The grammar alone decides. No URL parser is consulted, so every client
+    // gets the same answer from the same bytes (a parser's answer differs between
+    // runtimes, for `xn--` labels among others). A client that cannot parse a
+    // listed host when it makes a request skips that node.
+    return true;
+}
+/**
+ * The `server` a token names for a node: the host of a canonical base,
+ * exactly as written, or `undefined` when `base` is not canonical. Decided by
+ * the grammar alone, with no URL parser, so a client derives the same server
+ * from a listed base on every runtime. Never throws.
+ */
+export function storageNodeServer(base) {
+    return isStorageNodeBase(base) ? hostOf(base) : undefined;
+}
+/** True for a list the invitation may carry (0 to 8 canonical entries, one per host), including []. Never throws. */
+export function isInvitationStorage(value) {
+    if (!Array.isArray(value) || value.length > MAX_INVITATION_STORAGE_NODES)
+        return false;
+    // Hostile input may be sparse or hold holes: read by index, never by iterator.
+    const hosts = new Set();
+    for (let i = 0; i < value.length; i++) {
+        const entry = value[i];
+        if (!isStorageNodeBase(entry))
+            return false;
+        hosts.add(hostOf(entry));
+    }
+    return hosts.size === value.length;
+}
+/** Throws unless `nodes` is a list the invitation may carry; returns a copy. */
+export function requireInvitationStorage(nodes) {
+    if (!Array.isArray(nodes))
+        throw new Error('storage nodes must be a list');
+    if (nodes.length > MAX_INVITATION_STORAGE_NODES)
+        throw new Error(`a room can list at most ${MAX_INVITATION_STORAGE_NODES} storage nodes`);
+    const hosts = new Set();
+    for (let i = 0; i < nodes.length; i++) {
+        const entry = nodes[i];
+        if (!isStorageNodeBase(entry))
+            throw new Error(`storage nodes must be canonical node URLs (https, or http only on this machine): ${String(entry)}`);
+        const host = hostOf(entry);
+        if (hosts.has(host))
+            throw new Error(`storage nodes must not share a host name: ${host}`);
+        hosts.add(host);
+    }
+    return [...nodes];
+}
+function shorten(text) {
+    return text.length > 60 ? `${text.slice(0, 57)}...` : text;
+}
+/**
+ * The canonical form of an operator's URL, and its server. Lower-cases the
+ * scheme and host, drops a default port and trailing slashes, and throws a
+ * message fit to show an operator on anything the grammar refuses. It does not
+ * refuse onion hosts: a keeper that cannot reach one says so itself. Text that
+ * is already canonical is returned as it stands, without a URL parser.
+ */
+export function storageNodeFromBase(text) {
+    const shown = shorten(String(text));
+    const typed = String(text).trim();
+    const already = storageNodeServer(typed);
+    if (already !== undefined)
+        return { base: typed, server: already };
+    let url;
+    try {
+        url = new URL(typed);
+    }
+    catch {
+        throw new Error(`group node ${shown}: not a URL`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`group node ${shown}: only http and https nodes are supported in this version`);
+    }
+    // Read the pieces from the text as written, not from what the parser made of
+    // them: it would quietly mend `127.1`, `0x7f.0.0.1`, a dot segment or a
+    // percent-escape, and every one of those is refused here.
+    const m = /^(https?):\/\/([^/?#]*)([^?#]*)([?#].*)?$/i.exec(typed);
+    if (!m)
+        throw new Error(`group node ${shown}: not a URL`);
+    const scheme = m[1].toLowerCase();
+    const authority = m[2];
+    if (authority.includes('@'))
+        throw new Error('group node: a URL with a user name or password is refused');
+    if (m[4] !== undefined)
+        throw new Error('group node: a URL with a query or fragment is refused');
+    const colon = authority.lastIndexOf(':');
+    const bracketed = authority.startsWith('[');
+    const rawHost = colon === -1 || bracketed ? authority : authority.slice(0, colon);
+    const portText = colon === -1 || bracketed ? undefined : authority.slice(colon + 1);
+    // Lower-case ASCII only: a non-ASCII letter must not fold into a legal host.
+    const hostText = rawHost.replace(/[A-Z]/g, c => c.toLowerCase());
+    if (!isCanonicalHost(hostText)) {
+        throw new Error(`group node ${shown}: the host name must be lower-case letters, digits, hyphens and dots (no IPv6 literal, no trailing dot)`);
+    }
+    if (scheme === 'http' && !isPlainHttpHost(hostText)) {
+        throw new Error(`group node ${hostText}: plain http is only for a node on this machine (localhost or 127.x); use https so grants and revocations cannot be read or answered by somebody on the way`);
+    }
+    // A URL parser reads an empty port as the default and `08080` as 8080, so
+    // an operator's URL is mended the same way; only a port of 0 is newly refused.
+    const port = portText === undefined || portText === '' ? undefined : portText.replace(/^0+(?=[0-9])/, '');
+    if (port !== undefined && !isCanonicalPort(port)) {
+        throw new Error(`group node ${shown}: the port must be a number from 1 to 65535`);
+    }
+    const path = m[3].replace(/\/+$/, '');
+    if (!isCanonicalPath(path)) {
+        throw new Error(`group node ${shown}: the path may hold only letters, digits and . _ ~ - between slashes`);
+    }
+    const isDefaultPort = port !== undefined && ((scheme === 'https' && port === '443') || (scheme === 'http' && port === '80'));
+    const base = `${scheme}://${hostText}${port === undefined || isDefaultPort ? '' : `:${port}`}${path}`;
+    if (base.length > MAX_STORAGE_NODE_URL_LENGTH) {
+        throw new Error(`group node ${shown}: the URL is longer than ${MAX_STORAGE_NODE_URL_LENGTH} characters`);
+    }
+    const server = storageNodeServer(base);
+    if (server === undefined)
+        throw new Error(`group node ${shown}: not a canonical node URL`);
+    return { base, server };
+}

package/dist/persistent-invitation-evidence.d.ts

@@ -1,9 +1,29 @@
 import { type RoomInvitation } from './invitation.js';
 import { type PersistentRoomAdmission } from './persistent-invitation.js';
+import { MAX_PERSISTENT_INVITATION_EVENT_BYTES } from './evidence-carrier.js';
 import type { RelayTransport } from './transport.js';
 export declare const MAX_PERSISTENT_INVITATION_EVIDENCE_EVENTS = 64;
-export declare const MAX_PERSISTENT_INVITATION_EVENT_BYTES = 16384;
+export { MAX_PERSISTENT_INVITATION_EVENT_BYTES };
 export declare const MAX_PERSISTENT_INVITATION_EVIDENCE_BYTES = 262144;
+/** 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 declare 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 declare const MAX_PERSISTENT_INVITATION_EVIDENCE_VERIFICATIONS = 128;
 /** Protected, local observation metadata. EOSE is NOT evidence of relay
  * completeness, current membership or global absence of retirement.
  * `events` are canonical allowlisted Event carriers, not original wire JSON. */
@@ -20,6 +40,9 @@ export interface PersistentInvitationContributors {
     readonly ends: readonly string[];
     readonly destruct: readonly string[];
     readonly relays: readonly string[];
+    /** The copies whose list stood. Present exactly when a copy names storage,
+     *  so a room with none has the same contributors as 0.13.0 wrote. */
+    readonly storage?: readonly string[];
 }
 export type PersistentInvitationEvidenceOutcome = {
     readonly status: 'admitted';
@@ -28,7 +51,7 @@ export type PersistentInvitationEvidenceOutcome = {
     readonly contributors: PersistentInvitationContributors;
 } | {
     readonly status: 'held';
-    readonly reason: 'unavailable' | 'retired' | 'conflicting-rooms' | 'conflicting-relays' | 'wrong-room';
+    readonly reason: 'unavailable' | 'retired' | 'conflicting-rooms' | 'conflicting-relays' | 'conflicting-storage' | 'wrong-room';
     readonly retirementEventIds: readonly string[];
 };
 export interface PersistentInvitationEvidenceResult {

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)