@forgesworn/fold-kit 0.9.0 → 0.10.0

package/README.md

@@ -104,6 +104,15 @@ the rest).
 
 ### Links and invitations
 
+`hostRoomInvitation` distinguishes approval from grant publication. Its
+`onGrantPublished(request)` and legacy `onAdmitted(device)` callbacks run only
+after the injected transport acknowledges the grant's publication.
+`onGrantFailed(request, error)` reports a rejected or throwing publication;
+neither success callback runs for that failure. Closing or retiring the host
+suppresses callbacks from outstanding sends. Publication acknowledgement does
+not prove that a guest received the grant or joined; the guest validates its
+grant independently. Observer exceptions do not change the publish outcome.
+
 - `parseRoomLink`, `encodeRoomLink`, `RoomLink` - the v1/v2/v3 link envelope
 - `createRoomInvitation`, `roomInvitation`, `deriveInvitationId`,
   `encodeInvitationRequest`, `decodeInvitationRequest`,
@@ -263,3 +272,21 @@ There is no separate lint script.
 ## Licence
 
 MIT
+
+### Live persistent admission (opt-in codecs)
+
+`parseLivePersistentEvent` bounds raw event JSON and refuses duplicate fields.
+`encodeLivePersistentDescriptor` / `decodeLivePersistentDescriptor` carry
+routing metadata alongside an unchanged persistent invitation link.
+`encodeLivePersistentRequest` / `decodeLivePersistentRequest` and
+`encodeLivePersistentAnswer` / `decodeLivePersistentAnswer` implement a fresh,
+root-signed challenge/answer with no delegation. The answer retains epoch-zero
+capability separately from `epochHint`. Constants bound request/answer lifetimes
+to 90/30 seconds. `LIVE_PERSISTENT_ADMISSION_LABELS` freezes its distinct KDF.
+
+These functions are codecs, not an offline join API. The host must have exclusive
+durable lifecycle authority; the client must complete authenticated epoch
+admission before publishing, including at epoch zero. No application enables
+this profile automatically. See [the wire profile and integration gates](docs/live-persistent-admission.md).
+Frozen synthetic fixtures are in `vectors/live-persistent-vectors.json`; run
+`npm run build && npm run generate-live-persistent` to regenerate them.

package/dist/index.d.ts

@@ -34,3 +34,4 @@ export type { RekeyEvidence, EncodeMemberEpochRequestOptions, DecodeMemberEpochR
 export { deriveChannel, CHANNEL_ID_INFO, CHANNEL_KEY_INFO, MAX_CHANNEL_NAME_LENGTH, CHANNEL_LABELS } from './channel.js';
 export { LANES, LANE_MEANING, LANE_LABEL, LANE_GLYPH, isLane, laneOfRelayUrl, laneOfRelays, weakestLane, isDowngrade, } from './lane.js';
 export type { Lane } from './lane.js';
+export * from "./live-persistent-admission.js";

package/dist/index.js

@@ -22,3 +22,5 @@ export { EPOCH_COMMIT_PREFIX, epochCommitment, EPOCH_COMMIT_LABELS } from './epo
 export { MEMBER_EPOCH_KINDS, MEMBER_EPOCH_REQUEST_KEY_INFO, MAX_MEMBER_EPOCH_CHAIN, deriveMemberEpochRequestKey, readRekeyEvidence, encodeMemberEpochRequest, decodeMemberEpochRequest, encodeMemberEpochGrant, decodeMemberEpochGrant, hostMemberEpochDesk, memberEpochSource, requestMemberEpoch, MEMBER_EPOCH_LABELS, } from './member-epoch.js';
 export { deriveChannel, CHANNEL_ID_INFO, CHANNEL_KEY_INFO, MAX_CHANNEL_NAME_LENGTH, CHANNEL_LABELS } from './channel.js';
 export { LANES, LANE_MEANING, LANE_LABEL, LANE_GLYPH, isLane, laneOfRelayUrl, laneOfRelays, weakestLane, isDowngrade, } from './lane.js';
+// Opt-in live persistent capability exchange; host lifecycle and epoch gates remain required.
+export * from "./live-persistent-admission.js";

package/dist/invitation.d.ts

@@ -139,7 +139,13 @@ export interface HostRoomInvitationOptions {
     /** Root-to-this-responder chain. Empty/absent only on the creator. */
     delegation?: InvitationDelegation[];
     now?: () => number;
+    /** Called after the injected transport acknowledges publication. This is
+     * not proof that the guest received the grant or joined the room. */
     onAdmitted?: (device: string) => void;
+    /** The same publication acknowledgement, correlated to the request. */
+    onGrantPublished?: (request: InvitationRequest) => void;
+    /** Publication rejected or threw. No admission callback is made. */
+    onGrantFailed?: (request: InvitationRequest, error: unknown) => void;
     /** Called when the creator's durable retirement tombstone is heard. */
     onRetired?: () => void;
     /** The epoch this responder is at, asked on every grant because it

package/dist/invitation.js

@@ -399,8 +399,29 @@ export function hostRoomInvitation(opts) {
                 close();
                 return;
             }
-            opts.transport.publish(grant).catch(() => { });
-            opts.onAdmitted?.(request.device);
+            // The decision to approve and the publication of its grant are
+            // separate states. A rejected send must never look like admission.
+            Promise.resolve()
+                .then(() => { if (!closed)
+                return opts.transport.publish(grant); })
+                .then(() => {
+                if (closed)
+                    return;
+                // One observer throwing must not change the publish outcome or
+                // prevent an independent observer from hearing it.
+                try {
+                    opts.onGrantPublished?.(request);
+                }
+                catch { /* Observer only. */ }
+                try {
+                    opts.onAdmitted?.(request.device);
+                }
+                catch { /* Observer only. */ }
+            }, error => {
+                if (!closed)
+                    opts.onGrantFailed?.(request, error);
+            })
+                .catch(() => { });
         };
         if (!opts.admit) {
             grantNow();

package/dist/live-persistent-admission.d.ts

@@ -0,0 +1,52 @@
+import { type Event } from 'nostr-tools/pure';
+import { type RoomInvitation } from './invitation.js';
+import { type PersistentRoomAdmission } from './persistent-invitation.js';
+export declare const LIVE_PERSISTENT_REQUEST_SECONDS = 90;
+export declare const LIVE_PERSISTENT_RESPONSE_SECONDS = 30;
+export interface LivePersistentContext {
+    invitation: RoomInvitation;
+    /** From the separate routing descriptor; authenticated again in the answer. */
+    roomId: string;
+}
+export interface LivePersistentRequest {
+    requestId: string;
+    requester: string;
+    createdAt: number;
+    expiresAt: number;
+}
+/** Capability evidence only. The caller must still perform epoch admission. */
+export interface LivePersistentAnswer {
+    admission: PersistentRoomAdmission;
+    epochHint: number;
+    requestId: string;
+    expiresAt: number;
+}
+/** For raw input boundaries: bound bytes before parsing, retain exact fields,
+ * and reject duplicate JSON keys before a general event reader can discard them. */
+export declare function parseLivePersistentEvent(json: string, request: boolean): Event | null;
+/** Routing metadata only; never advertise the invitation bearer. */
+export declare function encodeLivePersistentDescriptor(opts: LivePersistentContext): string;
+export declare function decodeLivePersistentDescriptor(encoded: string, invitation: RoomInvitation): LivePersistentContext | null;
+export declare function encodeLivePersistentRequest(opts: LivePersistentContext & {
+    requesterSk: Uint8Array;
+    now: number;
+}): Event;
+export declare function decodeLivePersistentRequest(event: Event, opts: LivePersistentContext & {
+    now: number;
+}): LivePersistentRequest | null;
+/** Codec only: callers must hold the durable lifecycle lock through handoff.
+ * This function cannot prove that the root's invitation is active. */
+export declare function encodeLivePersistentAnswer(opts: LivePersistentContext & {
+    request: Event;
+    invitationEvent: Event;
+    inviterSk: Uint8Array;
+    epoch: number;
+    now: number;
+}): Event;
+/** Stateless proof reader. The request owner consumes a result at most once. */
+export declare function decodeLivePersistentAnswer(event: Event, opts: LivePersistentContext & {
+    request: Event;
+    requesterSk: Uint8Array;
+    now: number;
+}): LivePersistentAnswer | null;
+export declare const LIVE_PERSISTENT_ADMISSION_LABELS: readonly ["kithmoot/v1/persistent-live/request-key"];

package/dist/live-persistent-admission.js

@@ -0,0 +1,183 @@
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha2';
+import { base64urlnopad } from '@scure/base';
+import { nip44 } from 'nostr-tools';
+import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
+import { deriveInvitationId } from './invitation.js';
+import { decodePersistentInvitation } from './persistent-invitation.js';
+import { deriveRoom } from './room.js';
+import { verifyEventUncached } from './verify.js';
+import { KINDS } from './kinds.js';
+const REQUEST_KEY = 'kithmoot/v1/persistent-live/request-key';
+const PROFILE = 'persistent-live';
+const HEX = /^[0-9a-f]{64}$/;
+const SIG = /^[0-9a-f]{128}$/;
+const utf8 = new TextEncoder();
+const text = new TextDecoder('utf-8', { fatal: true });
+export const LIVE_PERSISTENT_REQUEST_SECONDS = 90;
+export const LIVE_PERSISTENT_RESPONSE_SECONDS = 30;
+const SKEW = 5;
+function check(ok) {
+    if (!ok)
+        throw new Error('invalid live persistent admission');
+}
+function integer(n) {
+    return typeof n === 'number' && Number.isSafeInteger(n) && n >= 0;
+}
+function clock(now) {
+    check(integer(now) && now <= Number.MAX_SAFE_INTEGER - LIVE_PERSISTENT_REQUEST_SECONDS);
+}
+function context(opts) {
+    check(opts.invitation.persistent === true && opts.invitation.bearer.length === 32);
+    check(HEX.test(opts.invitation.inviter) && HEX.test(opts.roomId));
+}
+function fields(raw, names) {
+    check(typeof raw === 'object' && raw !== null && !Array.isArray(raw));
+    const keys = Object.keys(raw);
+    check(keys.length === names.length && keys.every(k => names.includes(k)));
+}
+/** Minified JSON also rejects duplicate fields and ambiguous number spellings. */
+function body(raw, names) {
+    const parsed = JSON.parse(raw);
+    fields(parsed, names);
+    check(JSON.stringify(parsed) === raw);
+    return parsed;
+}
+function key(invitation) {
+    return hkdf(sha256, invitation.bearer, undefined, REQUEST_KEY, 32);
+}
+function wire(event) {
+    return { id: event.id, pubkey: event.pubkey, created_at: event.created_at,
+        kind: event.kind, tags: event.tags, content: event.content, sig: event.sig };
+}
+/** Bound every field before serialising or verifying an attacker-supplied object. */
+function eventBounds(raw, contentLimit, byteLimit, tagsLimit) {
+    fields(raw, ['id', 'pubkey', 'created_at', 'kind', 'tags', 'content', 'sig']);
+    check(typeof raw.id === 'string' && HEX.test(raw.id) && typeof raw.pubkey === 'string' && HEX.test(raw.pubkey));
+    check(typeof raw.sig === 'string' && SIG.test(raw.sig) && integer(raw.kind) && integer(raw.created_at));
+    check(typeof raw.content === 'string' && raw.content.length <= contentLimit);
+    check(Array.isArray(raw.tags) && raw.tags.length <= tagsLimit);
+    for (const tag of raw.tags) {
+        check(Array.isArray(tag) && tag.length <= 4 && tag.every(v => typeof v === 'string' && v.length <= 256));
+    }
+    check(utf8.encode(JSON.stringify(raw)).length <= byteLimit);
+}
+/** For raw input boundaries: bound bytes before parsing, retain exact fields,
+ * and reject duplicate JSON keys before a general event reader can discard them. */
+export function parseLivePersistentEvent(json, request) {
+    try {
+        const max = request ? 4096 : 20480;
+        check(typeof json === 'string' && json.length <= max && utf8.encode(json).length <= max);
+        const raw = JSON.parse(json);
+        check(JSON.stringify(raw) === json);
+        eventBounds(raw, request ? 2048 : 16384, max, 3);
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+function envelope(event, opts, kind, recipient, now) {
+    context(opts);
+    clock(now);
+    const request = kind === KINDS.INVITATION_REQUEST;
+    eventBounds(event, request ? 2048 : 16384, request ? 4096 : 20480, 3);
+    check(event.kind === kind && event.created_at <= now + SKEW);
+    check(event.tags.length === 3 && event.tags.every(t => t.length === 2));
+    const tag = (name) => {
+        const matches = event.tags.filter(t => t[0] === name);
+        check(matches.length === 1);
+        return matches[0][1];
+    };
+    check(tag('d') === deriveInvitationId(opts.invitation) && tag('p') === recipient);
+    const expiresAt = Number(tag('expiration'));
+    check(integer(expiresAt) && String(expiresAt) === tag('expiration') && expiresAt > now);
+    check(verifyEventUncached(event));
+    return expiresAt;
+}
+/** Routing metadata only; never advertise the invitation bearer. */
+export function encodeLivePersistentDescriptor(opts) {
+    context(opts);
+    return base64urlnopad.encode(utf8.encode(JSON.stringify({ v: 1, room: opts.roomId,
+        invitation: deriveInvitationId(opts.invitation), inviter: opts.invitation.inviter })));
+}
+export function decodeLivePersistentDescriptor(encoded, invitation) {
+    try {
+        check(typeof encoded === 'string' && encoded.length <= 512);
+        const bytes = base64urlnopad.decode(encoded);
+        check(bytes.length <= 384 && base64urlnopad.encode(bytes) === encoded);
+        const raw = body(text.decode(bytes), ['v', 'room', 'invitation', 'inviter']);
+        check(raw.v === 1 && typeof raw.room === 'string');
+        const opts = { invitation, roomId: raw.room };
+        context(opts);
+        check(raw.invitation === deriveInvitationId(invitation) && raw.inviter === invitation.inviter);
+        return opts;
+    }
+    catch {
+        return null;
+    }
+}
+export function encodeLivePersistentRequest(opts) {
+    context(opts);
+    clock(opts.now);
+    return finalizeEvent({ kind: KINDS.INVITATION_REQUEST, created_at: opts.now,
+        tags: [['d', deriveInvitationId(opts.invitation)], ['p', opts.invitation.inviter],
+            ['expiration', String(opts.now + LIVE_PERSISTENT_REQUEST_SECONDS)]],
+        content: nip44.v2.encrypt(JSON.stringify({ v: 1, profile: PROFILE, room: opts.roomId,
+            requester: getPublicKey(opts.requesterSk) }), key(opts.invitation)),
+    }, opts.requesterSk);
+}
+export function decodeLivePersistentRequest(event, opts) {
+    try {
+        const expiresAt = envelope(event, opts, KINDS.INVITATION_REQUEST, opts.invitation.inviter, opts.now);
+        check(expiresAt === event.created_at + LIVE_PERSISTENT_REQUEST_SECONDS);
+        const raw = body(nip44.v2.decrypt(event.content, key(opts.invitation)), ['v', 'profile', 'room', 'requester']);
+        check(raw.v === 1 && raw.profile === PROFILE && raw.room === opts.roomId && raw.requester === event.pubkey);
+        return { requestId: event.id, requester: event.pubkey, createdAt: event.created_at, expiresAt };
+    }
+    catch {
+        return null;
+    }
+}
+function invitationOf(event, opts, now, responseAt) {
+    eventBounds(event, 6144, 8192, 8);
+    check(event.created_at <= Math.min(now, responseAt) + SKEW);
+    const admission = decodePersistentInvitation(event, opts.invitation);
+    check(admission !== null && deriveRoom(admission.secret).roomId === opts.roomId);
+    check(admission.endsAt === undefined || admission.endsAt > now);
+    return admission;
+}
+/** Codec only: callers must hold the durable lifecycle lock through handoff.
+ * This function cannot prove that the root's invitation is active. */
+export function encodeLivePersistentAnswer(opts) {
+    const request = decodeLivePersistentRequest(opts.request, opts);
+    check(request !== null && integer(opts.epoch) && getPublicKey(opts.inviterSk) === opts.invitation.inviter);
+    check(opts.now >= request.createdAt - SKEW);
+    invitationOf(opts.invitationEvent, opts, opts.now, opts.now);
+    const event = finalizeEvent({ kind: KINDS.INVITATION_GRANT, created_at: opts.now,
+        tags: [['d', deriveInvitationId(opts.invitation)], ['p', request.requester],
+            ['expiration', String(Math.min(request.expiresAt, opts.now + LIVE_PERSISTENT_RESPONSE_SECONDS))]],
+        content: nip44.v2.encrypt(JSON.stringify({ v: 1, profile: PROFILE, request: request.requestId,
+            room: opts.roomId, epoch: opts.epoch, invitation: wire(opts.invitationEvent) }), nip44.v2.utils.getConversationKey(opts.inviterSk, request.requester)),
+    }, opts.inviterSk);
+    eventBounds(event, 16384, 20480, 3);
+    return event;
+}
+/** Stateless proof reader. The request owner consumes a result at most once. */
+export function decodeLivePersistentAnswer(event, opts) {
+    try {
+        const request = decodeLivePersistentRequest(opts.request, opts);
+        check(request !== null && getPublicKey(opts.requesterSk) === request.requester);
+        const expiresAt = envelope(event, opts, KINDS.INVITATION_GRANT, request.requester, opts.now);
+        check(event.pubkey === opts.invitation.inviter && event.created_at >= request.createdAt - SKEW);
+        check(expiresAt === Math.min(request.expiresAt, event.created_at + LIVE_PERSISTENT_RESPONSE_SECONDS));
+        const raw = body(nip44.v2.decrypt(event.content, nip44.v2.utils.getConversationKey(opts.requesterSk, opts.invitation.inviter)), ['v', 'profile', 'request', 'room', 'epoch', 'invitation']);
+        check(raw.v === 1 && raw.profile === PROFILE && raw.request === request.requestId && raw.room === opts.roomId && integer(raw.epoch));
+        const admission = invitationOf(raw.invitation, opts, opts.now, event.created_at);
+        return { admission, epochHint: raw.epoch, requestId: request.requestId, expiresAt };
+    }
+    catch {
+        return null;
+    }
+}
+export const LIVE_PERSISTENT_ADMISSION_LABELS = [REQUEST_KEY];

package/llms.txt

@@ -64,6 +64,7 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `verifyInvitationDelegation(invitation, chain, now)`
 - `encodeInvitationRetirement(opts)` / `decodeInvitationRetirementNotice(event, invitation)` - durable tombstone (kind 1461)
 - `hostRoomInvitation(opts)` / `requestRoomAdmission(opts)` - the live desk, both sides
+- Host `onGrantPublished(request)` / legacy `onAdmitted(device)` run after transport publication acknowledgement, not on approval. `onGrantFailed(request, error)` reports send failure; closed hosts suppress outstanding callbacks. Publication does not prove guest receipt or room entry.
 - `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
@@ -113,3 +114,21 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - README.md - full API overview, peer dependency rationale, how this kit relates to `covey-kit` and `roost-kit`
 - EXTRACTION.md - the source commit, exactly which modules and functions moved, and the two splits (`access.ts`, `chat.ts`) performed on the way
 - AGENTS.md - build/test commands and repository conventions for an agent working in this repo
+
+### Live persistent admission (opt-in codecs)
+
+`parseLivePersistentEvent` bounds raw event JSON and refuses duplicate fields.
+`encodeLivePersistentDescriptor` / `decodeLivePersistentDescriptor` carry
+routing metadata alongside an unchanged persistent invitation link.
+`encodeLivePersistentRequest` / `decodeLivePersistentRequest` and
+`encodeLivePersistentAnswer` / `decodeLivePersistentAnswer` implement a fresh,
+root-signed challenge/answer with no delegation. The answer retains epoch-zero
+capability separately from `epochHint`. Constants bound request/answer lifetimes
+to 90/30 seconds. `LIVE_PERSISTENT_ADMISSION_LABELS` freezes its distinct KDF.
+
+These functions are codecs, not an offline join API. The host must have exclusive
+durable lifecycle authority; the client must complete authenticated epoch
+admission before publishing, including at epoch zero. No application enables
+this profile automatically. See [the wire profile and integration gates](docs/live-persistent-admission.md).
+Frozen synthetic fixtures are in `vectors/live-persistent-vectors.json`; run
+`npm run build && npm run generate-live-persistent` to regenerate them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/fold-kit",
-  "version": "0.9.0",
+  "version": "0.10.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",
@@ -26,7 +26,8 @@
     "vectors/destruct-vectors.json",
     "LICENSE",
     "README.md",
-    "llms.txt"
+    "llms.txt",
+    "vectors/live-persistent-vectors.json"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -44,7 +45,8 @@
     "vectors": "vitest run vectors/",
     "check": "npm run typecheck && npm test && npm run diff-source",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run check && npm run bundle-check && npm run tarball-smoke"
+    "prepublishOnly": "npm run check && npm run bundle-check && npm run tarball-smoke",
+    "generate-live-persistent": "node scripts/generate-live-persistent.mjs"
   },
   "keywords": [
     "nostr",