@forgesworn/fold-kit 0.1.0 → 0.2.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
@@ -127,6 +130,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 +192,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/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';

package/dist/index.js

@@ -4,7 +4,9 @@ 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';

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`
@@ -77,6 +78,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.2.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,