@forgesworn/fold-kit 0.3.0 → 0.5.0

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
 
@@ -78,6 +79,7 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `encodeEpochGrant(opts)` / `decodeEpochGrant(event, opts)` - the authority's answer (secret, epoch-0, or a refusal `'removed' | 'closed'`)
 - `epochRequestAdmission(opts)`, `deriveEpochRequestKey(roomKey)`
 - `hostRoomEpoch(opts)` / `requestRoomEpoch(opts)` / `EpochRefusedError` - the live request/grant desk, both sides
+- Member epoch catch-up (see `docs/member-epoch-catch-up.md`): `encodeRekeyEvent({ ..., commit: true })` writes `epochCommitment(roomId, epoch, secret)` into the rekey body; `hostMemberEpochDesk(opts)` lets any current member answer; `requestRoomEpoch({ ..., members: memberEpochSource(opts) })` asks the authority and members, first verifiable answer wins; `requestMemberEpoch(opts)` asks members alone. Kinds `MEMBER_EPOCH_KINDS` = `{ REQUEST: 20471, GRANT: 20472 }`. A member grant carries the authority-signed rekeys from the asker's epoch to the current one; the asker verifies the chain itself (`decodeMemberEpochGrant`) and refuses a last epoch with no commitment (legacy: authority only), a chain that removes it or closes the room, and one that stops short of `expected`. Codecs: `encodeMemberEpochRequest`, `decodeMemberEpochRequest`, `encodeMemberEpochGrant`, `readRekeyEvidence`, `deriveMemberEpochRequestKey`, `MAX_MEMBER_EPOCH_CHAIN` (32)
 - `canonicalAdmins(admins)` / `signAdmins(opts)` / `verifyAdmins(opts)` - the authority's signed admin list
 - `canonicalChannels(channels)` / `signChannels(opts)` / `verifyChannels(opts)` - the authority's signed channel list; `CHANNEL_NAME`, `RESERVED_CHANNELS`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/fold-kit",
-  "version": "0.3.0",
+  "version": "0.5.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",
@@ -20,6 +20,7 @@
     "dist",
     "vectors/kithmoot-vectors.json",
     "vectors/circle-vectors.json",
+    "vectors/member-epoch-vectors.json",
     "LICENSE",
     "README.md",
     "llms.txt"
@@ -31,6 +32,7 @@
     "typecheck": "tsc -p tsconfig.typecheck.json",
     "diff-source": "node scripts/diff-source.mjs",
     "generate-fold": "node scripts/generate-fold.mjs",
+    "generate-member-epoch": "node scripts/generate-member-epoch.mjs",
     "bundle-check": "node scripts/bundle-check.mjs",
     "tarball-smoke": "node scripts/tarball-smoke.mjs",
     "vectors": "vitest run vectors/",