@forgesworn/fold-kit 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,120 @@ 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
+
+- One-time senders for rekeys (1462) and authority grants (20469):
+  `oneTimeSender` on `encodeRekeyEvent` and `encodeEpochGrant` seals every
+  copy from a fresh key named in a `from` tag, so a later copy of the
+  authority's key no longer opens past copies. Off by default; off, events
+  are byte-identical to 0.12.0. Readers (`decodeRekeyEvent`,
+  `decodeEpochGrant`) open either form now, through the new `sealSender`
+  (also exported, with `SENDER_TAG`). Turn writers on only once these readers
+  have shipped everywhere. See docs/seal-key.md, "One-time senders"; vectors
+  in `seal-vectors.json`.
+
 ## 0.12.0
 
 ### Fixed

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.12.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
@@ -310,6 +330,11 @@ decision completes, so approval cannot extend an expired request's authority.
   `sealSks` on the readers; `credentialFor` on both desks;
   `credentialSeal`, `sealTarget`, `sealTo`, `openSealed`, `newerCredential`,
   `sealCredential`. Vectors: `vectors/seal-vectors.json`
+- One-time senders (`docs/seal-key.md`, "One-time senders"):
+  `oneTimeSender` on `encodeRekeyEvent` and `encodeEpochGrant` seals every
+  copy from a fresh key named in a `from` tag, so a later copy of the
+  authority's key opens no past copy; readers use `sealSender`. Off by
+  default until every client's readers have shipped.
 - Scheduled rekeys and the history window (`docs/scheduled-rekey.md`):
   `encodeRekeyEvent({ scheduled: true })` marks a turn of the key that
   removes nobody, read back as `RekeyNotice.scheduled` and
@@ -386,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

@@ -134,6 +134,13 @@ export interface EncodeRekeyOptions {
     /** A conference room's end, in unix seconds: the event carries it as a
      *  NIP-40 expiration (see `withExpiration`). Omit for a room with no end. */
     expiresAt?: number;
+    /** Seal the copies from a one-time key, named in a `from` tag and
+     *  discarded once they are sealed, instead of from the authority's key.
+     *  Readers from fold-kit 0.13.0 open either; an older reader opens no copy
+     *  from a one-time key, so turn this on only once readers have shipped
+     *  (docs/seal-key.md, "One-time senders"). Omitted, the event is
+     *  byte-identical to before. */
+    oneTimeSender?: boolean;
 }
 /** A rekey recipient: a device, and the newest credential the sender holds
  *  for it. */
@@ -330,6 +337,13 @@ export interface EncodeEpochGrantOptions {
     /** A conference room's end, in unix seconds: the event carries it as a
      *  NIP-40 expiration (see `withExpiration`). Omit for a room with no end. */
     expiresAt?: number;
+    /** Seal the copies from a one-time key, named in a `from` tag and
+     *  discarded once they are sealed, instead of from the authority's key.
+     *  Readers from fold-kit 0.13.0 open either; an older reader opens no copy
+     *  from a one-time key, so turn this on only once readers have shipped
+     *  (docs/seal-key.md, "One-time senders"). Omitted, the event is
+     *  byte-identical to before. */
+    oneTimeSender?: boolean;
 }
 /** Answer one request: the current epoch sealed to the asking device, or a
  *  refusal it alone can read. */
@@ -427,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

@@ -5,14 +5,14 @@ import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils';
 import { schnorr } from '@noble/curves/secp256k1.js';
 import { base64urlnopad } from '@scure/base';
 import { nip44 } from 'nostr-tools';
-import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
+import { finalizeEvent, generateSecretKey, getPublicKey } from 'nostr-tools/pure';
 import { hexEquals, normaliseHex } from './hex.js';
 import { KINDS } from './kinds.js';
 import { deriveRoom } from './room.js';
 import { verifyDeviceCredential } from './credential.js';
 import { evaluateAccess } from './access.js';
 import { verifyEventUncached } from './verify.js';
-import { newerCredential, openSealed, sealTo } from './seal.js';
+import { SENDER_TAG, newerCredential, openSealed, sealSender, sealTo } from './seal.js';
 import { withExpiration } from './expiration.js';
 import { epochCommitment } from './epoch-commit.js';
 import { DEFAULT_REPLY_DELAY_MS, REFUSE_AGAIN_AFTER_SECONDS, RefusalLimiter, defaultReplySchedule, replyDelay } from './quiet-reply.js';
@@ -135,6 +135,14 @@ function memberListOf(members, removed) {
         out.delete(normaliseHex(p));
     return [...out].sort();
 }
+/** The key a rekey or grant seals from: the authority's own, or, with
+ *  `oneTimeSender`, a fresh one named in a `from` tag and zeroed once used. */
+function oneTimeSenderOf(opts) {
+    if (!opts.oneTimeSender)
+        return { sk: opts.authoritySk, tags: [], discard: () => { } };
+    const sk = generateSecretKey();
+    return { sk, tags: [[SENDER_TAG, getPublicKey(sk)]], discard: () => sk.fill(0) };
+}
 /** Announce the next epoch. See the module comment for what this is. */
 export function encodeRekeyEvent(opts) {
     require32(opts.authoritySk, 'authority secret key');
@@ -151,10 +159,16 @@ export function encodeRekeyEvent(opts) {
     const keys = {};
     const sealed = { v: 1, secret: base64urlnopad.encode(opts.next.secret) };
     const plaintext = JSON.stringify(sealed);
-    for (const raw of opts.closed ? [] : opts.recipients) {
-        const recipient = typeof raw === 'string' ? { device: raw } : raw;
-        const device = requireHex32(recipient.device, 'recipient device');
-        keys[device] = sealTo(plaintext, opts.authoritySk, device, recipient.credential);
+    const sender = oneTimeSenderOf(opts);
+    try {
+        for (const raw of opts.closed ? [] : opts.recipients) {
+            const recipient = typeof raw === 'string' ? { device: raw } : raw;
+            const device = requireHex32(recipient.device, 'recipient device');
+            keys[device] = sealTo(plaintext, sender.sk, device, recipient.credential);
+        }
+    }
+    finally {
+        sender.discard();
     }
     const body = {
         v: 1,
@@ -174,6 +188,7 @@ export function encodeRekeyEvent(opts) {
         tags: withExpiration([
             ['d', roomId],
             ['epoch', String(epoch)],
+            ...sender.tags,
         ], opts.expiresAt),
         content: nip44.v2.encrypt(JSON.stringify(body), opts.current.key),
     }, opts.authoritySk);
@@ -239,13 +254,14 @@ export function decodeRekeyEvent(event, opts) {
             notice.members = members;
         const device = getPublicKey(opts.deviceSk);
         const mine = Object.entries(body.keys).find(([to]) => hexEquals(to, device))?.[1];
-        if (typeof mine === 'string') {
+        const sender = sealSender(event);
+        if (typeof mine === 'string' && sender !== null) {
             // A copy none of this device's keys opens is no copy: sealed to a
             // seal key it has since erased, or one it never had. The rest of the
             // rekey still says who was removed, so it is read without the secret,
             // and the device asks for the epoch.
             try {
-                const sealed = JSON.parse(openSealed(mine, event.pubkey, opts.deviceSk, opts.sealSks));
+                const sealed = JSON.parse(openSealed(mine, sender, opts.deviceSk, opts.sealSks));
                 if (sealed.v === 1 && typeof sealed.secret === 'string') {
                     const secret = base64urlnopad.decode(sealed.secret);
                     if (secret.length === 32)
@@ -506,14 +522,23 @@ export function encodeEpochGrant(opts) {
         if (opts.passed !== undefined && opts.passed.length > 0)
             body.passed = passedListOf(opts.passed, body.epoch);
     }
+    const sender = oneTimeSenderOf(opts);
+    let content;
+    try {
+        content = sealTo(JSON.stringify(body), sender.sk, device, opts.credential);
+    }
+    finally {
+        sender.discard();
+    }
     return finalizeEvent({
         kind: KINDS.EPOCH_GRANT,
         created_at: opts.now,
         tags: withExpiration([
             ['d', roomId],
             ['p', device],
+            ...sender.tags,
         ], opts.expiresAt),
-        content: sealTo(JSON.stringify(body), opts.authoritySk, device, opts.credential),
+        content,
     }, opts.authoritySk);
 }
 /** Read the authority's answer to this device's own request. Null for
@@ -535,7 +560,10 @@ export function decodeEpochGrant(event, opts) {
         const addressed = event.tags.find((t) => t[0] === 'p')?.[1];
         if (addressed === undefined || !hexEquals(addressed, device))
             return null;
-        const body = JSON.parse(openSealed(event.content, event.pubkey, opts.deviceSk, opts.sealSks));
+        const sender = sealSender(event);
+        if (sender === null)
+            return null;
+        const body = JSON.parse(openSealed(event.content, sender, opts.deviceSk, opts.sealSks));
         if (body.v !== 1 || typeof body.request !== 'string' || !hexEquals(body.request, opts.request))
             return null;
         if (body.refused === 'removed' || body.refused === 'closed' || body.refused === 'unknown')
@@ -706,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 {
@@ -722,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

@@ -7,7 +7,7 @@ export type { DeviceCredential, AccessTier, AgentRule, RoomPolicy, KindredProof
 export type { RelayTransport } from './transport.js';
 export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
 export type { CreateCredentialOptions, VerifyResult } from './credential.js';
-export { SEAL_TAG, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
+export { SEAL_TAG, SENDER_TAG, sealSender, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
 export type { SealKey } from './seal.js';
 export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
 export type { ScopedKeys } from './scoped.js';
@@ -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

@@ -5,7 +5,7 @@ export { verifyEventUncached, boundedEventVerifier } from './verify.js';
 export { localIdentity } from './identity.js';
 export { KINDS } from './kinds.js';
 export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
-export { SEAL_TAG, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
+export { SEAL_TAG, SENDER_TAG, sealSender, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
 export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
 export { createSubKeyCertificate, verifySubKeyCertificate, SUB_KEY_CERTIFICATE_SCOPE, } from './sub-cert.js';
 export { generateRoomSecret, deriveRoom, encodeJoinUrl, decodeJoinUrl, parseRoomPolicy, ROOM_LABELS, } from './room.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;