@forgesworn/fold-kit 0.0.0-seed.0 → 0.2.0

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/dist/transport.d.ts

@@ -0,0 +1,24 @@
+import type { Event } from 'nostr-tools/pure';
+import type { Filter } from 'nostr-tools/filter';
+/**
+ * The relay transport seam the kit's codecs need: publish, subscribe, close.
+ *
+ * This is the kit's own declaration, not an import of KithMoot's
+ * `RelayTransport` (KithMoot's `src/relay-pool.ts`). The relay pool itself
+ * has not moved to the kit yet (see EXTRACTION.md): epoch, invitation and
+ * persistent-invitation only ever call `publish`/`subscribe`/`close` on the
+ * transport they are given, so the kit needs only that much of the shape,
+ * not KithMoot's richer `describe()`/`rekey()` extensions.
+ *
+ * A caller can pass KithMoot's `NostrRelayPool` (which implements a superset
+ * of this interface) straight through, or the kit's own `SimTransport`
+ * (`test/sim-relay.ts`), or any other implementation with the same three
+ * methods.
+ */
+export interface RelayTransport {
+    publish(event: Event): Promise<void>;
+    /** `via` is the relay URL that delivered the event, when the transport
+     *  knows it. */
+    subscribe(filters: Filter[], onEvent: (event: Event, via?: string) => void, onEose?: () => void): () => void;
+    close(): void;
+}

package/dist/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+import type { Event } from 'nostr-tools/pure';
+/** Circle-layer wire types: a subset of KithMoot's `src/types.ts`, copied
+ * byte-identical per declaration from the pinned source commit (see
+ * EXTRACTION.md). KithMoot's `types.ts` also defines roster, media and
+ * descriptor types that stay in KithMoot; those import `Reachability`
+ * (KithMoot's `src/reachability.ts`), which does not move here (see
+ * EXTRACTION.md's "What did not move" section). None of the types below
+ * need it. */
+/** A device credential is an ordinary signed Nostr event, never published bare. */
+export type DeviceCredential = Event;
+/** Kindred tiers, closest first: family, mutual verified bond, one-way
+ *  recognition, no requirement at all. */
+export type AccessTier = 'open' | 'ken' | 'kith' | 'kin';
+/** What a room requires of its agents. `owned-by-members`: an agent is
+ *  admitted to the roster only with a verified ownership proof from a
+ *  participant who is in the room. See `AgentOwnership`. */
+export type AgentRule = 'owned-by-members';
+/** A room's admission rule. `admitted` lists the issuer pubkeys the room
+ *  trusts to vouch for guests; irrelevant when `tier` is `open`. `agents`
+ *  is a separate rule about what an agent has to show; absent means
+ *  nothing, which is how every room worked before it existed. */
+export interface RoomPolicy {
+    tier: AccessTier;
+    admitted?: string[];
+    agents?: AgentRule;
+    /** When present, the only participants admitted, whatever the tier
+     *  says. A direct message is a room whose policy lists two. See
+     *  `docs/messages.md`. */
+    members?: string[];
+    /** A quiet room: its chat rides the kind 1059 firehose as dead drops to
+     *  keys derived from the epoch key, on a cadence, so a relay cannot tell
+     *  whether anything was said, by whom, or when. Only with `members`,
+     *  because everybody derives every member's keys. Rides here so that
+     *  everyone who joins agrees on how the room talks, exactly as they
+     *  agree on who may enter. See `quiet.ts`. */
+    quiet?: true;
+}
+/**
+ * A signed claim that `issuer` recognises `participant` at `tier` in `room`,
+ * until `expiresAt`. Never issued for `open`, since open needs no proof.
+ *
+ * `room` is what stops a proof being a bearer token: without it, one proof
+ * admits its holder to every room that happens to trust the same issuer, and
+ * an issuer who vouched for a guest at one moot has not vouched for them at
+ * all of them. The cost of that binding is stated plainly: a kindred proof is
+ * a room grant here, not a portable statement about a relationship, so an
+ * issuer mints one per room. In this protocol the party who vouches is the
+ * party who sent the join link, so it already knows the room id.
+ */
+export type KindredProof = {
+    tier: Exclude<AccessTier, 'open'>;
+    participant: string;
+    issuer: string;
+    /** The room id this proof is valid in. */
+    room: string;
+    /** 32 random bytes, hex, unique to this proof. Signed over, so two proofs
+     *  on identical terms are still distinguishable - which is what a revocation
+     *  list, or an audit, needs to name one of them. */
+    nonce: string;
+    sig: string;
+    expiresAt: number;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/verify.d.ts

@@ -0,0 +1,26 @@
+import { type Event } from 'nostr-tools/pure';
+/**
+ * Verify an event's signature, ignoring any cached verdict it arrives with.
+ *
+ * `verifyEvent` caches its result on the event object under `verifiedSymbol`
+ * and returns that cached value on any later call, without re-checking
+ * anything. The property is an own enumerable symbol, so it survives a
+ * shallow copy (`{ ...event }`, which is exactly how a caller might rebuild
+ * an event after editing a field) - and an attacker who hands us an object
+ * rather than a JSON string can simply set it themselves. Either way the
+ * signature check silently becomes a no-op.
+ *
+ * Every inbound event in this library goes through here rather than calling
+ * `verifyEvent` directly, so the defence cannot be forgotten by the next
+ * decoder somebody writes. The copy also keeps the caller's object
+ * unmodified: we never stamp a verdict onto something we did not sign.
+ */
+export declare function verifyEventUncached(event: Event): boolean;
+/**
+ * Keep relay fan-out from verifying the same signed event once per relay and
+ * replay. The cached value includes every signed field, so an object that
+ * reuses a known id while changing its body or signature is rejected. The
+ * fixed-size FIFO also prevents an untrusted relay from
+ * growing keeper memory without bound.
+ */
+export declare function boundedEventVerifier(limit?: number, verify?: (event: Event) => boolean): (event: Event) => boolean;

package/dist/verify.js

@@ -0,0 +1,46 @@
+import { verifyEvent, verifiedSymbol } from 'nostr-tools/pure';
+/**
+ * Verify an event's signature, ignoring any cached verdict it arrives with.
+ *
+ * `verifyEvent` caches its result on the event object under `verifiedSymbol`
+ * and returns that cached value on any later call, without re-checking
+ * anything. The property is an own enumerable symbol, so it survives a
+ * shallow copy (`{ ...event }`, which is exactly how a caller might rebuild
+ * an event after editing a field) - and an attacker who hands us an object
+ * rather than a JSON string can simply set it themselves. Either way the
+ * signature check silently becomes a no-op.
+ *
+ * Every inbound event in this library goes through here rather than calling
+ * `verifyEvent` directly, so the defence cannot be forgotten by the next
+ * decoder somebody writes. The copy also keeps the caller's object
+ * unmodified: we never stamp a verdict onto something we did not sign.
+ */
+export function verifyEventUncached(event) {
+    const unverified = { ...event };
+    delete unverified[verifiedSymbol];
+    return verifyEvent(unverified);
+}
+/**
+ * Keep relay fan-out from verifying the same signed event once per relay and
+ * replay. The cached value includes every signed field, so an object that
+ * reuses a known id while changing its body or signature is rejected. The
+ * fixed-size FIFO also prevents an untrusted relay from
+ * growing keeper memory without bound.
+ */
+export function boundedEventVerifier(limit = 8_192, verify = verifyEventUncached) {
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new Error('Event verification cache size must be a positive integer');
+    const verified = new Map();
+    return event => {
+        const cached = verified.get(event.id);
+        if (cached !== undefined) {
+            return cached === JSON.stringify([event.id, event.pubkey, event.created_at, event.kind, event.tags, event.content, event.sig]);
+        }
+        if (!verify(event))
+            return false;
+        verified.set(event.id, JSON.stringify([event.id, event.pubkey, event.created_at, event.kind, event.tags, event.content, event.sig]));
+        if (verified.size > limit)
+            verified.delete(verified.keys().next().value);
+        return true;
+    };
+}