@forgesworn/fold-kit 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,106 @@ This kit is pre-1.0 (see AGENTS.md "Release Notes"); a behaviour change on
 byte-identical copy of a KithMoot function (see EXTRACTION.md) and this is
 the one place its behaviour has deliberately diverged.
 
+## 0.14.0
+
+### Added
+
+- Room storage nodes: the group storage nodes a room keeps its files on,
+  carried in its signed group invitation (kind 1463) so a client uploads to
+  the group's own nodes instead of a public server.
+  `encodePersistentInvitation` takes an optional `storage`: zero to eight
+  canonical node base URLs on distinct hosts, else it throws. The encrypted v3
+  body carries them last, after `relays` (key order `v, room, secret, ends,
+  destruct, relays, storage`; the version stays 3, so every lenient reader,
+  including shipped Android, ignores the key). `[]` says the room's authority
+  withdrew every node; a body without the key says nothing about nodes.
+  With no `storage`, the event is byte-identical to 0.13.0's.
+- An entry is a base URL and nothing else. Canonical is a grammar, pinned by
+  `vectors/storage-vectors.json`: `https`, or `http` only for `localhost`, a
+  `127.x.y.z` address or an onion v3 host; lower-case host; no default port,
+  trailing slash, user info, query or fragment; at most 256 characters; a host
+  ending in a number must be four plain decimal octets. The grammar alone
+  decides on the wire: no URL parser is consulted, so every client gets the
+  same answer, `xn--` labels included (valid Punycode or not). New exports:
+  `storageNodeFromBase` (an operator's URL to `{ base, server }`),
+  `storageNodeServer` (the `server` of a canonical base, by grammar alone, for
+  a client that must not need a URL parser), `isStorageNodeBase`, `isInvitationStorage`, `requireInvitationStorage`,
+  `MAX_INVITATION_STORAGE_NODES` (8), `MAX_STORAGE_NODE_URL_LENGTH` (256) and
+  the `StorageNode` type.
+- `decodePersistentInvitation` returns `storage` and `storageAt` (the
+  `created_at` of the copy whose list stood; a client uses it as the record's
+  version), and returns null for the whole envelope on a malformed list.
+  `requestPersistentRoomAdmission` keeps the list of the newest signed copy
+  that names any, `[]` included; a copy without the key says nothing, and on
+  equal timestamps the first heard stays. Relays and storage merge
+  independently.
+- The strict evidence path (`persistent-invitation-evidence`) accepts the new
+  key and merges it the same way. Two newest copies of one second that
+  disagree hold with the new reason `conflicting-storage`, and
+  `PersistentInvitationContributors` gains an optional `storage`, present
+  exactly when a copy names storage, so a room with none has contributors
+  byte-identical to 0.13.0's and a stored proof still reads back unchanged.
+  Compatibility with 0.13.0 strict readers is only partial. A live query on
+  0.13.0 skips a copy it does not know, so with a plain copy beside it the room
+  still admits (the vector `storage-strict-old-reader`), and with only a
+  storage copy it reads as unavailable. But evidence that 0.14.0 retained
+  holds every valid copy, the storage copy included, and 0.13.0's
+  `revalidatePersistentInvitationEvidence` throws on a carrier it cannot read,
+  plain copy or not. So evidence stored by 0.14.0 cannot be read by 0.13.0: a
+  stale tab, a cached older bundle or a rollback meets it. Keep older readers
+  off evidence a newer version stored, or isolate each read failure.
+- `vectors/storage-vectors.json` (`npm run generate-storage`).
+- `hostRoomEpoch` takes `oneTimeSender`, passed to every grant the desk
+  writes. Off by default; off, every grant is byte-identical to 0.13.0's.
+
+### Fixed
+
+- `requestPersistentRoomAdmissionEvidence` no longer fails a room on repeats,
+  strangers or junk. It charged every delivered event, before de-duplicating
+  and before checking the author, kind and `d` tag, against the 64 retained
+  events and 256 KiB, and one malformed or oversized event failed the whole
+  query. A room on four relays whose keeper had republished 17 times failed to
+  load, and any relay could fail a query with one oversized event or 64 events
+  of another author. Now a delivery is only counted against a new bound,
+  `MAX_PERSISTENT_INVITATION_EVIDENCE_DELIVERIES` (512, which bounds parse
+  work). An event that is malformed, or out of scope (not the inviter, not
+  kind 1463 or 1461, not exactly one `d` tag naming the invitation), is dropped
+  without crypto, as is an exact repeat or another carrier under an id already
+  held (the held event was verified, so its signed fields are the same).
+  Signature checks have their own bound,
+  `MAX_PERSISTENT_INVITATION_EVIDENCE_VERIFICATIONS` (128: 64 retained events
+  plus 64 in-scope events that fail). Those are checks charged, not Schnorr
+  verifications: a retained retirement is verified twice and the finished query
+  revalidates what it kept, so a query that succeeds can do up to 128 + 64,
+  while a hostile relay can cause at most 128. Nothing is truncated: a 65th
+  unique valid authority event, 256 KiB of retained carriers, more than 512
+  deliveries or more than 128 signature checks still fail the query.
+- An in-scope event over the evidence size limits (16,384 bytes, 64 tags, eight
+  strings in a tag) can never be retained, so it is checked rather than
+  dropped unseen: one hash and one signature check, charged to the same bound
+  of 128. If the authority signed it, the query fails with `invitation evidence
+  query refused an event signed by the authority that exceeds the evidence size
+  limits`, because it may be a retirement or a newer list the query cannot
+  hold. If it only claims the authority's key it is dropped, and a repeat costs
+  nothing. Before this fix such an event also failed the query, as any
+  oversized event did; failing only for the authority's own is the change.
+- Error messages. Gone from this query: `conflicting duplicate invitation event
+  identity` (a second carrier under a held id is now dropped, since the held
+  one was verified), and the carrier errors `oversized evidence event`,
+  `invalid or oversized evidence event`, `invalid or oversized evidence tag`,
+  `invalid evidence field`, `invalid evidence record` and the like (a malformed
+  delivery is now dropped). New: `invitation evidence query capacity exceeded:
+  too many deliveries`, `...: too many signature checks` and the size-limit
+  refusal above. Unchanged: `invitation evidence query capacity exceeded` for a
+  retained-event or retained-byte overflow. The revalidators still throw the
+  carrier errors, and the evidence format and its limits are unchanged, so
+  stored evidence revalidates exactly as before.
+- `encodePersistentInvitation` throws when the event it would sign exceeds
+  those size limits (only possible with very long relay URLs: 27,813 bytes at
+  eight 2,048-character relays), so the authority cannot sign what the strict
+  reader must refuse. `encodeInvitationRetirement` is unchanged: its body and
+  tags are fixed and small, so it cannot exceed them.
+
 ## 0.13.0
 
 ### Added

package/EXTRACTION.md

@@ -330,6 +330,28 @@ declares each added line in `ROOM_RELAY_CHANGES` as 0.4.0 text against
 0.3.0 text, applied before `CONFERENCE_CHANGES`, so the whole-file
 comparison against the pinned commit still holds.
 
+## Room storage nodes: declared additions to `persistent-invitation.ts`
+
+0.14.0 adds the room's group storage nodes to the group invitation body,
+after `relays`: the base URLs of the nodes a room keeps its files on, so a
+client can upload to the group's own nodes instead of a public server. The
+rule (0 to 8 canonical node URLs on distinct hosts, defined by a grammar
+rather than by what a URL parser prints, and decided by the grammar alone on
+the wire) lives in a new module, `src/invitation-storage.ts`,
+which moved from nowhere; `storageNodeServer` there gives the `server` of a
+canonical base by grammar alone, for clients that must not need a URL parser.
+With no `storage` the body, and the whole event, is
+byte-identical to 0.13.0's (`vectors/storage-vectors.json`, vector
+`storage-absent`, pins two events recorded from 0.13.0's own encoder). The
+admission gains `storage` and `storageAt`; the strict evidence path
+(`src/persistent-invitation-evidence.ts`, not a moved module) allows the key
+and merges it as it merges `relays`, holding a same-second disagreement as
+`conflicting-storage`; its `contributors.storage` is present only when a copy
+names storage, so contributors without one match 0.13.0's byte for byte. `scripts/diff-source.mjs` declares each added line in
+`STORAGE_CHANGES` as 0.14.0 text against 0.13.0 text, applied before every
+other change set, so the whole-file comparison against the pinned commit
+still holds.
+
 ## Member epoch catch-up: declared additions to `epoch.ts`
 
 Unreleased. Any current member can now hand an admitted, non-removed device

package/README.md

@@ -13,7 +13,7 @@ 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:** Version 0.13.0 on `main`. Published on npm as
+**Status:** Version 0.14.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
@@ -250,6 +250,26 @@ decision completes, so approval cannot extend an expired request's authority.
   `requestPersistentRoomAdmission` keeps the relays of the newest signed
   copy that names any. `isInvitationRelays`, `requireInvitationRelays` and
   `MAX_INVITATION_RELAYS` are the rule
+- Room storage nodes: pass `storage` (zero to eight canonical node base URLs
+  on distinct hosts, e.g. `https://grove.example.net` or
+  `http://127.0.0.1:8080`) and the encrypted body carries them last, after
+  `relays`, so a room that keeps its files on its own computers says where.
+  An entry is only a base URL; the grammar (no trailing slash, no default
+  port, `http` only on this machine or an onion address) is in
+  `src/invitation-storage.ts` and pinned by vectors; no URL parser is
+  consulted, so every client gets the same answer. `[]` says the authority withdrew every node; a body with no
+  `storage` says nothing about nodes, and is byte-identical to 0.13.0's. The
+  decoder returns `storage` and `storageAt` (the `created_at` of the copy
+  whose list stood) and refuses the whole envelope on a malformed list.
+  `requestPersistentRoomAdmission` and the strict evidence path keep the list
+  of the newest signed copy that names any, independently of the relays; the
+  strict path holds a same-second disagreement as `conflicting-storage`.
+  `storageNodeFromBase(text)` canonicalises an operator's URL and gives its
+  `server`; `storageNodeServer(base)` gives the `server` of a canonical base by
+  grammar alone (`undefined` when not canonical); `isStorageNodeBase`, `isInvitationStorage`,
+  `requireInvitationStorage`, `MAX_INVITATION_STORAGE_NODES` and
+  `MAX_STORAGE_NODE_URL_LENGTH` are the rule. Vectors:
+  `vectors/storage-vectors.json`
 - Self-destructing rooms (`docs/room-destruct.md`): pass `destruct: true`
   and the encrypted body carries it after `ends` (no end needed: the room
   then self-destructs when its authority closes it). The decoder returns
@@ -391,6 +411,7 @@ npm run typecheck    # type-check src/ and test/ (matching KithMoot, vectors/ is
 npm run vectors      # run only the vector-verification suites
 npm run diff-source  # compare moved modules against the pinned source commit (needs FOLD_KIT_SOURCE_DIR)
 npm run generate-fold # regenerate vectors/fold-vectors.json (needs a prior build)
+npm run generate-storage # regenerate vectors/storage-vectors.json (needs a prior build)
 npm run bundle-check # esbuild browser bundle check (needs a prior build)
 npm run check        # typecheck + test + diff-source
 ```

package/dist/epoch.d.ts

@@ -441,6 +441,10 @@ export interface HostRoomEpochOptions {
     onRefused?: (request: EpochRequest, why: EpochRefusal) => void;
     /** A conference room's end: every grant carries it as an expiration. */
     expiresAt?: number;
+    /** Seal every grant from a one-time key (`EncodeEpochGrantOptions.oneTimeSender`).
+     *  Off by default; turn it on only once every client reads one-time
+     *  senders (fold-kit 0.13.0 and the clients built on it). */
+    oneTimeSender?: boolean;
     /** 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. */

package/dist/epoch.js

@@ -734,6 +734,7 @@ export function hostRoomEpoch(opts) {
                             refused,
                             credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
                             expiresAt: opts.expiresAt,
+                            ...(opts.oneTimeSender ? { oneTimeSender: true } : {}),
                         });
                     }
                     else {
@@ -750,6 +751,7 @@ export function hostRoomEpoch(opts) {
                             ...(opts.past ? { passed: passedFor(opts.past, epoch.epoch, now()) } : {}),
                             credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
                             expiresAt: opts.expiresAt,
+                            ...(opts.oneTimeSender ? { oneTimeSender: true } : {}),
                         });
                     }
                 }

package/dist/evidence-carrier.d.ts

@@ -0,0 +1,10 @@
+import type { Event } from 'nostr-tools/pure';
+/** Per-event ceiling of the strict evidence carrier, in canonical UTF-8 bytes. */
+export declare const MAX_PERSISTENT_INVITATION_EVENT_BYTES = 16384;
+/** Tag arrays a strict evidence carrier may hold, and strings in each. */
+export declare const MAX_EVIDENCE_CARRIER_TAGS = 64;
+export declare const MAX_EVIDENCE_CARRIER_TAG_STRINGS = 8;
+/** Returns `event` if the strict evidence reader could retain it, else throws.
+ * A writer calls this before it signs and publishes, so the authority never
+ * signs what a strict reader must refuse. */
+export declare function requireEvidenceCarrierLimits(event: Event, what: string): Event;

package/dist/evidence-carrier.js

@@ -0,0 +1,19 @@
+/** Per-event ceiling of the strict evidence carrier, in canonical UTF-8 bytes. */
+export const MAX_PERSISTENT_INVITATION_EVENT_BYTES = 16_384;
+/** Tag arrays a strict evidence carrier may hold, and strings in each. */
+export const MAX_EVIDENCE_CARRIER_TAGS = 64;
+export const MAX_EVIDENCE_CARRIER_TAG_STRINGS = 8;
+/** Returns `event` if the strict evidence reader could retain it, else throws.
+ * A writer calls this before it signs and publishes, so the authority never
+ * signs what a strict reader must refuse. */
+export function requireEvidenceCarrierLimits(event, what) {
+    const bytes = new TextEncoder().encode(JSON.stringify({ id: event.id, pubkey: event.pubkey, created_at: event.created_at,
+        kind: event.kind, tags: event.tags, content: event.content, sig: event.sig })).length;
+    if (bytes > MAX_PERSISTENT_INVITATION_EVENT_BYTES) {
+        throw new Error(`the ${what} is ${bytes} bytes, over the ${MAX_PERSISTENT_INVITATION_EVENT_BYTES} a strict reader accepts; use fewer or shorter relays or storage nodes`);
+    }
+    if (event.tags.length > MAX_EVIDENCE_CARRIER_TAGS || event.tags.some(tag => tag.length > MAX_EVIDENCE_CARRIER_TAG_STRINGS)) {
+        throw new Error(`the ${what} has more tags, or more strings in a tag, than a strict reader accepts`);
+    }
+    return event;
+}

package/dist/index.d.ts

@@ -26,6 +26,8 @@ export { encodePersistentInvitation, decodePersistentInvitation, requestPersiste
 export type { PersistentRoomAdmission } 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 { isStorageNodeBase, storageNodeFromBase, storageNodeServer, isInvitationStorage, requireInvitationStorage, MAX_INVITATION_STORAGE_NODES, MAX_STORAGE_NODE_URL_LENGTH, } from './invitation-storage.js';
+export type { StorageNode } from './invitation-storage.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
 export type { RoomLink } from './link.js';
 export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, 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';

package/dist/index.js

@@ -17,6 +17,7 @@ export { encodeInvitationDecline, decodeInvitationDecline, InvitationDeclinedErr
 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 { isStorageNodeBase, storageNodeFromBase, storageNodeServer, isInvitationStorage, requireInvitationStorage, MAX_INVITATION_STORAGE_NODES, MAX_STORAGE_NODE_URL_LENGTH, } from './invitation-storage.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';

package/dist/invitation-storage.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 declare const MAX_INVITATION_STORAGE_NODES = 8;
+/** The longest canonical node base URL. */
+export declare const MAX_STORAGE_NODE_URL_LENGTH = 256;
+/** A canonical node base URL and the `server` tag it implies (its host). */
+export interface StorageNode {
+    base: string;
+    server: string;
+}
+/** True when `value` is a canonical node base URL. Never throws. */
+export declare function isStorageNodeBase(value: unknown): value is string;
+/**
+ * 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 declare function storageNodeServer(base: string): string | undefined;
+/** True for a list the invitation may carry (0 to 8 canonical entries, one per host), including []. Never throws. */
+export declare function isInvitationStorage(value: unknown): value is string[];
+/** Throws unless `nodes` is a list the invitation may carry; returns a copy. */
+export declare function requireInvitationStorage(nodes: readonly string[]): string[];
+/**
+ * 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 declare function storageNodeFromBase(text: string): StorageNode;

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 {