@forgesworn/fold-kit 0.3.0 → 0.4.0

package/README.md

@@ -118,6 +118,14 @@ the rest).
   conference room: the encrypted body carries `ends` and the event a NIP-40
   `expiration` tag, so relays drop it when the room ends; the decoder returns
   `endsAt` and refuses a tag that disagrees with the body
+- Room relays: pass `relays` (one to eight distinct safe relay URLs in
+  canonical `normalizeURL` form, e.g. `wss://relay.example.com/`) and the
+  encrypted body carries them after `ends`. Every member's pool includes
+  them, so members never land on disjoint relays. The decoder returns
+  `relays` and refuses the whole envelope on a malformed list;
+  `requestPersistentRoomAdmission` keeps the relays of the newest signed
+  copy that names any. `isInvitationRelays`, `requireInvitationRelays` and
+  `MAX_INVITATION_RELAYS` are the rule
 - `withExpiration`, `isRoomEnds`, `requireRoomEnds`, `MAX_ROOM_ENDS_SECONDS` -
   the conference-room expiration rule: add the end as an `expiration` tag,
   keep an earlier one, lower a later one. `encodeInvitationRetirement` takes

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export type { RoomInvitation, RoomInvitationHost, InvitationDelegation, RoomInvi
 export { encodePersistentInvitation, decodePersistentInvitation, requestPersistentRoomAdmission, PERSISTENT_INVITATION_LABELS, } from './persistent-invitation.js';
 export type { PersistentRoomAdmission } from './persistent-invitation.js';
 export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } from './expiration.js';
+export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.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, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export { issueKindredProof, evaluateAccess, ACCESS_LABELS, } from './access.js';
 export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
 export { encodePersistentInvitation, decodePersistentInvitation, requestPersistentRoomAdmission, PERSISTENT_INVITATION_LABELS, } from './persistent-invitation.js';
 export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } from './expiration.js';
+export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
 export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
 export { deriveChannel, CHANNEL_ID_INFO, CHANNEL_KEY_INFO, MAX_CHANNEL_NAME_LENGTH, CHANNEL_LABELS } from './channel.js';

package/dist/invitation-relays.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A room's own relays, carried in its signed group invitation (kind 1463).
+ *
+ * The relays a room is created on are its meeting place: every member's pool
+ * includes them, whatever else that member uses, so two members can never
+ * end up on disjoint relays. A link's relay hints are unsigned and drift as
+ * links are re-shared; the invitation's list is signed by the inviter, so a
+ * stale bookmark converges on it.
+ *
+ * The list is strict: one to `MAX_INVITATION_RELAYS` distinct URLs, each a
+ * safe relay URL already in canonical form (`normalizeURL` from
+ * `nostr-tools/utils`: lower-case host, no default port, no trailing slash
+ * except the root's, sorted query), with no credentials. Anything else
+ * refuses the whole envelope; a list is never silently trimmed.
+ */
+/** At most this many room relays: the same bound as a link's relay hints. */
+export declare const MAX_INVITATION_RELAYS = 8;
+/** True for a list of room relays the invitation may carry. Never throws. */
+export declare function isInvitationRelays(value: unknown): value is string[];
+/** Throws unless `relays` is a list the invitation may carry; returns a copy. */
+export declare function requireInvitationRelays(relays: readonly string[]): string[];

package/dist/invitation-relays.js

@@ -0,0 +1,52 @@
+import { normalizeURL } from 'nostr-tools/utils';
+import { isSafeRelayUrl, MAX_RELAY_HINTS } from './network-hints.js';
+/**
+ * A room's own relays, carried in its signed group invitation (kind 1463).
+ *
+ * The relays a room is created on are its meeting place: every member's pool
+ * includes them, whatever else that member uses, so two members can never
+ * end up on disjoint relays. A link's relay hints are unsigned and drift as
+ * links are re-shared; the invitation's list is signed by the inviter, so a
+ * stale bookmark converges on it.
+ *
+ * The list is strict: one to `MAX_INVITATION_RELAYS` distinct URLs, each a
+ * safe relay URL already in canonical form (`normalizeURL` from
+ * `nostr-tools/utils`: lower-case host, no default port, no trailing slash
+ * except the root's, sorted query), with no credentials. Anything else
+ * refuses the whole envelope; a list is never silently trimmed.
+ */
+/** At most this many room relays: the same bound as a link's relay hints. */
+export const MAX_INVITATION_RELAYS = MAX_RELAY_HINTS;
+function isCanonicalRelayUrl(value) {
+    if (typeof value !== 'string' || !isSafeRelayUrl(value))
+        return false;
+    try {
+        const parsed = new URL(value);
+        if (parsed.username || parsed.password)
+            return false;
+        return normalizeURL(value) === value;
+    }
+    catch {
+        return false;
+    }
+}
+/** True for a list of room relays the invitation may carry. Never throws. */
+export function isInvitationRelays(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_INVITATION_RELAYS)
+        return false;
+    return value.every(isCanonicalRelayUrl) && new Set(value).size === value.length;
+}
+/** Throws unless `relays` is a list the invitation may carry; returns a copy. */
+export function requireInvitationRelays(relays) {
+    if (!Array.isArray(relays) || relays.length === 0)
+        throw new Error('a room relay list needs at least one relay');
+    if (relays.length > MAX_INVITATION_RELAYS)
+        throw new Error(`a room can list at most ${MAX_INVITATION_RELAYS} relays`);
+    for (const url of relays) {
+        if (!isCanonicalRelayUrl(url))
+            throw new Error(`room relays must be wss:// URLs (ws:// only on localhost) in canonical form, without credentials: ${String(url)}`);
+    }
+    if (new Set(relays).size !== relays.length)
+        throw new Error('room relays must not repeat');
+    return [...relays];
+}

package/dist/persistent-invitation.d.ts

@@ -10,6 +10,9 @@ export interface PersistentRoomAdmission {
     /** When the room ends, in unix seconds: a conference room. Absent for a
      *  group that runs until somebody ends it. */
     endsAt?: number;
+    /** The room's own relays, as its inviter signed them: every member's pool
+     *  includes them. Absent from an invitation written before 0.4.0. */
+    relays?: string[];
 }
 /** Publish once before sharing. The link plus this envelope is a durable
  * bearer capability: anybody holding both can learn epoch 0. Retirement
@@ -23,6 +26,10 @@ export declare function encodePersistentInvitation(opts: {
      *  30 days beyond it. Carried in the body and as a NIP-40 expiration, so
      *  relays drop the invitation when the room ends. */
     endsAt?: number;
+    /** The room's own relays: one to eight distinct safe URLs in canonical
+     *  form (see `isInvitationRelays`), else it throws. Omitted, the body is
+     *  byte-identical to 0.3.0's. */
+    relays?: readonly string[];
 }): Event;
 export declare function decodePersistentInvitation(event: Event, invitation: RoomInvitation): PersistentRoomAdmission | null;
 /** Fetch the signed envelope and retirement in ONE stored-event query.

package/dist/persistent-invitation.js

@@ -8,6 +8,7 @@ import { KINDS } from './kinds.js';
 import { deriveRoom } from './room.js';
 import { verifyEventUncached } from './verify.js';
 import { isRoomEnds, requireRoomEnds } from './expiration.js';
+import { isInvitationRelays, requireInvitationRelays } from './invitation-relays.js';
 function welcomeKey(invitation) {
     if (!invitation.persistent)
         throw new Error('a persistent group invitation is required');
@@ -23,12 +24,13 @@ export function encodePersistentInvitation(opts) {
         throw new Error('only the inviter can publish a group invitation');
     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({
         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 }),
+            v: 3, room, secret: base64urlnopad.encode(opts.roomSecret), ...(ends === undefined ? {} : { ends }), ...(relays === undefined ? {} : { relays }),
         }), welcomeKey(opts.invitation)),
     }, opts.inviterSk);
 }
@@ -56,7 +58,14 @@ export function decodePersistentInvitation(event, invitation) {
             return null;
         if (expirations.length === 1 && (ends === undefined || expirations[0][1] !== String(ends)))
             return null;
-        return ends === undefined ? { secret, persistent: true, epoch: 0 } : { secret, persistent: true, epoch: 0, endsAt: ends };
+        // The room's relays, when the body names them, must be a list the encoder
+        // would write; a malformed one refuses the envelope rather than half of it.
+        if (body.relays !== undefined && !isInvitationRelays(body.relays))
+            return null;
+        const admission = ends === undefined ? { secret, persistent: true, epoch: 0 } : { secret, persistent: true, epoch: 0, endsAt: ends };
+        if (body.relays !== undefined)
+            admission.relays = [...body.relays];
+        return admission;
     }
     catch {
         return null;
@@ -73,6 +82,7 @@ export function requestPersistentRoomAdmission(opts) {
     return new Promise((resolve, reject) => {
         let settled = false;
         let admission;
+        let relaysAt = -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) {
@@ -109,6 +119,13 @@ export function requestPersistentRoomAdmission(opts) {
                 // end stands, so a stale copy can never keep a room open longer.
                 if (admission?.endsAt !== undefined && (decoded.endsAt === undefined || decoded.endsAt > admission.endsAt))
                     decoded.endsAt = admission.endsAt;
+                // Two signed copies that disagree on the room's relays: the newest
+                // copy that names any stands. A copy naming none (an older writer)
+                // says nothing about them, and on equal timestamps the first heard stays.
+                if (decoded.relays !== undefined && event.created_at > relaysAt)
+                    relaysAt = event.created_at;
+                else if (admission?.relays !== undefined)
+                    decoded.relays = admission.relays;
                 admission = decoded;
             }, () => {
                 if (admission)

package/llms.txt

@@ -67,6 +67,7 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `encodePersistentInvitation(opts)` / `decodePersistentInvitation(event, invitation)` - v3 stored group invitation (kind 1463)
 - `requestPersistentRoomAdmission(opts)` - joins from stored admission alone, no live desk needed
 - Conference rooms: `encodePersistentInvitation({ ..., endsAt })` puts `ends` in the body and `['expiration', String(endsAt)]` on the 1463; `decodePersistentInvitation` returns `endsAt` and is null when an `expiration` tag disagrees with the body; `encodeInvitationRetirement({ ..., endsAt })` tags the 1461 the same way
+- Room relays: `encodePersistentInvitation({ ..., relays })` puts the room's own relays (1-8 distinct canonical `wss://host/` URLs, else it throws) in the body after `ends`; the decoder returns `relays` and is null on a malformed list; `requestPersistentRoomAdmission` keeps the newest signed copy's list (a copy without one says nothing); `isInvitationRelays`, `requireInvitationRelays`, `MAX_INVITATION_RELAYS` (8)
 - `withExpiration(tags, expiresAt?)` - NIP-40 rule for a room that ends: add the tag, keep an earlier one, lower a later one; `isRoomEnds`, `requireRoomEnds(endsAt, now)`, `MAX_ROOM_ENDS_SECONDS` (30 days)
 - Epoch encoders (`encodeRekeyEvent`, `encodeEpochRequest`, `encodeEpochGrant`) and `hostRoomEpoch` / `requestRoomEpoch` take `expiresAt?` for a conference room
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/fold-kit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Circle primitives for private Nostr groups nobody operates: epoch keys, link invites, removal by rekey, device credentials.",
   "type": "module",
   "main": "./dist/index.js",