@forgesworn/fold-kit 0.1.0 → 0.3.0

package/README.md

@@ -93,7 +93,10 @@ the rest).
   `parseRoomPolicy` - the legacy v1 join URL and room id/key derivation
 - `createDeviceCredential`, `verifyDeviceCredential`,
   `PERSON_CREDENTIAL_MAX_SECONDS` - room-scope and person-scope device
-  credentials
+  credentials. `createDeviceCredential` throws `RestampedCredentialExpiryError`
+  for a person-scope credential a restamping signer would make unverifiable
+  everywhere (see CHANGELOG.md) - catch it and retry with a shorter
+  `expiresAt` margin
 - `issueKindredProof`, `evaluateAccess` - kindred-tier admission
 - `sanitiseDisplayName`, `MAX_DISPLAY_NAME_LENGTH` - defused display names
 - `safeRelayUrls`, `safeIceUrls`, `assertNetworkHintBounds`, and the related
@@ -110,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)
 
@@ -127,6 +139,28 @@ the rest).
 - `canonicalChannels`, `signChannels`, `verifyChannels`, `CHANNEL_NAME`,
   `RESERVED_CHANNELS` - the authority's signed channel list
 
+### Scoped labels and sub-key certificates (a consuming app's own keys)
+
+- `deriveScoped` - derive an app-defined `{ id, key }` pair from an epoch key
+  under an app's own labelled namespace (e.g. `myapp/v1/board/<id>/update`),
+  so an app can ride the same epoch as the roster and the chat - and rotate
+  on the same rekey - without ever deriving a key that could be mistaken for
+  a KithMoot channel. Refuses this kit's own protocol namespace and any
+  label outside `SCOPED_LABEL_PATTERN`.
+- `createSubKeyCertificate`, `verifySubKeyCertificate`,
+  `SUB_KEY_CERTIFICATE_SCOPE` - a small, locally-signed statement that a
+  credentialled device minted a particular app-derived key (a `deriveScoped`
+  output, typically) for a particular scoped id. Rides inside a signed
+  message's ciphertext alongside the device credential it depends on; never
+  published on its own, and never accepted by `verifyDeviceCredential` (its
+  `scope: "sub"` is a value that function already refuses). Verification is
+  strict and canonical: exactly four two-element tags in a fixed order,
+  empty `content`, an `expiration` in canonical decimal form compared as the
+  exact tag string (not numerically) against the device credential passed
+  in - `verifySubKeyCertificate` reads that credential's own `device` and
+  `expiration` tags itself, rather than trusting a caller to have copied
+  them out correctly.
+
 ### Channel (main entry, and `deriveChannel` only)
 
 - `deriveChannel`, `CHANNEL_ID_INFO`, `CHANNEL_KEY_INFO`,
@@ -167,6 +201,7 @@ npm test            # run the Vitest suite, including both vector files
 npm run typecheck    # type-check src/ and test/ (matching KithMoot, vectors/ is not tsc-checked)
 npm run vectors      # run only the vector-verification suites
 npm run diff-source  # compare moved modules against the pinned source commit (needs FOLD_KIT_SOURCE_DIR)
+npm run generate-fold # regenerate vectors/fold-vectors.json (needs a prior build)
 npm run bundle-check # esbuild browser bundle check (needs a prior build)
 npm run check        # typecheck + test + diff-source
 ```

package/dist/credential.d.ts

@@ -28,6 +28,22 @@ export interface CreateCredentialOptions {
 }
 /** The longest a person-scoped credential may run. A phone that leaves the house is better at seven days. */
 export declare const PERSON_CREDENTIAL_MAX_SECONDS: number;
+/**
+ * Thrown by `createDeviceCredential` when a remote signer's restamped
+ * `created_at` would make the requested expiry run longer than 30 days from
+ * it - see the comment at the throw site, and forgesworn/kithmoot issue 205
+ * (CHANGELOG.md has the full writeup and a link).
+ * Typed (rather than a plain `Error`) so a caller can distinguish this from
+ * the other, unrelated failure modes above it (wrong key, wrong terms, bad
+ * signature) and retry with a shorter margin specifically in this case.
+ */
+export declare class RestampedCredentialExpiryError extends Error {
+    /** How far over the 30-day cap the signed `created_at` pushed the
+     *  requested expiry, in seconds. Always positive. A caller retrying with
+     *  a shorter margin needs to shorten by at least this much. */
+    readonly overBySeconds: number;
+    constructor(overBySeconds: number);
+}
 /**
  * Authorise a device to act for a participant in one room, until an expiry.
  *

package/dist/credential.js

@@ -3,6 +3,26 @@ import { verifyEventUncached } from './verify.js';
 import { hexEquals, normaliseHex } from './hex.js';
 /** The longest a person-scoped credential may run. A phone that leaves the house is better at seven days. */
 export const PERSON_CREDENTIAL_MAX_SECONDS = 30 * 24 * 60 * 60;
+/**
+ * Thrown by `createDeviceCredential` when a remote signer's restamped
+ * `created_at` would make the requested expiry run longer than 30 days from
+ * it - see the comment at the throw site, and forgesworn/kithmoot issue 205
+ * (CHANGELOG.md has the full writeup and a link).
+ * Typed (rather than a plain `Error`) so a caller can distinguish this from
+ * the other, unrelated failure modes above it (wrong key, wrong terms, bad
+ * signature) and retry with a shorter margin specifically in this case.
+ */
+export class RestampedCredentialExpiryError extends Error {
+    /** How far over the 30-day cap the signed `created_at` pushed the
+     *  requested expiry, in seconds. Always positive. A caller retrying with
+     *  a shorter margin needs to shorten by at least this much. */
+    overBySeconds;
+    constructor(overBySeconds) {
+        super('the signer restamped created_at, and the requested expiry now runs longer than 30 days from it');
+        this.name = 'RestampedCredentialExpiryError';
+        this.overBySeconds = overBySeconds;
+    }
+}
 /**
  * Authorise a device to act for a participant in one room, until an expiry.
  *
@@ -58,6 +78,18 @@ export async function createDeviceCredential(opts) {
     if (!verifyEventUncached(signed)) {
         throw new Error('the signer returned a credential that does not verify');
     }
+    // forgesworn/kithmoot#205: a remote signer (a bunker, a phone) may restamp
+    // `created_at` to its own, earlier clock. `verifyDeviceCredential` measures
+    // the 30-day cap from the SIGNED `created_at`, not from `now` above - so a
+    // person credential requested near the cap can come back already unable to
+    // verify anywhere ("longer than 30 days"), even though nothing here was
+    // asked for more than 30 days. Re-check with the verifier's own
+    // measurement and fail loudly at mint time, rather than handing back a
+    // credential doomed to be refused everywhere it is presented. Callers that
+    // hit this can retry with a shorter `expiresAt` margin.
+    if (person && opts.expiresAt - signed.created_at > PERSON_CREDENTIAL_MAX_SECONDS) {
+        throw new RestampedCredentialExpiryError(opts.expiresAt - signed.created_at - PERSON_CREDENTIAL_MAX_SECONDS);
+    }
     return signed;
 }
 /**

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

@@ -5,8 +5,12 @@ export { localIdentity } from './identity.js';
 export { KINDS } from './kinds.js';
 export type { DeviceCredential, AccessTier, AgentRule, RoomPolicy, KindredProof } from './types.js';
 export type { RelayTransport } from './transport.js';
-export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, } from './credential.js';
+export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
 export type { CreateCredentialOptions, VerifyResult } from './credential.js';
+export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
+export type { ScopedKeys } from './scoped.js';
+export { createSubKeyCertificate, verifySubKeyCertificate, SUB_KEY_CERTIFICATE_SCOPE, } from './sub-cert.js';
+export type { CreateSubKeyCertificateOptions, VerifySubKeyCertificateOptions, VerifySubKeyCertificateResult, } from './sub-cert.js';
 export { generateRoomSecret, deriveRoom, encodeJoinUrl, decodeJoinUrl, parseRoomPolicy, ROOM_LABELS, } from './room.js';
 export { MAX_RELAY_HINTS, MAX_ICE_HINTS, MAX_NETWORK_HINT_LENGTH, isSafeRelayUrl, safeRelayUrls, isSafeIceUrl, safeIceUrls, assertNetworkHintBounds, } from './network-hints.js';
 export { sanitiseDisplayName, MAX_DISPLAY_NAME_LENGTH } from './display-name.js';
@@ -16,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

@@ -4,13 +4,16 @@ export { hexEquals, normaliseHex } from './hex.js';
 export { verifyEventUncached, boundedEventVerifier } from './verify.js';
 export { localIdentity } from './identity.js';
 export { KINDS } from './kinds.js';
-export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, } from './credential.js';
+export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
+export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
+export { createSubKeyCertificate, verifySubKeyCertificate, SUB_KEY_CERTIFICATE_SCOPE, } from './sub-cert.js';
 export { generateRoomSecret, deriveRoom, encodeJoinUrl, decodeJoinUrl, parseRoomPolicy, ROOM_LABELS, } from './room.js';
 export { MAX_RELAY_HINTS, MAX_ICE_HINTS, MAX_NETWORK_HINT_LENGTH, isSafeRelayUrl, safeRelayUrls, isSafeIceUrl, safeIceUrls, assertNetworkHintBounds, } from './network-hints.js';
 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/dist/scoped.d.ts

@@ -0,0 +1,67 @@
+import type { EpochKeys } from './epoch.js';
+/**
+ * Per-app scoped labels, derived from an epoch key (kit T3.1).
+ *
+ * A consuming app (a board tool, a task list, anything that rides a
+ * KithMoot-derived circle) needs its own payload keys and stream ids that
+ * live under the same epoch as the roster and the chat, without ever
+ * colliding with a KithMoot channel key or being mistaken for one. Sharing
+ * one epoch, rather than deriving a second independent secret, is what lets
+ * a board and a room use the same link and the same removal: both derive
+ * from the same epoch key, so both move together on a rekey.
+ *
+ * `deriveScoped` is deliberately NOT `deriveChannel`: a channel name is a
+ * KithMoot registry concept, signed off by the room's authority
+ * (`epoch.ts`'s `signChannels`) and rendered to members as a place to chat.
+ * An app's own scoped keys are neither: nobody signs off on them, and they
+ * are never shown as a channel. Reusing `deriveChannel` for them would let
+ * an app-chosen string collide with a real channel name, or a channel name
+ * collide with an app's payload key, so this is its own derivation under
+ * its own info strings.
+ *
+ * `label` MUST NOT start with this kit's own protocol namespace (see
+ * `KITHMOOT_NAMESPACE_PREFIX` below) - that namespace belongs to this kit's
+ * own derivations (`EPOCH_ID_INFO`, `CHANNEL_ID_INFO`, and so on), and
+ * refusing the prefix here means no app label can ever be mistaken for one
+ * of this kit's own, whatever an app supplies. `label` MUST match
+ * `^[a-z0-9-]{1,64}/v[0-9]{1,9}/[\x21-\x7e]{1,200}$`: a lower-case app
+ * namespace of 1 to 64 bytes, a version segment of 1 to 9 digits (an app's
+ * label shape is itself something it may need to change - this pins wire
+ * compatibility label by label, not by fiat), then 1 to 200 printable-ASCII
+ * bytes naming what the label is for. The namespace and version bounds are
+ * deliberately tight - an app label is always a short, fixed, hand-written
+ * string, never derived from untrusted input - so an unbounded namespace or
+ * version segment (as an earlier revision allowed) is refused rather than
+ * accepted and merely hashed away: nothing here needs to parse a namespace
+ * or version number back out of a label, but a caller building one by
+ * concatenation from attacker-influenced text should get a small, cheap
+ * refusal rather than an expensive regex match over untrusted length.
+ *
+ * `ikm` is the epoch KEY, never the epoch id: publishing a scoped id (which
+ * a relay necessarily sees as a `d` tag) must reveal nothing about any
+ * other scoped key derived from the same epoch, matching `deriveRoom` and
+ * `deriveChannel`'s own reasoning for deriving from the room/channel KEY.
+ * No salt, matching `deriveEpoch` and `deriveChannel`.
+ */
+export declare const SCOPED_LABEL_PATTERN: RegExp;
+/** A derived id and key for one app-defined purpose under one epoch. */
+export interface ScopedKeys {
+    /** Lower-case hex, 32 bytes. Suitable as a `d` tag or any other public
+     *  identifier a relay is expected to see. */
+    id: string;
+    /** 32 bytes. A NIP-44 conversation key, an envelope key, an HKDF salt for
+     *  a further derivation - whatever the label's owner needs a secret for. */
+    key: Uint8Array;
+}
+/**
+ * `{ id, key } = HKDF-SHA256(ikm = epoch.key, info = label + "/id" | label +
+ * "/key", 32)`, no salt.
+ *
+ * Refuses a label in this kit's own protocol namespace, and any label that
+ * does not match `SCOPED_LABEL_PATTERN`. Two different labels always derive
+ * to two different (id, key) pairs (barring an HKDF collision); the same
+ * label under two different epoch keys always derives to two different
+ * pairs too, which is what lets a rekey rotate every scoped key an app
+ * derived from the old epoch.
+ */
+export declare function deriveScoped(epoch: EpochKeys, label: string): ScopedKeys;

package/dist/scoped.js

@@ -0,0 +1,83 @@
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha2';
+/**
+ * Per-app scoped labels, derived from an epoch key (kit T3.1).
+ *
+ * A consuming app (a board tool, a task list, anything that rides a
+ * KithMoot-derived circle) needs its own payload keys and stream ids that
+ * live under the same epoch as the roster and the chat, without ever
+ * colliding with a KithMoot channel key or being mistaken for one. Sharing
+ * one epoch, rather than deriving a second independent secret, is what lets
+ * a board and a room use the same link and the same removal: both derive
+ * from the same epoch key, so both move together on a rekey.
+ *
+ * `deriveScoped` is deliberately NOT `deriveChannel`: a channel name is a
+ * KithMoot registry concept, signed off by the room's authority
+ * (`epoch.ts`'s `signChannels`) and rendered to members as a place to chat.
+ * An app's own scoped keys are neither: nobody signs off on them, and they
+ * are never shown as a channel. Reusing `deriveChannel` for them would let
+ * an app-chosen string collide with a real channel name, or a channel name
+ * collide with an app's payload key, so this is its own derivation under
+ * its own info strings.
+ *
+ * `label` MUST NOT start with this kit's own protocol namespace (see
+ * `KITHMOOT_NAMESPACE_PREFIX` below) - that namespace belongs to this kit's
+ * own derivations (`EPOCH_ID_INFO`, `CHANNEL_ID_INFO`, and so on), and
+ * refusing the prefix here means no app label can ever be mistaken for one
+ * of this kit's own, whatever an app supplies. `label` MUST match
+ * `^[a-z0-9-]{1,64}/v[0-9]{1,9}/[\x21-\x7e]{1,200}$`: a lower-case app
+ * namespace of 1 to 64 bytes, a version segment of 1 to 9 digits (an app's
+ * label shape is itself something it may need to change - this pins wire
+ * compatibility label by label, not by fiat), then 1 to 200 printable-ASCII
+ * bytes naming what the label is for. The namespace and version bounds are
+ * deliberately tight - an app label is always a short, fixed, hand-written
+ * string, never derived from untrusted input - so an unbounded namespace or
+ * version segment (as an earlier revision allowed) is refused rather than
+ * accepted and merely hashed away: nothing here needs to parse a namespace
+ * or version number back out of a label, but a caller building one by
+ * concatenation from attacker-influenced text should get a small, cheap
+ * refusal rather than an expensive regex match over untrusted length.
+ *
+ * `ikm` is the epoch KEY, never the epoch id: publishing a scoped id (which
+ * a relay necessarily sees as a `d` tag) must reveal nothing about any
+ * other scoped key derived from the same epoch, matching `deriveRoom` and
+ * `deriveChannel`'s own reasoning for deriving from the room/channel KEY.
+ * No salt, matching `deriveEpoch` and `deriveChannel`.
+ */
+export const SCOPED_LABEL_PATTERN = /^[a-z0-9-]{1,64}\/v[0-9]{1,9}\/[\x21-\x7e]{1,200}$/;
+/** See the comment at its one use site in `deriveScoped`. */
+const KITHMOOT_NAMESPACE_PREFIX = 'kithmoot' + '/';
+function hex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * `{ id, key } = HKDF-SHA256(ikm = epoch.key, info = label + "/id" | label +
+ * "/key", 32)`, no salt.
+ *
+ * Refuses a label in this kit's own protocol namespace, and any label that
+ * does not match `SCOPED_LABEL_PATTERN`. Two different labels always derive
+ * to two different (id, key) pairs (barring an HKDF collision); the same
+ * label under two different epoch keys always derives to two different
+ * pairs too, which is what lets a rekey rotate every scoped key an app
+ * derived from the old epoch.
+ */
+export function deriveScoped(epoch, label) {
+    // Built by concatenation, deliberately not as one string literal: this
+    // kit's `src/labels.test.ts` scans src/*.ts for every literal wire-format
+    // label this kit's own protocol owns, and freezes the exact set found.
+    // This check needs the same prefix at runtime, but it names that
+    // namespace in order to refuse it, rather than adding a new label of its
+    // own - so it is assembled at call time instead of appearing in the
+    // source as a scannable literal that test would otherwise pick up.
+    if (label.startsWith(KITHMOOT_NAMESPACE_PREFIX)) {
+        throw new Error('a scoped label may not start with this kit\'s own protocol namespace');
+    }
+    if (!SCOPED_LABEL_PATTERN.test(label)) {
+        throw new Error('scoped label must match ^[a-z0-9-]{1,64}/v[0-9]{1,9}/[\\x21-\\x7e]{1,200}$');
+    }
+    if (epoch.key.length !== 32)
+        throw new Error('epoch key must be 32 bytes');
+    const id = hex(hkdf(sha256, epoch.key, undefined, `${label}/id`, 32));
+    const key = hkdf(sha256, epoch.key, undefined, `${label}/key`, 32);
+    return { id, key };
+}

package/dist/sub-cert.d.ts

@@ -0,0 +1,117 @@
+import type { ParticipantIdentity } from './identity.js';
+import type { DeviceCredential } from './types.js';
+/**
+ * Sub-key certificates (kit T3.3).
+ *
+ * A device credential (`credential.ts`) says a device may act for a
+ * participant, in one room or everywhere. An app that signs its own traffic
+ * under a further per-scope key - a board's per-epoch signing key, say,
+ * derived from the epoch key and never held anywhere but derived on demand
+ * (see `scoped.ts`) - needs a second, narrower statement: that THIS
+ * credentialled device is the one that minted THIS particular sub-key, for
+ * THIS particular scoped id. Without it, a relay (or a receiver) has no way
+ * to tell a sub-key's traffic apart from a stranger who also derived a key
+ * and started signing with it - the sub-key is not itself proof of anything.
+ *
+ * The certificate is never published on its own: it rides inside a signed
+ * message's ciphertext, alongside the device credential it depends on, so a
+ * relay only ever sees the sub-key's signature on outer events and never
+ * learns which credentialled device stands behind it.
+ *
+ * Deliberately its own kind-20460 event with `scope: "sub"`, not a variant
+ * `verifyDeviceCredential` accepts: `verifyDeviceCredential` already refuses
+ * any `scope` it does not recognise (`credential.ts`, "unknown scope"), so a
+ * sub-key certificate can never be mistaken for a room or person credential
+ * by the existing verifier, and does not need that function to change at
+ * all. Its `device` tag also means something different here - the sub-key
+ * being certified, not a device being authorised - so folding it into
+ * `verifyDeviceCredential`'s shape would only invite the two to be confused.
+ *
+ * Exactly four tags, in this fixed order, each exactly `[name, value]`: `d`
+ * (the scoped signer id this certificate is for), `device` (the sub-key
+ * pubkey), `expiration` (MUST equal the accompanying device credential's
+ * `expiration`, compared as the exact tag string - a sub-key certificate
+ * never outlives the credential that backs it, and never gets its own
+ * independent expiry a caller could set longer by mistake, nor a
+ * differently-formatted but numerically-equal one), `scope` (always
+ * `"sub"`). `content` MUST be the empty string, matching `credential.ts`'s
+ * own convention.
+ */
+export declare const SUB_KEY_CERTIFICATE_SCOPE = "sub";
+export interface CreateSubKeyCertificateOptions {
+    /** The credentialled device: the same key a device credential names in
+     *  its `device` tag. Signs the certificate. */
+    identity: ParticipantIdentity;
+    /** The scoped id this certificate is for - typically
+     *  `deriveScoped(epoch, '<app>/v1/.../signer').id`. Must be 32-byte hex. */
+    signerId: string;
+    /** The sub-key pubkey being certified. Must be 32-byte hex (x-only). */
+    subKeyPubkey: string;
+    /** MUST equal the accompanying device credential's `expiration` exactly.
+     *  A safe integer, strictly in the future of `now` (or the real clock). */
+    expiresAt: number;
+    /** Injectable clock, in unix seconds. Defaults to the real one. */
+    now?: () => number;
+}
+/**
+ * Mint a sub-key certificate. Asynchronous for the same reason
+ * `createDeviceCredential` is: the identity may be a remote signer.
+ *
+ * Validates its own inputs before asking the signer to sign anything: a
+ * bad `signerId`/`subKeyPubkey` shape or a non-future `expiresAt` is a
+ * caller bug, not something worth turning into a certificate a verifier
+ * would refuse for a more confusing reason downstream.
+ *
+ * Checks what the signer handed back against what was asked for, exactly as
+ * `createDeviceCredential` does, so a signer that stamps its own fields (a
+ * different `created_at` is fine and deliberately not compared; anything
+ * else is not) cannot silently hand back a certificate for something else.
+ */
+export declare function createSubKeyCertificate(opts: CreateSubKeyCertificateOptions): Promise<DeviceCredential>;
+export type VerifySubKeyCertificateResult = {
+    ok: true;
+    device: string;
+    subKeyPubkey: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface VerifySubKeyCertificateOptions {
+    /** The scoped signer id the certificate must name in its `d` tag. */
+    signerId: string;
+    /**
+     * The device credential this certificate depends on, ALREADY VERIFIED by
+     * the caller (a successful `verifyDeviceCredential` call). This function
+     * reads that credential's `device` and `expiration` tags itself, rather
+     * than trusting a caller to have copied them out correctly: the
+     * certificate's signer (`cert.pubkey`) must equal the credential's
+     * `device` tag exactly, and the certificate's `expiration` tag must equal
+     * the credential's `expiration` tag as the EXACT SAME STRING (not merely
+     * the same number) - so a certificate cannot outlive, or be reissued
+     * under a differently-formatted equivalent of, the credential backing it.
+     */
+    credential: DeviceCredential;
+    /** The pubkey that signed the message this certificate rode in on - the
+     *  sub-key. The certificate's `device` tag must equal it. */
+    subKeyPubkey: string;
+    now: number;
+    /** The containing message's sign time: the certificate's own `created_at`
+     *  must not be later than `at + skewSeconds`. Omit `at` entirely to skip
+     *  this bound (a caller with no message context yet, such as a vector,
+     *  may not have one). Giving `at` without `skewSeconds` does NOT relax
+     *  the bound to unlimited skew - `skewSeconds` then defaults to `0`, a
+     *  certificate must not be minted after the message at all. */
+    at?: number;
+    skewSeconds?: number;
+}
+/**
+ * Verify a sub-key certificate: that the credentialled device named by
+ * `credential` certified `subKeyPubkey` as its sub-key for `signerId`, with
+ * an expiry that matches `credential` exactly and a mint time no later than
+ * the message it rode in on.
+ *
+ * Every check below is cheap-first, strict and canonical, and never throws,
+ * matching `verifyDeviceCredential`; the signature is checked last, since it
+ * is the most expensive and every tag check above invalidates it anyway.
+ */
+export declare function verifySubKeyCertificate(cert: DeviceCredential, opts: VerifySubKeyCertificateOptions): VerifySubKeyCertificateResult;

package/dist/sub-cert.js

@@ -0,0 +1,192 @@
+import { KINDS } from './kinds.js';
+import { verifyEventUncached } from './verify.js';
+import { hexEquals, normaliseHex } from './hex.js';
+/**
+ * Sub-key certificates (kit T3.3).
+ *
+ * A device credential (`credential.ts`) says a device may act for a
+ * participant, in one room or everywhere. An app that signs its own traffic
+ * under a further per-scope key - a board's per-epoch signing key, say,
+ * derived from the epoch key and never held anywhere but derived on demand
+ * (see `scoped.ts`) - needs a second, narrower statement: that THIS
+ * credentialled device is the one that minted THIS particular sub-key, for
+ * THIS particular scoped id. Without it, a relay (or a receiver) has no way
+ * to tell a sub-key's traffic apart from a stranger who also derived a key
+ * and started signing with it - the sub-key is not itself proof of anything.
+ *
+ * The certificate is never published on its own: it rides inside a signed
+ * message's ciphertext, alongside the device credential it depends on, so a
+ * relay only ever sees the sub-key's signature on outer events and never
+ * learns which credentialled device stands behind it.
+ *
+ * Deliberately its own kind-20460 event with `scope: "sub"`, not a variant
+ * `verifyDeviceCredential` accepts: `verifyDeviceCredential` already refuses
+ * any `scope` it does not recognise (`credential.ts`, "unknown scope"), so a
+ * sub-key certificate can never be mistaken for a room or person credential
+ * by the existing verifier, and does not need that function to change at
+ * all. Its `device` tag also means something different here - the sub-key
+ * being certified, not a device being authorised - so folding it into
+ * `verifyDeviceCredential`'s shape would only invite the two to be confused.
+ *
+ * Exactly four tags, in this fixed order, each exactly `[name, value]`: `d`
+ * (the scoped signer id this certificate is for), `device` (the sub-key
+ * pubkey), `expiration` (MUST equal the accompanying device credential's
+ * `expiration`, compared as the exact tag string - a sub-key certificate
+ * never outlives the credential that backs it, and never gets its own
+ * independent expiry a caller could set longer by mistake, nor a
+ * differently-formatted but numerically-equal one), `scope` (always
+ * `"sub"`). `content` MUST be the empty string, matching `credential.ts`'s
+ * own convention.
+ */
+export const SUB_KEY_CERTIFICATE_SCOPE = 'sub';
+/** Lower-case or upper-case 32-byte hex - the shape of every pubkey and
+ *  scoped id this module handles. Matches `epoch.ts`'s own `HEX64`. */
+const HEX64 = /^[0-9a-f]{64}$/i;
+/** A canonical decimal unix timestamp: no leading/trailing whitespace, no
+ *  sign, no `0x` prefix, no fraction, and no leading zeros (other than the
+ *  single digit `"0"` itself, which is not a legal expiry here since it
+ *  refuses at "expired" but is excluded from ambiguity regardless). Matches
+ *  `expiresAt` values `credential.ts` itself would produce with `String()`
+ *  on a safe non-negative integer. */
+const CANONICAL_DECIMAL = /^(0|[1-9][0-9]*)$/;
+function requireHex64(value, what) {
+    if (!HEX64.test(value))
+        throw new Error(`${what} must be 32-byte hex`);
+}
+/**
+ * Mint a sub-key certificate. Asynchronous for the same reason
+ * `createDeviceCredential` is: the identity may be a remote signer.
+ *
+ * Validates its own inputs before asking the signer to sign anything: a
+ * bad `signerId`/`subKeyPubkey` shape or a non-future `expiresAt` is a
+ * caller bug, not something worth turning into a certificate a verifier
+ * would refuse for a more confusing reason downstream.
+ *
+ * Checks what the signer handed back against what was asked for, exactly as
+ * `createDeviceCredential` does, so a signer that stamps its own fields (a
+ * different `created_at` is fine and deliberately not compared; anything
+ * else is not) cannot silently hand back a certificate for something else.
+ */
+export async function createSubKeyCertificate(opts) {
+    requireHex64(opts.signerId, 'signerId');
+    requireHex64(opts.subKeyPubkey, 'subKeyPubkey');
+    const now = (opts.now ?? (() => Math.floor(Date.now() / 1000)))();
+    if (!Number.isSafeInteger(opts.expiresAt) || opts.expiresAt <= now) {
+        throw new Error('expiresAt must be a safe integer unix timestamp in the future');
+    }
+    const unsigned = {
+        kind: KINDS.CREDENTIAL,
+        created_at: now,
+        tags: [
+            ['d', opts.signerId],
+            ['device', opts.subKeyPubkey],
+            ['expiration', String(opts.expiresAt)],
+            ['scope', SUB_KEY_CERTIFICATE_SCOPE],
+        ],
+        content: '',
+    };
+    const signed = await opts.identity.signEvent(unsigned);
+    if (!hexEquals(signed.pubkey, opts.identity.pubkey)) {
+        throw new Error('the signer returned a certificate signed by a different key');
+    }
+    if (signed.kind !== unsigned.kind || signed.content !== unsigned.content) {
+        throw new Error('the signer returned a certificate for something else');
+    }
+    if (JSON.stringify(signed.tags) !== JSON.stringify(unsigned.tags)) {
+        throw new Error('the signer returned a certificate on different terms than it was asked for');
+    }
+    if (!verifyEventUncached(signed)) {
+        throw new Error('the signer returned a certificate that does not verify');
+    }
+    return signed;
+}
+/** Verified sub-key certificates, keyed on the whole signed event exactly as
+ *  `credential.ts`'s own bounded cache is: a Schnorr signature is
+ *  randomised, so the identical certificate can arrive carrying two
+ *  different valid signatures, and an id-keyed cache would refuse the
+ *  second. Kept separate from `credential.ts`'s cache because a sub-key
+ *  certificate and a device credential are verified under different rules
+ *  and neither should be able to poison the other's cache. */
+const verifiedSubKeyCertificates = new Set();
+function certificateSignature(cert) {
+    const whole = JSON.stringify([cert.id, cert.pubkey, cert.created_at, cert.kind, cert.tags, cert.content, cert.sig]);
+    if (verifiedSubKeyCertificates.has(whole))
+        return true;
+    if (!verifyEventUncached(cert))
+        return false;
+    verifiedSubKeyCertificates.add(whole);
+    if (verifiedSubKeyCertificates.size > 4_096)
+        verifiedSubKeyCertificates.delete(verifiedSubKeyCertificates.values().next().value);
+    return true;
+}
+/**
+ * Verify a sub-key certificate: that the credentialled device named by
+ * `credential` certified `subKeyPubkey` as its sub-key for `signerId`, with
+ * an expiry that matches `credential` exactly and a mint time no later than
+ * the message it rode in on.
+ *
+ * Every check below is cheap-first, strict and canonical, and never throws,
+ * matching `verifyDeviceCredential`; the signature is checked last, since it
+ * is the most expensive and every tag check above invalidates it anyway.
+ */
+export function verifySubKeyCertificate(cert, opts) {
+    if (cert.kind !== KINDS.CREDENTIAL)
+        return { ok: false, reason: 'wrong kind' };
+    if (cert.content !== '')
+        return { ok: false, reason: 'non-empty content' };
+    // Exactly four tags, in this fixed order, each exactly [name, value] (see
+    // the module comment): a certificate with an extra, missing or reordered
+    // tag, or an extra element tacked onto one tag, is refused before any of
+    // its values are even read, so nothing downstream can be tricked by
+    // content nobody here is looking for.
+    if (cert.tags.length !== 4)
+        return { ok: false, reason: 'wrong tag count' };
+    if (cert.tags.some((t) => t.length !== 2))
+        return { ok: false, reason: 'wrong tag shape' };
+    const [dTag, deviceTag, expirationTag, scopeTag] = cert.tags;
+    if (dTag[0] !== 'd')
+        return { ok: false, reason: 'wrong tag order' };
+    if (deviceTag[0] !== 'device')
+        return { ok: false, reason: 'wrong tag order' };
+    if (expirationTag[0] !== 'expiration')
+        return { ok: false, reason: 'wrong tag order' };
+    if (scopeTag[0] !== 'scope')
+        return { ok: false, reason: 'wrong tag order' };
+    if (scopeTag[1] !== SUB_KEY_CERTIFICATE_SCOPE)
+        return { ok: false, reason: 'wrong scope' };
+    const signerId = dTag[1];
+    if (!hexEquals(signerId, opts.signerId))
+        return { ok: false, reason: 'wrong signer' };
+    const subKeyPubkey = deviceTag[1];
+    if (!hexEquals(subKeyPubkey, opts.subKeyPubkey)) {
+        return { ok: false, reason: 'device tag does not match the message signer' };
+    }
+    const credentialDevice = opts.credential.tags.find((t) => t[0] === 'device')?.[1];
+    if (credentialDevice === undefined)
+        return { ok: false, reason: 'credential missing device tag' };
+    if (!hexEquals(cert.pubkey, credentialDevice))
+        return { ok: false, reason: 'wrong device' };
+    const expirationValue = expirationTag[1];
+    if (!CANONICAL_DECIMAL.test(expirationValue))
+        return { ok: false, reason: 'non-canonical expiration' };
+    const credentialExpiration = opts.credential.tags.find((t) => t[0] === 'expiration')?.[1];
+    if (credentialExpiration === undefined)
+        return { ok: false, reason: 'credential missing expiration tag' };
+    // Exact string comparison, not numeric: "1802582000" and "01802582000" (or
+    // any other non-canonical spelling of the same number) must not be
+    // treated as equal - CANONICAL_DECIMAL above already refuses the
+    // certificate's own tag if it is not canonical, so this compares two
+    // already-canonical-or-refused strings, catching a credential whose own
+    // tag differs even numerically-identically-formatted.
+    if (expirationValue !== credentialExpiration)
+        return { ok: false, reason: 'expiration does not match the credential' };
+    const expiresAt = Number(expirationValue);
+    if (expiresAt <= opts.now)
+        return { ok: false, reason: 'expired' };
+    if (opts.at !== undefined && cert.created_at > opts.at + (opts.skewSeconds ?? 0)) {
+        return { ok: false, reason: 'certificate minted after the message it rode in on' };
+    }
+    if (!certificateSignature(cert))
+        return { ok: false, reason: 'bad signature' };
+    return { ok: true, device: normaliseHex(cert.pubkey), subKeyPubkey: normaliseHex(subKeyPubkey) };
+}

package/llms.txt

@@ -49,6 +49,7 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `createDeviceCredential(opts)` → `Promise<DeviceCredential>` - room-scope or person-scope (`scope: 'person'`)
 - `verifyDeviceCredential(event, opts)` → `VerifyResult` - pass `acceptPerson: true` to accept a person-scope credential where a room credential is expected
 - `PERSON_CREDENTIAL_MAX_SECONDS` - 30-day cap on a person-scope credential
+- `RestampedCredentialExpiryError` - thrown by `createDeviceCredential` when a restamping signer would make a person-scope credential unverifiable everywhere; has `overBySeconds`; catch and retry with a shorter `expiresAt` margin (see CHANGELOG.md)
 - `issueKindredProof(opts)` → `KindredProof`
 - `evaluateAccess(policy, participant, proof, now, roomId)` → `{ admitted, reason }`
 - `sanitiseDisplayName(raw)` → `string | undefined`, `MAX_DISPLAY_NAME_LENGTH`
@@ -65,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)
 
@@ -77,6 +81,11 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `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`
 
+### Scoped labels and sub-key certificates
+
+- `deriveScoped(epoch, label)` → `{ id, key }` - HKDF from the epoch KEY under an app's own labelled namespace (e.g. `myapp/v1/board/<id>/update`); refuses this kit's own protocol namespace and any label outside `SCOPED_LABEL_PATTERN`
+- `createSubKeyCertificate(opts)` → `Promise<DeviceCredential>` / `verifySubKeyCertificate(event, opts)` → result - a locally-signed, never-published statement binding an app-derived key to the credentialled device that minted it; `scope: 'sub'` is a value `verifyDeviceCredential` already refuses, so the two forms can never be confused. `verifySubKeyCertificate` takes `opts.credential` (the already-verified device credential) and reads its `device`/`expiration` tags itself; verification is strict (exactly four two-element tags, empty content) and canonical (expiration compared as the exact tag string). `SUB_KEY_CERTIFICATE_SCOPE`.
+
 ### Channel derivation
 
 - `deriveChannel(roomId, roomKey, channel?)` → `{ id, key }` - a named channel's id/key, derived from the room key; `CHANNEL_ID_INFO`, `CHANNEL_KEY_INFO`, `MAX_CHANNEL_NAME_LENGTH`. The chat log and event codecs themselves stay in the consuming app.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/fold-kit",
-  "version": "0.1.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",
@@ -30,6 +30,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.typecheck.json",
     "diff-source": "node scripts/diff-source.mjs",
+    "generate-fold": "node scripts/generate-fold.mjs",
     "bundle-check": "node scripts/bundle-check.mjs",
     "tarball-smoke": "node scripts/tarball-smoke.mjs",
     "vectors": "vitest run vectors/",

package/vectors/circle-vectors.json

@@ -1758,7 +1758,7 @@
       {
         "name": "refused-over-30-days",
         "kind": "negative",
-        "note": "M15 (refused side): the real `createDeviceCredential`'s mint-time check passes (expiry is exactly 2592000 seconds past the requested `now`, not more) - but the injected identity restamps the signed event's `created_at` ten seconds earlier than `now`, so the credential that actually results runs 2592010 seconds from its own real `created_at`. `verifyDeviceCredential` refuses it on read.",
+        "note": "M15 (refused side); updated for forgesworn/kithmoot#205: the real createDeviceCredential now measures the same way verifyDeviceCredential does - against the SIGNED created_at, not the requested now - and throws RestampedCredentialExpiryError at mint time instead of returning a credential. output.event/output.result keep M15's original coverage: the exact over-cap event a pre-#205 mint would have returned (built deterministically, the same bytes as before), and verifyDeviceCredential's own refusal of it, which is unchanged by #205 (its measurement was already correct - only the mint side was checking the wrong clock).",
         "input": {
           "participantSkHex": "826f7335cca1f25633dbc6efc43131a651feb9b7d419c9b1fdc35b2e115d2180",
           "devicePubkey": "b4814eb28f92350f362af5eb7a1dc6b9bdd1d27e789f5d97ad3b8c7653753076",
@@ -1772,6 +1772,7 @@
           }
         },
         "output": {
+          "mintThrew": "the signer restamped created_at, and the requested expiry now runs longer than 30 days from it",
           "event": {
             "kind": 20460,
             "created_at": 1799989990,