@forgesworn/fold-kit 0.2.0 → 0.3.0

package/README.md

@@ -113,7 +113,16 @@ the rest).
   `requestRoomAdmission` - the v2 live rendezvous invitation, its delegation
   chain and retirement
 - `encodePersistentInvitation`, `decodePersistentInvitation`,
-  `requestPersistentRoomAdmission` - the v3 stored group invitation (1463)
+  `requestPersistentRoomAdmission` - the v3 stored group invitation (1463).
+  Pass `endsAt` (unix seconds, after `now` and at most 30 days on) for a
+  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
+- `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
+  `endsAt`, and the epoch encoders, `hostRoomEpoch` and `requestRoomEpoch`
+  take `expiresAt`, to tag what they sign the same way
 
 ### Epochs (removal by rekey)
 

package/dist/epoch.d.ts

@@ -104,6 +104,9 @@ export interface EncodeRekeyOptions {
      *  says so rather than leaving everybody to wonder. */
     closed?: boolean;
     now: number;
+    /** 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;
 }
 /** Announce the next epoch. See the module comment for what this is. */
 export declare function encodeRekeyEvent(opts: EncodeRekeyOptions): Event;
@@ -189,6 +192,9 @@ export interface EncodeEpochRequestOptions {
     credential: DeviceCredential;
     proof?: KindredProof;
     now: number;
+    /** 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;
 }
 /** Ask the authority which epoch the room is at, and for its secret. */
 export declare function encodeEpochRequest(opts: EncodeEpochRequestOptions): Event;
@@ -226,6 +232,9 @@ export interface EncodeEpochGrantOptions {
     epoch?: RoomEpoch;
     removed?: string[];
     refused?: EpochRefusal;
+    /** 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;
 }
 /** Answer one request: the current epoch sealed to the asking device, or a
  *  refusal it alone can read. */
@@ -268,6 +277,8 @@ export interface HostRoomEpochOptions {
     now?: () => number;
     onGranted?: (request: EpochRequest) => void;
     onRefused?: (request: EpochRequest, why: EpochRefusal) => void;
+    /** A conference room's end: every grant carries it as an expiration. */
+    expiresAt?: number;
 }
 /**
  * Answer epoch requests for as long as the handle is open. What a keeper
@@ -294,6 +305,8 @@ export interface RequestRoomEpochOptions {
     now?: () => number;
     timeoutMs?: number;
     retryMs?: number;
+    /** A conference room's end: the request carries it as an expiration. */
+    expiresAt?: number;
 }
 /** Thrown when the authority answered, and the answer was no. */
 export declare class EpochRefusedError extends Error {

package/dist/epoch.js

@@ -12,6 +12,7 @@ import { deriveRoom } from './room.js';
 import { verifyDeviceCredential } from './credential.js';
 import { evaluateAccess } from './access.js';
 import { verifyEventUncached } from './verify.js';
+import { withExpiration } from './expiration.js';
 /**
  * Room epochs: how a member is removed.
  *
@@ -144,10 +145,10 @@ export function encodeRekeyEvent(opts) {
     return finalizeEvent({
         kind: KINDS.ROOM_REKEY,
         created_at: opts.now,
-        tags: [
+        tags: withExpiration([
             ['d', roomId],
             ['epoch', String(epoch)],
-        ],
+        ], opts.expiresAt),
         content: nip44.v2.encrypt(JSON.stringify(body), opts.current.key),
     }, opts.authoritySk);
 }
@@ -282,10 +283,10 @@ export function encodeEpochRequest(opts) {
     return finalizeEvent({
         kind: KINDS.EPOCH_REQUEST,
         created_at: opts.now,
-        tags: [
+        tags: withExpiration([
             ['d', roomId],
             ['p', authority],
-        ],
+        ], opts.expiresAt),
         content: nip44.v2.encrypt(JSON.stringify(body), nip44.v2.utils.getConversationKey(opts.deviceSk, authority)),
     }, opts.deviceSk);
 }
@@ -367,10 +368,10 @@ export function encodeEpochGrant(opts) {
     return finalizeEvent({
         kind: KINDS.EPOCH_GRANT,
         created_at: opts.now,
-        tags: [
+        tags: withExpiration([
             ['d', roomId],
             ['p', device],
-        ],
+        ], opts.expiresAt),
         content: nip44.v2.encrypt(JSON.stringify(body), nip44.v2.utils.getConversationKey(opts.authoritySk, device)),
     }, opts.authoritySk);
 }
@@ -458,7 +459,7 @@ export function hostRoomEpoch(opts) {
         let grant;
         try {
             grant = refused
-                ? encodeEpochGrant({ roomId, authoritySk: opts.authoritySk, device: request.device, request: request.request, now: now(), refused })
+                ? encodeEpochGrant({ roomId, authoritySk: opts.authoritySk, device: request.device, request: request.request, now: now(), refused, expiresAt: opts.expiresAt })
                 : encodeEpochGrant({
                     roomId,
                     authoritySk: opts.authoritySk,
@@ -467,6 +468,7 @@ export function hostRoomEpoch(opts) {
                     now: now(),
                     epoch: opts.current(),
                     removed: [...opts.removed()],
+                    expiresAt: opts.expiresAt,
                 });
         }
         catch {
@@ -511,6 +513,7 @@ export function requestRoomEpoch(opts) {
         credential: opts.credential,
         proof: opts.proof,
         now: now(),
+        expiresAt: opts.expiresAt,
     });
     return new Promise((resolve, reject) => {
         let settled = false;

package/dist/expiration.d.ts

@@ -0,0 +1,31 @@
+/**
+ * NIP-40 expiration for a room that ends: a conference room.
+ *
+ * A conference room is a persistent group with a fixed end time. Every event
+ * signed for it carries `['expiration', String(ends)]`, so relays that honour
+ * NIP-40 drop the room's traffic once it has ended, rather than holding it
+ * for as long as they keep anything. Not new in this kit: the shape is the
+ * plain NIP-40 tag; what is decided here is how it meets an event that
+ * already carries one of its own (a signal wrap, a call bell).
+ */
+/** The furthest ahead a conference room may end, from the moment it is
+ *  created: thirty days. */
+export declare const MAX_ROOM_ENDS_SECONDS: number;
+/** True for a whole number of unix seconds a room could end at: a positive
+ *  safe integer. Says nothing about whether it is in the future. */
+export declare function isRoomEnds(value: unknown): value is number;
+/** Throws unless `endsAt` is a valid end for a room created at `now`: after
+ *  `now`, and no more than `MAX_ROOM_ENDS_SECONDS` beyond it. */
+export declare function requireRoomEnds(endsAt: number, now: number): number;
+/**
+ * `tags` with the room's end applied as a NIP-40 expiration.
+ *
+ * An event with no expiration gains `['expiration', String(expiresAt)]`. One
+ * that already expires earlier keeps its own: the room ending does not make
+ * a short-lived event live longer. One that expires later is lowered to
+ * `expiresAt`. Never more than one expiration tag comes back; any extra is
+ * folded into the earliest. `expiresAt` undefined returns `tags` untouched,
+ * the same array, so a room with no end signs exactly the bytes it always
+ * did.
+ */
+export declare function withExpiration(tags: string[][], expiresAt: number | undefined): string[][];

package/dist/expiration.js

@@ -0,0 +1,62 @@
+/**
+ * NIP-40 expiration for a room that ends: a conference room.
+ *
+ * A conference room is a persistent group with a fixed end time. Every event
+ * signed for it carries `['expiration', String(ends)]`, so relays that honour
+ * NIP-40 drop the room's traffic once it has ended, rather than holding it
+ * for as long as they keep anything. Not new in this kit: the shape is the
+ * plain NIP-40 tag; what is decided here is how it meets an event that
+ * already carries one of its own (a signal wrap, a call bell).
+ */
+/** The furthest ahead a conference room may end, from the moment it is
+ *  created: thirty days. */
+export const MAX_ROOM_ENDS_SECONDS = 30 * 24 * 60 * 60;
+/** True for a whole number of unix seconds a room could end at: a positive
+ *  safe integer. Says nothing about whether it is in the future. */
+export function isRoomEnds(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+/** Throws unless `endsAt` is a valid end for a room created at `now`: after
+ *  `now`, and no more than `MAX_ROOM_ENDS_SECONDS` beyond it. */
+export function requireRoomEnds(endsAt, now) {
+    if (!isRoomEnds(endsAt))
+        throw new Error('a room end must be a positive whole number of seconds');
+    if (endsAt <= now)
+        throw new Error('a room cannot end in the past');
+    if (endsAt > now + MAX_ROOM_ENDS_SECONDS)
+        throw new Error('a room cannot end more than 30 days from now');
+    return endsAt;
+}
+/**
+ * `tags` with the room's end applied as a NIP-40 expiration.
+ *
+ * An event with no expiration gains `['expiration', String(expiresAt)]`. One
+ * that already expires earlier keeps its own: the room ending does not make
+ * a short-lived event live longer. One that expires later is lowered to
+ * `expiresAt`. Never more than one expiration tag comes back; any extra is
+ * folded into the earliest. `expiresAt` undefined returns `tags` untouched,
+ * the same array, so a room with no end signs exactly the bytes it always
+ * did.
+ */
+export function withExpiration(tags, expiresAt) {
+    if (expiresAt === undefined)
+        return tags;
+    if (!isRoomEnds(expiresAt))
+        throw new Error('an expiration must be a positive whole number of seconds');
+    let earliest = expiresAt;
+    let first = -1;
+    tags.forEach((tag, i) => {
+        if (tag[0] !== 'expiration')
+            return;
+        if (first === -1)
+            first = i;
+        const own = Number(tag[1]);
+        if (isRoomEnds(own) && own < earliest)
+            earliest = own;
+    });
+    const out = tags.filter((tag, i) => tag[0] !== 'expiration' || i === first);
+    const tag = ['expiration', String(earliest)];
+    if (first === -1)
+        return [...out, tag];
+    return out.map((t) => (t[0] === 'expiration' ? tag : t));
+}

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, cre
 export type { RoomInvitation, RoomInvitationHost, InvitationDelegation, RoomInvitationDelegate, RoomAdmission, EncodeInvitationRequestOptions, InvitationRequest, DecodeInvitationRequestOptions, EncodeInvitationGrantOptions, DecodeInvitationGrantOptions, HostRoomInvitationOptions, EncodeInvitationRetirementOptions, RequestRoomAdmissionOptions, } from './invitation.js';
 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 { 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

@@ -13,6 +13,7 @@ export { sanitiseDisplayName, MAX_DISPLAY_NAME_LENGTH } from './display-name.js'
 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 { 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.d.ts

@@ -165,6 +165,9 @@ 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;
+    /** 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;
 }
 /** What a joiner is told when a link was retired because its room ended. */
 export declare const ROOM_ENDED_MESSAGE = "this room was ended by the person who started it";

package/dist/invitation.js

@@ -8,6 +8,7 @@ import { finalizeEvent, generateSecretKey, getPublicKey } from 'nostr-tools/pure
 import { hexEquals, normaliseHex } from './hex.js';
 import { KINDS } from './kinds.js';
 import { verifyEventUncached } from './verify.js';
+import { withExpiration } from './expiration.js';
 import { deriveRoom } from './room.js';
 const INVITATION_ID_INFO = 'kithmoot/v2/invitation-id';
 const INVITATION_REQUEST_KEY_INFO = 'kithmoot/v2/invitation-request-key';
@@ -281,7 +282,7 @@ export function encodeInvitationRetirement(opts) {
     return finalizeEvent({
         kind: KINDS.INVITATION_RETIREMENT,
         created_at: opts.now,
-        tags: [['d', deriveInvitationId(opts.invitation)]],
+        tags: withExpiration([['d', deriveInvitationId(opts.invitation)]], opts.endsAt),
         content: JSON.stringify(opts.ended ? { v: 1, ended: true } : { v: 1 }),
     }, opts.inviterSk);
 }

package/dist/persistent-invitation.d.ts

@@ -7,6 +7,9 @@ export interface PersistentRoomAdmission {
     secret: Uint8Array;
     persistent: true;
     epoch: 0;
+    /** When the room ends, in unix seconds: a conference room. Absent for a
+     *  group that runs until somebody ends it. */
+    endsAt?: number;
 }
 /** Publish once before sharing. The link plus this envelope is a durable
  * bearer capability: anybody holding both can learn epoch 0. Retirement
@@ -16,6 +19,10 @@ export declare function encodePersistentInvitation(opts: {
     inviterSk: Uint8Array;
     roomSecret: Uint8Array;
     now: number;
+    /** A conference room's end, in unix seconds: after `now` and no more than
+     *  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;
 }): 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

@@ -7,6 +7,7 @@ import { decodeInvitationRetirementNotice, deriveInvitationId, retirementError }
 import { KINDS } from './kinds.js';
 import { deriveRoom } from './room.js';
 import { verifyEventUncached } from './verify.js';
+import { isRoomEnds, requireRoomEnds } from './expiration.js';
 function welcomeKey(invitation) {
     if (!invitation.persistent)
         throw new Error('a persistent group invitation is required');
@@ -21,12 +22,13 @@ export function encodePersistentInvitation(opts) {
     if (getPublicKey(opts.inviterSk) !== opts.invitation.inviter)
         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);
     return finalizeEvent({
         kind: KINDS.GROUP_INVITATION,
         created_at: opts.now,
-        tags: [['d', deriveInvitationId(opts.invitation)]],
+        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),
+            v: 3, room, secret: base64urlnopad.encode(opts.roomSecret), ...(ends === undefined ? {} : { ends }),
         }), welcomeKey(opts.invitation)),
     }, opts.inviterSk);
 }
@@ -45,7 +47,16 @@ export function decodePersistentInvitation(event, invitation) {
         const secret = base64urlnopad.decode(body.secret);
         if (deriveRoom(secret).roomId !== body.room)
             return null;
-        return { secret, persistent: true, epoch: 0 };
+        // A conference room's end rides in the body and, for relays, as a NIP-40
+        // expiration. The two must agree: a tag with no body end, a second tag,
+        // or an end that is not a whole number of seconds is refused outright.
+        const ends = body.ends === undefined ? undefined : isRoomEnds(body.ends) ? body.ends : null;
+        const expirations = event.tags.filter(t => t[0] === 'expiration');
+        if (ends === null || expirations.length > 1)
+            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 };
     }
     catch {
         return null;
@@ -94,6 +105,10 @@ export function requestPersistentRoomAdmission(opts) {
                     finish(new Error('the group invitation names conflicting rooms'));
                     return;
                 }
+                // Two signed copies that disagree on when the room ends: the earlier
+                // 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;
                 admission = decoded;
             }, () => {
                 if (admission)

package/llms.txt

@@ -66,6 +66,9 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `hostRoomInvitation(opts)` / `requestRoomAdmission(opts)` - the live desk, both sides
 - `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
+- `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
 
 ### Epochs (removal by rekey)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/fold-kit",
-  "version": "0.2.0",
+  "version": "0.3.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",