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

package/README.md

@@ -5,12 +5,165 @@ per epoch, sealed to each device that stays; link invitations as
 capabilities; member removal by rekey; device credentials so a person
 approves a device once and it signs from then on.
 
-Fold-kit is being extracted from [KithMoot](https://github.com/forgesworn/kithmoot)
+Fold-kit is extracted from [KithMoot](https://github.com/forgesworn/kithmoot)
 so that other ForgeSworn clients can share one circle model. KithMoot's wire
-format does not change: every derivation label and event shape moves
-byte-identical and is pinned by known-answer vectors.
+format does not change: every derivation label and event shape moved
+byte-identical from the pinned source commit and is pinned by known-answer
+vectors (see EXTRACTION.md). Framework-free: owns no storage, UI, relay
+defaults or identity keys, and no relay I/O of its own - callers inject a
+transport.
 
-**Status: extraction in progress. No published package yet.**
+**Status:** T1 extraction complete (see EXTRACTION.md). Not yet published to
+npm under this API; pin an immutable Git commit until it is (see Install).
+KithMoot itself has not cut over to this kit yet - it still carries its own
+copy of these modules.
+
+## Install
+
+```bash
+npm install @forgesworn/fold-kit
+```
+
+Not yet published to npm. Until it is, pin an immutable Git commit:
+
+```json
+{
+  "dependencies": {
+    "@forgesworn/fold-kit": "github:forgesworn/fold-kit#<commit>"
+  }
+}
+```
+
+### Peer dependencies
+
+```json
+{
+  "peerDependencies": {
+    "nostr-tools": ">=2.24.2 <3",
+    "@noble/hashes": "^1.8.0",
+    "@noble/curves": "^2.0.1"
+  }
+}
+```
+
+Peers, not dependencies, so a consumer such as KithMoot keeps a single copy
+of `nostr-tools` (guarded by its own `overrides` and version-guard test) and
+of the noble libraries, at the same versions KithMoot already pins.
+`@noble/hashes` is pinned to its 1.x major only: its 2.x major changed its
+`hkdf` signature to reject a string `info` argument (this kit's HKDF calls
+pass strings) and its `exports` map no longer resolves the bare subpaths
+this kit and KithMoot both import without a `.js` suffix, so 2.x cannot
+satisfy this kit's imports as written.
+
+ESM only (`"type": "module"`). Node.js `>=22.13`.
+
+## Exports
+
+Two entry points: `@forgesworn/fold-kit` (everything) and
+`@forgesworn/fold-kit/lane` (just the lane helpers, for a consumer that only
+wants to classify a relay as `public`/`sheltered`/`direct` without pulling in
+the rest).
+
+### Identity, verification, hex
+
+- `hexEquals`, `normaliseHex` - constant-shape hex comparison and lower-casing
+- `verifyEventUncached`, `boundedEventVerifier` - Nostr event signature checks
+- `localIdentity`, `ParticipantIdentity`, `UnsignedEvent` - the signer seam
+  every codec below is built on
+
+### Wire kinds and types
+
+- `KINDS` - the circle layer's kind numbers (`CREDENTIAL`, `CHAT`,
+  `INVITATION_REQUEST`, `INVITATION_GRANT`, `INVITATION_RETIREMENT`,
+  `GROUP_INVITATION`, `ROOM_REKEY`, `EPOCH_REQUEST`, `EPOCH_GRANT`) - a
+  subset of KithMoot's full registry. `CHAT` (1460) is included because a
+  downstream app's own board events are designed to share KithMoot's chat
+  kind, so a relay cannot tell a board from a chat (see
+  docs/extraction-plan-excerpt.md).
+- `DeviceCredential`, `AccessTier`, `AgentRule`, `RoomPolicy`, `KindredProof` -
+  the link-layer wire types
+- `RelayTransport` - the transport seam (`publish`/`subscribe`/`close`) every
+  codec below that talks to a relay takes as a dependency. This kit declares
+  its own interface rather than importing KithMoot's relay pool, which has
+  not moved here (see EXTRACTION.md).
+
+### Rooms, credentials, access
+
+- `generateRoomSecret`, `deriveRoom`, `encodeJoinUrl`, `decodeJoinUrl`,
+  `parseRoomPolicy` - the legacy v1 join URL and room id/key derivation
+- `createDeviceCredential`, `verifyDeviceCredential`,
+  `PERSON_CREDENTIAL_MAX_SECONDS` - room-scope and person-scope device
+  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
+  `MAX_*` bounds - link envelope network hints
+
+### Links and invitations
+
+- `parseRoomLink`, `encodeRoomLink`, `RoomLink` - the v1/v2/v3 link envelope
+- `createRoomInvitation`, `roomInvitation`, `deriveInvitationId`,
+  `encodeInvitationRequest`, `decodeInvitationRequest`,
+  `verifyInvitationDelegation`, `encodeInvitationGrant`,
+  `decodeRoomAdmissionGrant`, `encodeInvitationRetirement`,
+  `decodeInvitationRetirementNotice`, `hostRoomInvitation`,
+  `requestRoomAdmission` - the v2 live rendezvous invitation, its delegation
+  chain and retirement
+- `encodePersistentInvitation`, `decodePersistentInvitation`,
+  `requestPersistentRoomAdmission` - the v3 stored group invitation (1463)
+
+### Epochs (removal by rekey)
+
+- `deriveEpoch`, `generateEpochSecret` - per-epoch id/key derivation
+- `encodeRekeyEvent`, `peekRekeyEvent`, `decodeRekeyEvent` - the durable
+  rekey notice (1462), sealed per remaining device
+- `encodeEpochRequest`, `decodeEpochRequest`, `encodeEpochGrant`,
+  `decodeEpochGrant`, `epochRequestAdmission`, `deriveEpochRequestKey` -
+  catch-up for a device that missed a rekey
+- `hostRoomEpoch`, `requestRoomEpoch`, `EpochRefusedError` - the live
+  request/grant desk
+- `canonicalAdmins`, `signAdmins`, `verifyAdmins` - the authority's signed
+  admin list
+- `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`,
+  `MAX_CHANNEL_NAME_LENGTH` - a named channel's id/key, derived from the room
+  key. `ChatLog` and the chat event codecs stay in KithMoot; only the
+  derivation moved.
+
+### Lane (`@forgesworn/fold-kit/lane`)
+
+- `LANES`, `LANE_MEANING`, `LANE_LABEL`, `LANE_GLYPH`, `isLane`,
+  `laneOfRelayUrl`, `laneOfRelays`, `weakestLane`, `isDowngrade` - classifies
+  a relay as `public`, `sheltered` or `direct`
 
 ## How it relates to its siblings
 
@@ -23,6 +176,29 @@ byte-identical and is pinned by known-answer vectors.
   collaborative documents, where a wrap per recipient per message is too
   costly.
 
+Nothing is shared in code between the three today: the key models are
+incompatible (a static epoch secret with sealed rekeys here, versus a
+deterministic reseed from a root in covey-kit), the trust models differ
+(pinned authority here versus caller-enforced roles in covey-kit), and
+covey-kit/roost-kit pin a different `nostr-tools` version than this kit and
+KithMoot share.
+
+## Development
+
+```bash
+npm install
+npm run build       # compile TypeScript into dist/
+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
+```
+
+There is no separate lint script.
+
 ## Licence
 
 MIT

package/dist/access.d.ts

@@ -0,0 +1,34 @@
+import type { KindredProof, RoomPolicy } from './types.js';
+export interface IssueKindredProofOptions {
+    /** The issuer's secret key. */
+    hostSk: Uint8Array;
+    participant: string;
+    tier: KindredProof['tier'];
+    /** The room this proof admits the participant to. */
+    roomId: string;
+    /** Unix seconds. */
+    expiresAt: number;
+    /** 32 bytes, hex. Supply one only to make a proof reproducible - the
+     *  interop vectors do; everything else wants the random default. */
+    nonce?: string;
+}
+/** Vouch for a participant at a tier, in one room, until an expiry. */
+export declare function issueKindredProof(opts: IssueKindredProofOptions): KindredProof;
+/**
+ * Decide whether `participant` may join a room under `policy`.
+ *
+ * `ken` is one-way recognition - pinning someone's key from an authoritative
+ * source, with no bond back - so it never satisfies a `kith` gate. `kin` is
+ * closer than `kith` and does. Checks run cheapest first and never throw:
+ * participant match, room match, expiry, issuer trust, tier, then the schnorr
+ * verification last, since it is the most expensive.
+ */
+export declare function evaluateAccess(policy: RoomPolicy, participant: string, proof: KindredProof | undefined, now: number, roomId: string): {
+    admitted: boolean;
+    reason: string;
+};
+/** Every wire-format literal this module owns (each one a kithmoot protocol string), frozen for
+ *  `src/labels.test.ts`, which checks each module against its own exported
+ *  list rather than scanning file text for matching comments. Pure data -
+ *  adding this export changes no runtime behaviour. */
+export declare const ACCESS_LABELS: readonly ["kithmoot/v1/kindred:"];

package/dist/access.js

@@ -0,0 +1,102 @@
+import { schnorr } from '@noble/curves/secp256k1.js';
+import { sha256 } from '@noble/hashes/sha2';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils';
+import { getPublicKey } from 'nostr-tools/pure';
+import { hexEquals, normaliseHex } from './hex.js';
+/** Closest first, matching the canonical order in the kindred primitive. */
+const TIER_RANK = { kin: 3, kith: 2, ken: 1, open: 0 };
+/**
+ * The exact bytes a kindred proof signs over. Every field that changes the
+ * proof's meaning is in here, so tampering with any one of them - tier,
+ * subject, room, nonce or expiry - invalidates the signature.
+ *
+ * `room` and `nonce` are covered deliberately: see `KindredProof`. A proof
+ * signed by an implementation that omits them reconstructs a different message
+ * and fails the signature check, which is the right way round - an older proof
+ * is refused rather than silently admitted somewhere it was never meant to go.
+ */
+function canonicalMessage(tier, participant, room, nonce, expiresAt) {
+    return sha256(new TextEncoder().encode(`kithmoot/v1/kindred:${tier}:${participant}:${room}:${nonce}:${expiresAt}`));
+}
+/** Vouch for a participant at a tier, in one room, until an expiry. */
+export function issueKindredProof(opts) {
+    // `participant` and `roomId` are identifiers handed in by the caller -
+    // possibly typed or pasted - so they are canonicalised here, at the point
+    // they enter the proof, rather than left for `evaluateAccess`'s equality
+    // checks to paper over.
+    const participant = normaliseHex(opts.participant);
+    const room = normaliseHex(opts.roomId);
+    const nonce = normaliseHex(opts.nonce ?? bytesToHex(randomBytes(32)));
+    const sig = schnorr.sign(canonicalMessage(opts.tier, participant, room, nonce, opts.expiresAt), opts.hostSk);
+    return {
+        tier: opts.tier,
+        participant,
+        issuer: getPublicKey(opts.hostSk),
+        room,
+        nonce,
+        sig: bytesToHex(sig),
+        expiresAt: opts.expiresAt,
+    };
+}
+/**
+ * Decide whether `participant` may join a room under `policy`.
+ *
+ * `ken` is one-way recognition - pinning someone's key from an authoritative
+ * source, with no bond back - so it never satisfies a `kith` gate. `kin` is
+ * closer than `kith` and does. Checks run cheapest first and never throw:
+ * participant match, room match, expiry, issuer trust, tier, then the schnorr
+ * verification last, since it is the most expensive.
+ */
+export function evaluateAccess(policy, participant, proof, now, roomId) {
+    // A members list closes the door before any tier is considered: a
+    // direct message is open in tier and shut to everybody but its two.
+    if (policy.members !== undefined && !policy.members.some((m) => hexEquals(m, participant))) {
+        return { admitted: false, reason: 'not a member' };
+    }
+    if (policy.tier === 'open')
+        return { admitted: true, reason: 'open room' };
+    if (!proof)
+        return { admitted: false, reason: 'no kindred proof' };
+    // Hex, compared case-insensitively throughout this function: see
+    // `hexEquals` and `vectors/README.md`. An allow-list entry, or a proof,
+    // stored in upper-case hex names exactly the same identifier and must not
+    // be rejected on case alone.
+    if (!hexEquals(proof.participant, participant))
+        return { admitted: false, reason: 'proof names another participant' };
+    // A proof is a grant in one room, not a bearer token - see `KindredProof`.
+    if (proof.room === undefined || !hexEquals(proof.room, roomId)) {
+        return { admitted: false, reason: 'proof names another room' };
+    }
+    if (proof.expiresAt <= now)
+        return { admitted: false, reason: 'expired' };
+    if (!policy.admitted?.some((a) => hexEquals(a, proof.issuer))) {
+        return { admitted: false, reason: 'untrusted issuer' };
+    }
+    // Fail closed on a tier we do not recognise. TIER_RANK[unknown] is
+    // undefined and `undefined < 2` is false, so the obvious comparison skips
+    // the rejection branch and admits - the opposite of what a gate is for. A
+    // trusted issuer's typo, or a looser independent implementation, is all it
+    // would take.
+    const rank = TIER_RANK[proof.tier];
+    if (rank === undefined)
+        return { admitted: false, reason: 'unrecognised tier' };
+    if (rank < (TIER_RANK[policy.tier] ?? 0))
+        return { admitted: false, reason: 'tier too low' };
+    try {
+        const message = canonicalMessage(proof.tier, proof.participant, proof.room, proof.nonce, proof.expiresAt);
+        if (!schnorr.verify(hexToBytes(proof.sig), message, hexToBytes(proof.issuer))) {
+            return { admitted: false, reason: 'bad signature' };
+        }
+    }
+    catch {
+        return { admitted: false, reason: 'bad signature' };
+    }
+    return { admitted: true, reason: 'kindred proof accepted' };
+}
+/** Every wire-format literal this module owns (each one a kithmoot protocol string), frozen for
+ *  `src/labels.test.ts`, which checks each module against its own exported
+ *  list rather than scanning file text for matching comments. Pure data -
+ *  adding this export changes no runtime behaviour. */
+export const ACCESS_LABELS = [
+    "kithmoot/v1/kindred:",
+];

package/dist/channel.d.ts

@@ -0,0 +1,27 @@
+/** `deriveChannel`, extracted from KithMoot's `src/chat.ts` (see
+ * EXTRACTION.md).
+ * `ChatLog` and the chat event codecs stay in KithMoot. */
+export declare const CHANNEL_ID_INFO = "kithmoot/v1/channel-id/";
+export declare const CHANNEL_KEY_INFO = "kithmoot/v1/channel-key/";
+/** Bounds a channel name, which rides only in an HKDF info string and
+ *  never on the wire; long enough for any sensible name. */
+export declare const MAX_CHANNEL_NAME_LENGTH = 64;
+/**
+ * The room id and key a named channel lives under.
+ *
+ * Both derived from the room KEY, never the room id, so a party that holds
+ * the id and not the key - a forwarder, a relay - cannot find the channel
+ * from the room, let alone read it. Two separate HKDF expansions for the
+ * same reason `deriveRoom` uses two: publishing the id reveals nothing about
+ * the key. The main chat is the unnamed channel and is untouched by this:
+ * its id is the room id and its key the room key, byte for byte as before.
+ */
+export declare function deriveChannel(roomId: string, roomKey: Uint8Array, channel?: string): {
+    id: string;
+    key: Uint8Array;
+};
+/** Every wire-format literal this module owns (each one a kithmoot protocol string), frozen for
+ *  `src/labels.test.ts`, which checks each module against its own exported
+ *  list rather than scanning file text for matching comments. Pure data -
+ *  adding this export changes no runtime behaviour. */
+export declare const CHANNEL_LABELS: readonly ["kithmoot/v1/channel-id/", "kithmoot/v1/channel-key/"];

package/dist/channel.js

@@ -0,0 +1,38 @@
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha2';
+/** `deriveChannel`, extracted from KithMoot's `src/chat.ts` (see
+ * EXTRACTION.md).
+ * `ChatLog` and the chat event codecs stay in KithMoot. */
+export const CHANNEL_ID_INFO = 'kithmoot/v1/channel-id/';
+export const CHANNEL_KEY_INFO = 'kithmoot/v1/channel-key/';
+/** Bounds a channel name, which rides only in an HKDF info string and
+ *  never on the wire; long enough for any sensible name. */
+export const MAX_CHANNEL_NAME_LENGTH = 64;
+/**
+ * The room id and key a named channel lives under.
+ *
+ * Both derived from the room KEY, never the room id, so a party that holds
+ * the id and not the key - a forwarder, a relay - cannot find the channel
+ * from the room, let alone read it. Two separate HKDF expansions for the
+ * same reason `deriveRoom` uses two: publishing the id reveals nothing about
+ * the key. The main chat is the unnamed channel and is untouched by this:
+ * its id is the room id and its key the room key, byte for byte as before.
+ */
+export function deriveChannel(roomId, roomKey, channel) {
+    if (channel === undefined)
+        return { id: roomId, key: roomKey };
+    if (channel.length === 0 || channel.length > MAX_CHANNEL_NAME_LENGTH)
+        throw new Error('channel name out of range');
+    const idBytes = hkdf(sha256, roomKey, undefined, CHANNEL_ID_INFO + channel, 32);
+    const key = hkdf(sha256, roomKey, undefined, CHANNEL_KEY_INFO + channel, 32);
+    const id = Array.from(idBytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    return { id, key };
+}
+/** Every wire-format literal this module owns (each one a kithmoot protocol string), frozen for
+ *  `src/labels.test.ts`, which checks each module against its own exported
+ *  list rather than scanning file text for matching comments. Pure data -
+ *  adding this export changes no runtime behaviour. */
+export const CHANNEL_LABELS = [
+    "kithmoot/v1/channel-id/",
+    "kithmoot/v1/channel-key/",
+];

package/dist/credential.d.ts

@@ -0,0 +1,74 @@
+import type { ParticipantIdentity } from './identity.js';
+import type { DeviceCredential } from './types.js';
+export interface CreateCredentialOptions {
+    /**
+     * The participant. A locally held key (`localIdentity`) or an external
+     * signer - see `ParticipantIdentity`. Either way the secret itself never
+     * reaches this function.
+     */
+    identity: ParticipantIdentity;
+    /** The pubkey of the device being authorised. */
+    devicePubkey: string;
+    /**
+     * The room this credential is for. Omit it, and pass `scope: 'person'`,
+     * for a credential that lets the device act for the participant in every
+     * room, DM and box: the same event with `d` set to the participant's own
+     * pubkey and a `scope` tag, so a verifier that knows one form knows the
+     * other. See docs/device-credential.md.
+     */
+    roomId?: string;
+    /** `person` widens the credential from one room to the participant. */
+    scope?: 'person';
+    /** What the person calls this device. Shown to them and to nobody else. */
+    label?: string;
+    /** Unix seconds. A person credential may not run more than 30 days. */
+    expiresAt: number;
+    /** Injectable clock, in unix seconds. Defaults to the real one. */
+    now?: () => number;
+}
+/** 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.
+ *
+ * The credential is signed by the participant key but is never published to a
+ * relay - it travels inside the room-key-encrypted roster, so relays never
+ * learn the participant pubkey.
+ *
+ * Asynchronous because the signer may not be here: an extension has to
+ * prompt, a bunker has to be reached over a relay, a phone has to be
+ * unlocked. See `ParticipantIdentity`.
+ */
+export declare function createDeviceCredential(opts: CreateCredentialOptions): Promise<DeviceCredential>;
+export type VerifyResult = {
+    ok: true;
+    participant: string;
+    device: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function verifyDeviceCredential(cred: DeviceCredential, opts: {
+    roomId: string;
+    now: number;
+    acceptPerson?: boolean;
+} | {
+    identity: string;
+    now: number;
+}): VerifyResult;

package/dist/credential.js

@@ -0,0 +1,177 @@
+import { KINDS } from './kinds.js';
+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.
+ *
+ * The credential is signed by the participant key but is never published to a
+ * relay - it travels inside the room-key-encrypted roster, so relays never
+ * learn the participant pubkey.
+ *
+ * Asynchronous because the signer may not be here: an extension has to
+ * prompt, a bunker has to be reached over a relay, a phone has to be
+ * unlocked. See `ParticipantIdentity`.
+ */
+export async function createDeviceCredential(opts) {
+    const now = (opts.now ?? (() => Math.floor(Date.now() / 1000)))();
+    const person = opts.scope === 'person';
+    if (person && opts.roomId !== undefined)
+        throw new Error('a person credential names no room');
+    if (!person && opts.roomId === undefined)
+        throw new Error('a room credential needs a room');
+    if (person && opts.expiresAt - now > PERSON_CREDENTIAL_MAX_SECONDS)
+        throw new Error('a person credential may not run more than 30 days');
+    const unsigned = {
+        kind: KINDS.CREDENTIAL,
+        created_at: now,
+        tags: [
+            ['d', person ? opts.identity.pubkey : opts.roomId],
+            ['device', opts.devicePubkey],
+            ['expiration', String(opts.expiresAt)],
+            ...(person ? [['scope', 'person']] : []),
+            ...(opts.label !== undefined ? [['label', opts.label]] : []),
+        ],
+        content: '',
+    };
+    const signed = await opts.identity.signEvent(unsigned);
+    // A signer is not part of this codebase: it is a browser extension, a
+    // bunker on somebody else's machine, or an app on a phone. It is trusted
+    // to hold the key, not to be correct - and a credential is the one thing
+    // in this protocol that says who a device speaks for. So what comes back
+    // is checked against what was asked for, rather than returned on faith.
+    //
+    // `created_at` is deliberately NOT compared: some signers stamp their own,
+    // it is inside the signature either way, and nothing here decides anything
+    // on it - the `expiration` tag is what bounds the credential, and that IS
+    // compared.
+    if (!hexEquals(signed.pubkey, opts.identity.pubkey)) {
+        throw new Error('the signer returned a credential signed by a different key');
+    }
+    if (signed.kind !== unsigned.kind || signed.content !== unsigned.content) {
+        throw new Error('the signer returned a credential for something else');
+    }
+    if (JSON.stringify(signed.tags) !== JSON.stringify(unsigned.tags)) {
+        throw new Error('the signer returned a credential on different terms than it was asked for');
+    }
+    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;
+}
+/**
+ * Verify a credential for one room (`roomId`) or for the person (`identity`,
+ * the participant pubkey the verifier expects). A person credential is
+ * accepted where a room credential is expected only when the caller says
+ * so with `acceptPerson`, which a room does when it admits the person and
+ * so admits their devices. A room credential is never accepted as a person
+ * credential, and a room credential carrying a `scope` tag is refused.
+ */
+/** A credential rides on every message and presence its device sends, so
+ *  the same one reaches this check again and again: checking its signature
+ *  afresh each time was half of what opening an old room cost. Keyed on the
+ *  whole event, signature included: a Schnorr signature is randomised, so
+ *  one credential can carry two valid signatures, and an id-keyed cache
+ *  would refuse the second. */
+const verifiedCredentials = new Set();
+function credentialSignature(cred) {
+    const whole = JSON.stringify([cred.id, cred.pubkey, cred.created_at, cred.kind, cred.tags, cred.content, cred.sig]);
+    if (verifiedCredentials.has(whole))
+        return true;
+    if (!verifyEventUncached(cred))
+        return false;
+    verifiedCredentials.add(whole);
+    if (verifiedCredentials.size > 4_096)
+        verifiedCredentials.delete(verifiedCredentials.values().next().value);
+    return true;
+}
+export function verifyDeviceCredential(cred, opts) {
+    if (cred.kind !== KINDS.CREDENTIAL)
+        return { ok: false, reason: 'wrong kind' };
+    const d = cred.tags.find((t) => t[0] === 'd')?.[1];
+    const scope = cred.tags.find((t) => t[0] === 'scope')?.[1];
+    if (d === undefined)
+        return { ok: false, reason: 'no scope' };
+    const isPerson = scope === 'person';
+    if (scope !== undefined && !isPerson)
+        return { ok: false, reason: 'unknown scope' };
+    if ('identity' in opts) {
+        if (!isPerson)
+            return { ok: false, reason: 'not a person credential' };
+        if (!hexEquals(d, opts.identity) || !hexEquals(d, cred.pubkey))
+            return { ok: false, reason: 'wrong person' };
+    }
+    else if (isPerson) {
+        if (!opts.acceptPerson)
+            return { ok: false, reason: 'person credential where a room credential was expected' };
+        if (!hexEquals(d, cred.pubkey))
+            return { ok: false, reason: 'wrong person' };
+    }
+    else if (!hexEquals(d, opts.roomId)) {
+        return { ok: false, reason: 'wrong room' };
+    }
+    const expiration = cred.tags.find((t) => t[0] === 'expiration')?.[1];
+    // A missing tag and a present-but-non-numeric one are the same failure:
+    // there is no usable expiry to check against. Folding them into one
+    // `Number.isFinite` guard matters because `Number(expiration)` on
+    // anything non-numeric is NaN, and every comparison with NaN - including
+    // `NaN <= now` - is false, so the naive check below would treat a
+    // corrupted tag as never expiring: a fail-open default in a security
+    // check, even though the tag sits inside the signed content today and so
+    // is not exploitable while the signature check below still runs.
+    const expiresAt = expiration === undefined ? NaN : Number(expiration);
+    if (!Number.isFinite(expiresAt))
+        return { ok: false, reason: 'no expiration' };
+    if (expiresAt <= opts.now)
+        return { ok: false, reason: 'expired' };
+    if (isPerson && expiresAt - cred.created_at > PERSON_CREDENTIAL_MAX_SECONDS)
+        return { ok: false, reason: 'longer than 30 days' };
+    const device = cred.tags.find((t) => t[0] === 'device')?.[1];
+    if (!device)
+        return { ok: false, reason: 'no device' };
+    // Signature last: it is the most expensive check, and tampering with any tag
+    // above invalidates it anyway. Never nostr-tools' own cached verdict, which
+    // a credential could arrive carrying - see `verify.ts` - but our bounded
+    // cache, which matches only the identical event.
+    if (!credentialSignature(cred))
+        return { ok: false, reason: 'bad signature' };
+    // A credential is one of the places a device/participant pubkey enters
+    // the system - the `device` tag in particular is free text set by
+    // whoever minted the credential. Canonicalise both here so every caller
+    // (roster decode, secondary-device adoption) compares against something
+    // already lower-case, rather than each having to know to.
+    return { ok: true, participant: normaliseHex(cred.pubkey), device: normaliseHex(device) };
+}