@forgesworn/fold-kit 0.8.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`,
@@ -126,6 +135,16 @@ the rest).
   `requestPersistentRoomAdmission` keeps the relays of the newest signed
   copy that names any. `isInvitationRelays`, `requireInvitationRelays` and
   `MAX_INVITATION_RELAYS` are the rule
+- 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
+  `destruct: true` and refuses the envelope on any other value;
+  `requestPersistentRoomAdmission` keeps it if any signed copy says it.
+  `encodeInvitationRetirement({ ended: true, destruct: true })` and
+  `encodeRekeyEvent({ closed: true, destruct: true })` carry it when the
+  room ends early, read back by `decodeInvitationRetirementNotice`,
+  `RekeyNotice.destruct` and `RekeyEvidence.destruct`. Vectors:
+  `vectors/destruct-vectors.json`
 - `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
@@ -253,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/epoch.d.ts

@@ -111,6 +111,10 @@ export interface EncodeRekeyOptions {
     /** True when the room is being closed: nobody is kept, and the event
      *  says so rather than leaving everybody to wonder. */
     closed?: boolean;
+    /** The room being closed self-destructs: every device deletes what it
+     *  wrote and forgets the room. Inside the encrypted body. Refused
+     *  without `closed`. Omitted, the event is byte-identical to before. */
+    destruct?: boolean;
     /** Mark this as a scheduled turn of the key rather than a removal, so
      *  clients can let it pass quietly. Refused with a removal or a close: a
      *  rekey that removes somebody is never quiet. Omitted, the event is
@@ -144,6 +148,10 @@ export interface RekeyNotice {
     removed: string[];
     by?: string;
     closed: boolean;
+    /** True when the closed room self-destructs. Absent unless `closed`:
+     *  beside an open room the flag is not believed, and the rekey is read
+     *  as if it were not there. */
+    destruct?: true;
     /** True for a scheduled turn of the key: nobody removed, the room still
      *  open. What lets a client move on without saying so. Absent when the
      *  body contradicts itself, so a removal is always announced. */

package/dist/epoch.js

@@ -145,6 +145,8 @@ export function encodeRekeyEvent(opts) {
     const removed = [...new Set(opts.removed.map((p) => requireHex32(p, 'removed participant')))].sort();
     if (opts.scheduled && (removed.length > 0 || opts.closed))
         throw new Error('a scheduled rekey removes nobody and does not close the room');
+    if (opts.destruct && !opts.closed)
+        throw new Error('only a closing rekey can self-destruct the room');
     const keys = {};
     const sealed = { v: 1, secret: base64urlnopad.encode(opts.next.secret) };
     const plaintext = JSON.stringify(sealed);
@@ -159,6 +161,7 @@ export function encodeRekeyEvent(opts) {
         removed,
         ...(opts.by !== undefined ? { by: requireHex32(opts.by, 'admin') } : {}),
         ...(opts.closed ? { closed: true } : {}),
+        ...(opts.destruct ? { destruct: true } : {}),
         ...(opts.scheduled ? { scheduled: true } : {}),
         ...(opts.commit ? { commit: epochCommitment(roomId, epoch, opts.next.secret) } : {}),
         ...(opts.members !== undefined ? { members: memberListOf(opts.members, removed) } : {}),
@@ -226,6 +229,8 @@ export function decodeRekeyEvent(event, opts) {
         };
         if (typeof body.by === 'string' && HEX64.test(body.by))
             notice.by = normaliseHex(body.by);
+        if (body.destruct === true && notice.closed)
+            notice.destruct = true;
         if (body.scheduled === true && notice.removed.length === 0 && !notice.closed)
             notice.scheduled = true;
         const members = readMemberList(body.members);

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
@@ -165,6 +171,12 @@ export interface EncodeInvitationRetirementOptions {
     /** The room itself was ended, not just this link replaced. Additive: a
      * reader that predates it still sees an ordinary retirement. */
     ended?: boolean;
+    /** The ended room self-destructs: every device deletes what it wrote and
+     * forgets the room. Only beside `ended`, else it throws. Unlike the
+     * invitation's own flag this content is not encrypted: it says no more
+     * than `ended` does about a link nobody outside the room can name.
+     * Omitted or false, the event is byte-identical to 0.8.0's. */
+    destruct?: boolean;
     /** A conference room's end, in unix seconds: the tombstone carries the
      * same NIP-40 expiration as the invitation it retires, and lapses with it. */
     endsAt?: number;
@@ -176,10 +188,12 @@ export declare function encodeInvitationRetirement(opts: EncodeInvitationRetirem
 /** A valid tombstone never expires: invitation ids are random and unique,
  * and a retired bearer must not become usable again after a timeout. */
 export declare function decodeInvitationRetirement(event: Event, invitation: RoomInvitation): boolean;
-/** A valid retirement, and whether it says the room was ended. Undefined
- * for anything that is not a valid retirement of this invitation. */
+/** A valid retirement, whether it says the room was ended, and whether the
+ * ended room self-destructs (`destruct`, believed only beside `ended`).
+ * Undefined for anything that is not a valid retirement of this invitation. */
 export declare function decodeInvitationRetirementNotice(event: Event, invitation: RoomInvitation): {
     ended: boolean;
+    destruct?: true;
 } | undefined;
 /** The error a joiner rejects with on a retirement. */
 export declare function retirementError(notice: {

package/dist/invitation.js

@@ -279,11 +279,13 @@ export function encodeInvitationRetirement(opts) {
     if (!hexEquals(getPublicKey(opts.inviterSk), opts.invitation.inviter)) {
         throw new Error('only the root inviter can retire an invitation');
     }
+    if (opts.destruct && !opts.ended)
+        throw new Error('only an ended room can self-destruct');
     return finalizeEvent({
         kind: KINDS.INVITATION_RETIREMENT,
         created_at: opts.now,
         tags: withExpiration([['d', deriveInvitationId(opts.invitation)]], opts.endsAt),
-        content: JSON.stringify(opts.ended ? { v: 1, ended: true } : { v: 1 }),
+        content: JSON.stringify(opts.ended ? (opts.destruct ? { v: 1, ended: true, destruct: true } : { v: 1, ended: true }) : { v: 1 }),
     }, opts.inviterSk);
 }
 /** A valid tombstone never expires: invitation ids are random and unique,
@@ -291,8 +293,9 @@ export function encodeInvitationRetirement(opts) {
 export function decodeInvitationRetirement(event, invitation) {
     return decodeInvitationRetirementNotice(event, invitation) !== undefined;
 }
-/** A valid retirement, and whether it says the room was ended. Undefined
- * for anything that is not a valid retirement of this invitation. */
+/** A valid retirement, whether it says the room was ended, and whether the
+ * ended room self-destructs (`destruct`, believed only beside `ended`).
+ * Undefined for anything that is not a valid retirement of this invitation. */
 export function decodeInvitationRetirementNotice(event, invitation) {
     try {
         if (event.kind !== KINDS.INVITATION_RETIREMENT)
@@ -304,7 +307,9 @@ export function decodeInvitationRetirementNotice(event, invitation) {
         if (event.tags.find((tag) => tag[0] === 'd')?.[1] !== deriveInvitationId(invitation))
             return undefined;
         const body = JSON.parse(event.content);
-        return body.v === 1 ? { ended: body.ended === true } : undefined;
+        if (body.v !== 1)
+            return undefined;
+        return body.ended === true && body.destruct === true ? { ended: true, destruct: true } : { ended: body.ended === true };
     }
     catch {
         return undefined;
@@ -394,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/dist/member-epoch.d.ts

@@ -59,6 +59,8 @@ export interface RekeyEvidence {
     epoch: number;
     removed: string[];
     closed: boolean;
+    /** The closed room self-destructs: see `RekeyNotice.destruct`. */
+    destruct?: true;
     /** A scheduled turn of the key: see `RekeyNotice.scheduled`. */
     scheduled?: true;
     /** The epoch commitment, when the authority wrote one. */

package/dist/member-epoch.js

@@ -117,6 +117,8 @@ export function readRekeyEvidence(event, opts) {
             removed: [...new Set(body.removed.map(normaliseHex))].sort(),
             closed: body.closed === true,
         };
+        if (body.destruct === true && evidence.closed)
+            evidence.destruct = true;
         if (body.scheduled === true && evidence.removed.length === 0 && !evidence.closed)
             evidence.scheduled = true;
         if (typeof body.commit === 'string' && HEX64.test(body.commit))

package/dist/persistent-invitation.d.ts

@@ -13,6 +13,9 @@ export interface PersistentRoomAdmission {
     /** 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[];
+    /** The room self-destructs: when it ends, every device deletes what it
+     *  wrote and forgets the room. Absent for a room that simply ends. */
+    destruct?: true;
 }
 /** Publish once before sharing. The link plus this envelope is a durable
  * bearer capability: anybody holding both can learn epoch 0. Retirement
@@ -30,6 +33,10 @@ export declare function encodePersistentInvitation(opts: {
      *  form (see `isInvitationRelays`), else it throws. Omitted, the body is
      *  byte-identical to 0.3.0's. */
     relays?: readonly string[];
+    /** The room self-destructs when it ends, by its time or by its authority
+     *  closing it. Written inside the encrypted body only, never as a tag.
+     *  Omitted or false, the event is byte-identical to 0.8.0's. */
+    destruct?: boolean;
 }): 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

@@ -30,7 +30,7 @@ export function encodePersistentInvitation(opts) {
         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 }), ...(relays === undefined ? {} : { relays }),
+            v: 3, room, secret: base64urlnopad.encode(opts.roomSecret), ...(ends === undefined ? {} : { ends }), ...(opts.destruct ? { destruct: true } : {}), ...(relays === undefined ? {} : { relays }),
         }), welcomeKey(opts.invitation)),
     }, opts.inviterSk);
 }
@@ -62,9 +62,15 @@ export function decodePersistentInvitation(event, invitation) {
         // would write; a malformed one refuses the envelope rather than half of it.
         if (body.relays !== undefined && !isInvitationRelays(body.relays))
             return null;
+        // Self-destruct is `true` or absent; anything else is a malformed
+        // envelope, refused as a malformed end is.
+        if (body.destruct !== undefined && body.destruct !== true)
+            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];
+        if (body.destruct === true)
+            admission.destruct = true;
         return admission;
     }
     catch {
@@ -119,6 +125,10 @@ 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 self-destruct: it sticks, for
+                // the same reason, so a stale copy can never keep a room's content.
+                if (admission?.destruct)
+                    decoded.destruct = true;
                 // 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.

package/llms.txt

@@ -64,10 +64,12 @@ 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
 - 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)
+- Self-destructing rooms (see `docs/room-destruct.md`): `encodePersistentInvitation({ ..., destruct: true })` puts `"destruct": true` in the encrypted body after `ends` (valid without `ends`), never a tag; `decodePersistentInvitation` returns `destruct: true` and is null when the field is present and not `true`; `requestPersistentRoomAdmission` keeps `destruct` if any valid copy carries it (sticky, like the earliest `ends`). `encodeInvitationRetirement({ ..., ended: true, destruct: true })` writes `{"v":1,"ended":true,"destruct":true}` (plain JSON, like `ended`) and throws on `destruct` without `ended`; `decodeInvitationRetirementNotice` returns `{ ended, destruct?: true }`, believing `destruct` only beside `ended`. `encodeRekeyEvent({ ..., closed: true, destruct: true })` writes it in the encrypted body after `closed` and throws without `closed`; `RekeyNotice.destruct` / `RekeyEvidence.destruct` are set only on a closing body, and a flag on an open rekey is dropped, not refused. Without the flag every event is byte-identical to 0.8.0, and a 0.8.0 reader ignores it
 - `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
 
@@ -112,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.8.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",
@@ -23,9 +23,11 @@
     "vectors/member-epoch-vectors.json",
     "vectors/seal-vectors.json",
     "vectors/schedule-vectors.json",
+    "vectors/destruct-vectors.json",
     "LICENSE",
     "README.md",
-    "llms.txt"
+    "llms.txt",
+    "vectors/live-persistent-vectors.json"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -37,12 +39,14 @@
     "generate-member-epoch": "node scripts/generate-member-epoch.mjs",
     "generate-seal": "node scripts/generate-seal.mjs",
     "generate-schedule": "node scripts/generate-schedule.mjs",
+    "generate-destruct": "node scripts/generate-destruct.mjs",
     "bundle-check": "node scripts/bundle-check.mjs",
     "tarball-smoke": "node scripts/tarball-smoke.mjs",
     "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",