@kokuin/controller 0.1.0

package/README.md

@@ -0,0 +1,7 @@
+# @kokuin/controller
+
+## Installation
+
+```sh
+npm install @kokuin/controller
+```

package/lib/canonical.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Deepest nesting {@link canonicalBytes} will encode (top-level value is depth 1). The RFC 8785
+ * encoder recurses once per level and, like `JSON.stringify`, only fails at native stack exhaustion —
+ * a few kilobytes of `[[[[…]]]]` on the wire would be a `RangeError` thrown from a function every
+ * event passes through, and from inside `resolveBranches` where one hostile branch would take
+ * duplicity detection down for every honest one. So `canonicalBytes` rejects on this bound *before*
+ * encoding rather than catching a `RangeError` (which still drives the stack to exhaustion once per
+ * event). 64 is far above anything this stack canonicalizes (an event body reaches depth 3) and far
+ * below the ~10⁴ frames a JS stack holds. Raising it is safe; lowering below 3 is not.
+ */
+export declare const MAX_CANONICAL_DEPTH = 64;
+/**
+ * Whether {@link canonicalBytes} could encode this value without exceeding
+ * {@link MAX_CANONICAL_DEPTH} — the total counterpart of the bound above, turning "too deep" into a
+ * rejection. Bounded by the same constant, so it is safe even on a cyclic object (which parsed JSON
+ * cannot produce but a caller can). Answers only the depth question; prefer {@link isCanonicalizable}
+ * for untrusted input, since a non-finite number is reachable from `JSON.parse` and this ignores it.
+ */
+export declare function withinCanonicalDepth(value: unknown, depth?: number): boolean;
+/**
+ * Whether {@link canonicalBytes} could encode this value at all — every reason it throws, answered
+ * instead of raised. The total counterpart of the whole canonicalizer. {@link withinCanonicalDepth}
+ * answers only depth, which left a hole: `1e400` on the wire parses to `Infinity`, is a `number`,
+ * nests no deeper than anything, and reached `canonicalize` where it *threw* — breaking the total
+ * contract of `foldLog`/`verifySignatures` and taking `resolveBranches` down for every honest branch.
+ *
+ * Answers `false` for exactly what `canonicalize` refuses: a non-finite number (`Infinity`/`NaN`,
+ * the first reachable from `JSON.parse` via `1e400`); a type with no encoding (`bigint`, `symbol`,
+ * `function`, top-level `undefined` — all caller-only); a non-plain object (caller-only); a value
+ * nesting past {@link MAX_CANONICAL_DEPTH}, kept here so one call covers the whole contract.
+ *
+ * Deliberately **not** rejected: `-0` (encodes as `0`, same value under every comparison this package
+ * makes), and integers past `Number.MAX_SAFE_INTEGER` (`JSON.parse` collapses the two wire spellings
+ * to one double before anything here sees them, so the shared digest names one value). Bounded by the
+ * same constant, so it is safe even on a cyclic object.
+ */
+export declare function isCanonicalizable(value: unknown, depth?: number): boolean;
+/**
+ * RFC 8785 (JCS) canonical bytes via `@sozai/json`: keys sorted, no insignificant whitespace,
+ * `undefined` properties dropped so an absent optional field never encodes as `null`. The DID is the
+ * hash of these bytes, so any change here moves every identifier the stack has issued — frozen.
+ *
+ * Validated by {@link isCanonicalizable} before encoding, not left to the encoder: `@sozai/json`
+ * fails a deep value only at native stack exhaustion (see {@link MAX_CANONICAL_DEPTH}) and *encodes*
+ * a `Date`/`Map`/typed array rather than refusing it. The guard rejects every value the old encoder
+ * did — non-finite, non-plain, unrepresentable, or past the depth bound — so a wrong digest fails
+ * loud here instead of silently naming a value the wire form can never carry. It also makes the
+ * throw set exactly {@link isCanonicalizable}'s `false` set, the totality `verifyDigest` relies on.
+ */
+export declare function canonicalBytes(value: unknown): Uint8Array;
+/** Self-addressing digest: multibase(multihash(canonical bytes)). */
+export declare function digestOf(value: unknown): string;
+/**
+ * Total: a malformed digest *or* a value this file cannot canonicalize returns false rather than
+ * throwing. The value side is the untrusted one in real use ("is this the body that digest names" is
+ * asked about wire bytes), and `false` is correct, not convenient: a digest this package produced can
+ * only name a value it could canonicalize. Uses {@link isCanonicalizable}, not
+ * {@link withinCanonicalDepth}, since a non-finite number is another way `canonicalize` throws.
+ * `canonicalBytes` keeps its throw — its contract is "these exact bytes or nothing".
+ */
+export declare function verifyDigest(digest: string, value: unknown): boolean;

package/lib/canonical.js

@@ -0,0 +1,114 @@
+import { decodeMultibase, encodeMultibase, multihashSHA256, verifyMultihash } from '@kokuin/token';
+import { canonicalize } from '@sozai/json';
+const encoder = new TextEncoder();
+/**
+ * Deepest nesting {@link canonicalBytes} will encode (top-level value is depth 1). The RFC 8785
+ * encoder recurses once per level and, like `JSON.stringify`, only fails at native stack exhaustion —
+ * a few kilobytes of `[[[[…]]]]` on the wire would be a `RangeError` thrown from a function every
+ * event passes through, and from inside `resolveBranches` where one hostile branch would take
+ * duplicity detection down for every honest one. So `canonicalBytes` rejects on this bound *before*
+ * encoding rather than catching a `RangeError` (which still drives the stack to exhaustion once per
+ * event). 64 is far above anything this stack canonicalizes (an event body reaches depth 3) and far
+ * below the ~10⁴ frames a JS stack holds. Raising it is safe; lowering below 3 is not.
+ */ export const MAX_CANONICAL_DEPTH = 64;
+/**
+ * Whether {@link canonicalBytes} could encode this value without exceeding
+ * {@link MAX_CANONICAL_DEPTH} — the total counterpart of the bound above, turning "too deep" into a
+ * rejection. Bounded by the same constant, so it is safe even on a cyclic object (which parsed JSON
+ * cannot produce but a caller can). Answers only the depth question; prefer {@link isCanonicalizable}
+ * for untrusted input, since a non-finite number is reachable from `JSON.parse` and this ignores it.
+ */ export function withinCanonicalDepth(value, depth = 1) {
+    // Same comparison at the same point as `canonicalize`'s, so the two agree exactly on the boundary.
+    if (depth > MAX_CANONICAL_DEPTH) {
+        return false;
+    }
+    if (value == null || typeof value !== 'object') {
+        return true;
+    }
+    const entries = Array.isArray(value) ? value : Object.values(value);
+    return entries.every((entry)=>withinCanonicalDepth(entry, depth + 1));
+}
+/**
+ * Whether {@link canonicalBytes} could encode this value at all — every reason it throws, answered
+ * instead of raised. The total counterpart of the whole canonicalizer. {@link withinCanonicalDepth}
+ * answers only depth, which left a hole: `1e400` on the wire parses to `Infinity`, is a `number`,
+ * nests no deeper than anything, and reached `canonicalize` where it *threw* — breaking the total
+ * contract of `foldLog`/`verifySignatures` and taking `resolveBranches` down for every honest branch.
+ *
+ * Answers `false` for exactly what `canonicalize` refuses: a non-finite number (`Infinity`/`NaN`,
+ * the first reachable from `JSON.parse` via `1e400`); a type with no encoding (`bigint`, `symbol`,
+ * `function`, top-level `undefined` — all caller-only); a non-plain object (caller-only); a value
+ * nesting past {@link MAX_CANONICAL_DEPTH}, kept here so one call covers the whole contract.
+ *
+ * Deliberately **not** rejected: `-0` (encodes as `0`, same value under every comparison this package
+ * makes), and integers past `Number.MAX_SAFE_INTEGER` (`JSON.parse` collapses the two wire spellings
+ * to one double before anything here sees them, so the shared digest names one value). Bounded by the
+ * same constant, so it is safe even on a cyclic object.
+ */ export function isCanonicalizable(value, depth = 1) {
+    // Same comparison at the same point as `canonicalize`'s, so the two agree exactly on the boundary.
+    if (depth > MAX_CANONICAL_DEPTH) {
+        return false;
+    }
+    if (value === null) {
+        return true;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value);
+    }
+    if (typeof value === 'string' || typeof value === 'boolean') {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every((entry)=>isCanonicalizable(entry, depth + 1));
+    }
+    if (typeof value === 'object') {
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            return false;
+        }
+        // `undefined` members are dropped by `canonicalize` rather than encoded, so they are not a
+        // reason to refuse — mirroring the `filter` there.
+        return Object.values(value).every((entry)=>entry === undefined || isCanonicalizable(entry, depth + 1));
+    }
+    return false;
+}
+/**
+ * RFC 8785 (JCS) canonical bytes via `@sozai/json`: keys sorted, no insignificant whitespace,
+ * `undefined` properties dropped so an absent optional field never encodes as `null`. The DID is the
+ * hash of these bytes, so any change here moves every identifier the stack has issued — frozen.
+ *
+ * Validated by {@link isCanonicalizable} before encoding, not left to the encoder: `@sozai/json`
+ * fails a deep value only at native stack exhaustion (see {@link MAX_CANONICAL_DEPTH}) and *encodes*
+ * a `Date`/`Map`/typed array rather than refusing it. The guard rejects every value the old encoder
+ * did — non-finite, non-plain, unrepresentable, or past the depth bound — so a wrong digest fails
+ * loud here instead of silently naming a value the wire form can never carry. It also makes the
+ * throw set exactly {@link isCanonicalizable}'s `false` set, the totality `verifyDigest` relies on.
+ */ export function canonicalBytes(value) {
+    if (!isCanonicalizable(value)) {
+        throw new Error('Canonicalization: value is not canonicalizable (non-finite, non-plain, unrepresentable, or ' + `nests deeper than ${MAX_CANONICAL_DEPTH})`);
+    }
+    // Never `undefined`: `isCanonicalizable` has already rejected the values with no JSON form.
+    return encoder.encode(canonicalize(value));
+}
+/** Self-addressing digest: multibase(multihash(canonical bytes)). */ export function digestOf(value) {
+    return encodeMultibase(multihashSHA256(canonicalBytes(value)));
+}
+/**
+ * Total: a malformed digest *or* a value this file cannot canonicalize returns false rather than
+ * throwing. The value side is the untrusted one in real use ("is this the body that digest names" is
+ * asked about wire bytes), and `false` is correct, not convenient: a digest this package produced can
+ * only name a value it could canonicalize. Uses {@link isCanonicalizable}, not
+ * {@link withinCanonicalDepth}, since a non-finite number is another way `canonicalize` throws.
+ * `canonicalBytes` keeps its throw — its contract is "these exact bytes or nothing".
+ */ export function verifyDigest(digest, value) {
+    let expected;
+    try {
+        expected = decodeMultibase(digest);
+    } catch  {
+        return false;
+    }
+    if (!isCanonicalizable(value)) {
+        return false;
+    }
+    return verifyMultihash(expected, canonicalBytes(value));
+}

package/lib/derivation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Authority signing key at a position. Lives under the delegable branch, so handing out the
+ * profile sub-seed delegates it.
+ */
+export declare function authorityPath(profile: number, gen: number, seq: number): string;
+/** Profile-level key agreement key. Durable data encrypts to these, never to device keys. */
+export declare function agreementPath(profile: number, gen: number, seq: number): string;
+/**
+ * Recovery key, on the root-retained branch — a sibling of the delegable subtree, never a
+ * descendant. Hardened derivation is one-way, so a sub-seed holder cannot reach it and the root
+ * always keeps the one key that can supersede.
+ */
+export declare function recoveryPath(profile: number): string;
+/**
+ * Key material for an algorithm at a path. SLIP-0010 fixes the tree position; HKDF supplies
+ * algorithm separation and arbitrary lengths, so adding an algorithm needs a new `info` string
+ * and no path change.
+ */
+export declare function deriveKeyMaterial(seed: Uint8Array, path: string, alg: string, length?: number): Uint8Array;
+export declare function deriveKeyPair(seed: Uint8Array, path: string, alg: string): {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+};

package/lib/derivation.js

@@ -0,0 +1,75 @@
+import { ed25519, x25519 } from '@noble/curves/ed25519.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import HDKey from 'micro-key-producer/slip10.js';
+import { VERSION_TAG } from './version.js';
+const BASE_PATH = "m/44'/876'";
+const DELEGABLE = "0'";
+const ROOT_ONLY = "1'";
+const ROLE_AUTHORITY = "0'";
+const ROLE_AGREEMENT = "1'";
+function assertIndex(name, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`Derivation: ${name} must be a non-negative integer, got ${value}`);
+    }
+}
+function profilePath(profile) {
+    assertIndex('profile', profile);
+    return `${BASE_PATH}/${DELEGABLE}/${profile}'`;
+}
+/**
+ * Authority signing key at a position. Lives under the delegable branch, so handing out the
+ * profile sub-seed delegates it.
+ */ export function authorityPath(profile, gen, seq) {
+    assertIndex('gen', gen);
+    assertIndex('seq', seq);
+    return `${profilePath(profile)}/${ROLE_AUTHORITY}/${gen}'/${seq}'`;
+}
+/** Profile-level key agreement key. Durable data encrypts to these, never to device keys. */ export function agreementPath(profile, gen, seq) {
+    assertIndex('gen', gen);
+    assertIndex('seq', seq);
+    return `${profilePath(profile)}/${ROLE_AGREEMENT}/${gen}'/${seq}'`;
+}
+/**
+ * Recovery key, on the root-retained branch — a sibling of the delegable subtree, never a
+ * descendant. Hardened derivation is one-way, so a sub-seed holder cannot reach it and the root
+ * always keeps the one key that can supersede.
+ */ export function recoveryPath(profile) {
+    assertIndex('profile', profile);
+    return `${BASE_PATH}/${ROOT_ONLY}/${profile}'`;
+}
+const KEY_LENGTHS = {
+    EdDSA: 32,
+    X25519: 32,
+    'ML-DSA-65': 32,
+    'ML-KEM-768': 64
+};
+/**
+ * Key material for an algorithm at a path. SLIP-0010 fixes the tree position; HKDF supplies
+ * algorithm separation and arbitrary lengths, so adding an algorithm needs a new `info` string
+ * and no path change.
+ */ export function deriveKeyMaterial(seed, path, alg, length = KEY_LENGTHS[alg] ?? 32) {
+    const node = HDKey.fromMasterSeed(seed).derive(path);
+    const ikm = node.privateKey;
+    if (ikm == null) {
+        throw new Error(`Derivation: no private key at path ${path}`);
+    }
+    const info = new TextEncoder().encode(`${VERSION_TAG}|${alg}`);
+    return hkdf(sha256, ikm, undefined, info, length);
+}
+export function deriveKeyPair(seed, path, alg) {
+    const privateKey = deriveKeyMaterial(seed, path, alg);
+    if (alg === 'EdDSA') {
+        return {
+            privateKey,
+            publicKey: ed25519.getPublicKey(privateKey)
+        };
+    }
+    if (alg === 'X25519') {
+        return {
+            privateKey,
+            publicKey: x25519.getPublicKey(privateKey)
+        };
+    }
+    throw new Error(`Derivation: Unsupported algorithm for key pair derivation: ${alg}`);
+}

package/lib/events.d.ts

@@ -0,0 +1,286 @@
+import type { DIDString, ResolvedSigningKey } from '@kokuin/token';
+export declare const DID_PREFIX = "did:kokuin:";
+export type EventType = 'icp' | 'rot' | 'rev';
+export type EventCommon = {
+    /** Inception format version. Absent must never be inferred; always written. */
+    v: 1;
+    t: EventType;
+    /** Profile DID. Omitted from an inception, whose hash *is* the DID. */
+    i?: string;
+    /** Generation. Incremented only by a reset. */
+    g: number;
+    /** Sequence within the generation. */
+    s: number;
+    /** Digest of the previous event. Absent on inception. */
+    p?: string;
+    /**
+     * Criticality. In the common envelope so a verifier reads it without understanding `t`. An unknown
+     * event fails the fold closed when true, and is skipped when false.
+     */
+    crit: boolean;
+};
+export type InceptionEvent = EventCommon & {
+    t: 'icp';
+    /** Current authority public keys, multicodec-tagged and multibase-encoded. */
+    k: Array<string>;
+    /**
+     * Key agreement public keys -- an OR set, never combined. Carries no pre-rotation commitment: an
+     * exposed agreement key discloses past ciphertexts but confers no authority.
+     */
+    ka: Array<string>;
+    /** Digests of the next public keys — pre-rotation. */
+    n: Array<string>;
+    /** Signing threshold: how many of `k` must sign. **Must equal `k.length`** — see {@link isEnforcedThreshold}. */
+    kt: number;
+    /** Rotation threshold: how many of `n` must sign the next rotate. **Must equal `n.length`.** */
+    nt: number;
+    /**
+     * Digest of the recovery key. Root-retained, **immutable for the life of the DID** — the only
+     * event that can carry one is this one, and this one is the DID. A rotate carrying `r` is refused
+     * rather than ignored — see {@link RotateEvent}.
+     */
+    r: string;
+};
+export type SignedEvent<E extends EventCommon = EventCommon> = {
+    event: E;
+    /** base64url ed25519 signatures over the canonical event bytes, positional against `event.k`. */
+    sigs: Array<string>;
+    /**
+     * The revealed recovery public key, present only on a reset. The recovery key is committed as a
+     * digest and unpublished until used, so a reset must reveal it for the commitment to be checkable.
+     */
+    recoveryKey?: string;
+};
+export declare function signEvent(event: EventCommon, privateKeys: Array<Uint8Array>): Array<string>;
+/**
+ * Total: a malformed signature or key yields false rather than throwing, including a body the
+ * canonicalizer refuses. `canonicalBytes` throws on a non-finite number or nesting past
+ * `MAX_CANONICAL_DEPTH` (both from `JSON.parse`); the fold's envelope guard rejects such a body one
+ * layer out, so this is unreachable through `foldLog` but stays because the export is documented
+ * total and a direct caller reaches it with a parsed body. `false` is honest: a body with no
+ * canonical encoding has no bytes for a signature to be over.
+ */
+export declare function verifySignatures(event: EventCommon, sigs: Array<string>, keys: Array<string>): boolean;
+/**
+ * Whether one of an event's signatures was made by `key` — the counterpart of
+ * {@link verifySignatures} for a signer the *event* does not name (resolved from a DID elsewhere). A
+ * capability-authorised revoke needs exactly this: its author is the capability's `aud`, which the
+ * fold cannot resolve, so it is handed the key and checks the signature itself.
+ *
+ * Total, EdDSA only — all {@link signEvent} produces. An ES256 audience therefore cannot author a
+ * revoke, which fails closed until events grow a second signature algorithm.
+ */
+export declare function verifyEventSignedBy(signed: SignedEvent, key: ResolvedSigningKey): boolean;
+/**
+ * Deterministic inception. Only seed-derived, canonical material — no timestamp, nonce, or label —
+ * so the DID is a pure function of the seed and profile index. Never add a label: a mistyped one on
+ * recovery would reproduce a different DID.
+ */
+export declare function createInception(seed: Uint8Array, profile: number): SignedEvent<InceptionEvent>;
+export declare function didFromInception(event: InceptionEvent): DIDString;
+/** The did:kokuin: identifier a seed and profile produce, without signing an inception. */
+export declare function didFor(seed: Uint8Array, profile: number): DIDString;
+export declare function verifyInception(signed: SignedEvent<InceptionEvent>, did: string): boolean;
+export type RotateEvent = EventCommon & {
+    t: 'rot';
+    /** Keys the prior event pre-committed, now revealed, multicodec-tagged and multibase-encoded. */
+    k: Array<string>;
+    /** Key agreement public keys — an OR set, never combined. Carries no pre-rotation commitment. */
+    ka: Array<string>;
+    /** Digests of the next public keys — pre-rotation. */
+    n: Array<string>;
+    /** Signing threshold: how many of `k` must sign. **Must equal `k.length`.** */
+    kt: number;
+    /** Rotation threshold: how many of `n` must sign the next rotate. **Must equal `n.length`.** */
+    nt: number;
+    /**
+     * Seal: an anchored external digest pinning a high-value grant to this position. Opaque to the fold
+     * by design — its meaning belongs to whatever produced it, and nothing in the key state can
+     * contradict it. The fold owes it only that it cannot ride in as a non-string (checked in
+     * {@link isPublishedRotate}). Not surfaced in `KeyState`: it belongs to a position, not the keys.
+     */
+    a?: string;
+    /** Deny-set snapshot. Replaces the accumulated set, pruning it. */
+    d?: Array<string>;
+};
+export type CreateRotateOptions = {
+    seal?: string;
+    /**
+     * The complete deny set this rotate leaves behind — **a replacement, not an addition**. `d` present
+     * replaces the accumulated set, `d` absent carries it forward. A caller writing one entry meaning
+     * "also deny this" silently drops every accumulated entry — un-revoking devices and un-retiring
+     * leaked keys — with no error and nothing in the log saying anything was lost. Build it from the
+     * folded state with {@link pruneDenySet}. `[]` is the deliberate "clear everything" a cold rotate
+     * does to recover from a bad management tier. A rotate cannot establish a key its own snapshot
+     * denies; the fold refuses such an event.
+     */
+    denySnapshot?: Array<string>;
+    /**
+     * Where the currently-active authority key lives — the position of the last `icp`/`rot`, i.e. the
+     * fold's `keyGen`/`keySeq`.
+     *
+     * Defaults to `prior`'s position, right only while sequence and derivation index still coincide: a
+     * `rev` advances `s` and establishes no key, so after the first revoke of a generation the two part
+     * company **and never rejoin**. Every rotate after a revoke needs this, not just the one directly
+     * on it. Optional rather than required because {@link createRotate} verifies the key it reveals
+     * against `prior`'s commitment and throws on disagreement — provably right where omitted, an error
+     * (not an unfoldable event) where not. Take it from `KeyState.keyGen`/`keySeq`.
+     */
+    keyPosition?: {
+        gen: number;
+        seq: number;
+    };
+};
+export type CreateRotateParams = {
+    seed: Uint8Array;
+    profile: number;
+    did: string;
+    prior: EventCommon;
+    options?: CreateRotateOptions;
+};
+/**
+ * A rotate reveals the keys the prior event pre-committed and commits the next set, signed by the
+ * newly revealed keys (per KERI — what makes a stolen current key unable to rotate). Reproducible
+ * from the seed alone unless it carries a seal or deny snapshot.
+ *
+ * **Throws rather than emitting an event the fold will reject.** The revealed key must be the one
+ * `prior` committed in `n`, and `options.keyPosition` decides which key gets derived — so a wrong
+ * position used to produce a well-formed, signed event no fold would accept. The two are checked
+ * against each other here. When `prior` carries no commitment (a `rev`), `keyPosition` is required:
+ * the default would derive a key one past the *revoke*, which nothing committed, and this is the one
+ * case unverifiable from `prior` alone.
+ */
+export declare function createRotate({ seed, profile, did, prior, options, }: CreateRotateParams): SignedEvent<RotateEvent>;
+/**
+ * A rotate is valid when it chains to the prior digest, its revealed keys match the prior event's
+ * pre-rotation commitment, and its signatures verify against those keys.
+ */
+export declare function verifyRotate(signed: SignedEvent<RotateEvent>, prior: {
+    digest: string;
+    n: Array<string>;
+}): boolean;
+/**
+ * A reset: a rotate signed by the recovery key that increments the generation and discards
+ * everything under the prior one, including every capability minted there.
+ *
+ * Anchored to the inception, not the log head: the recovery key lives on the root-retained
+ * derivation branch and its digest is committed in the deterministic inception, so a restored
+ * mnemonic can author one with no log knowledge or availability. Carries no options — no seal, `d`
+ * always `[]` — so a reset is a pure function of `(seed, profile, gen)`, and two blind resets at one
+ * generation produce identical bytes that resolve as idempotent re-derivation, not duplicity.
+ *
+ * The root need not know the current generation, only eventually exceed it (no attacker can author a
+ * competing reset at any generation): a blind root starts at `gen = 1` and retries higher if it
+ * learns of one — the cost is a round trip, never loss of control.
+ */
+export declare function createReset(seed: Uint8Array, profile: number, gen: number): SignedEvent<RotateEvent>;
+/**
+ * A reset verifies against the committed recovery digest, not the pre-rotation set. Both values it
+ * needs — the anchor digest and the recovery commitment — come from the inception, the *only* place
+ * either can: that is what lets a root holding nothing but its seed author one with no log
+ * availability. If the commitment could move, the root would have to read the log to know which key
+ * to sign with, and the one recovery path that survives losing the log would be gone.
+ * `recoveryPath(profile)` carries no index for the same reason — one recovery key per profile, for
+ * its lifetime. See {@link RotateEvent} for what was removed.
+ */
+export declare function verifyReset(signed: SignedEvent<RotateEvent>, inception: InceptionEvent): boolean;
+/**
+ * How a `rev` target names a **key** rather than a DID: `#<the multibase key exactly as it appears in
+ * `k`>`, the same spelling a token's `kid` uses. One spelling for one thing — unambiguous against
+ * `did:…` on sight, so a bare multibase string is not a second accepted encoding, any more than for
+ * `kid`.
+ */
+export declare const KEY_TARGET_PREFIX = "#";
+/** The deny-set spelling of `key` — what {@link createRevoke} takes as its target to deny it. */
+export declare function keyTarget(key: string): string;
+/**
+ * The key a `rev` target names, or `null` when it names a DID instead. Total on any string: a target
+ * of neither form lands in the deny set as the opaque identifier it is. The body is not validated
+ * against multibase — a `#` naming nothing denies nothing, exactly as a `did:` naming nobody does,
+ * and rejecting it would only add a way for a well-formed log to stop folding.
+ */
+export declare function keyFromTarget(target: string): string | null;
+export type RevokeEvent = EventCommon & {
+    t: 'rev';
+    /**
+     * What to deny, in one of two spellings, never a capability `jti`.
+     *
+     * A **DID** (`did:…`) denies a holder: no capability whose `aud` is that DID is valid from this
+     * position onward — one entry covers a device's life. A **key** ({@link keyTarget}) denies a
+     * signer: nothing this profile signed with that key verifies from this position onward, and it
+     * names a key of *this* profile (the deny set is the subject's own).
+     *
+     * One field carries both because they are enforced at opposite ends of the same set: the DID form
+     * by `@kokuin/capability` against a capability's `aud`, the key form by the resolver against the
+     * key a `kid` selects. Neither spelling can be mistaken for the other.
+     */
+    x: string;
+    /** A serialized capability authorising a non-authority signer. Verified in the fold. */
+    cap?: string;
+};
+export type CreateRevokeParams = {
+    seed: Uint8Array;
+    profile: number;
+    did: string;
+    prior: EventCommon;
+    target: string;
+    keyPosition: {
+        gen: number;
+        seq: number;
+    };
+    /** A serialized capability authorising this signer, when the signer is not an authority key. */
+    cap?: string;
+};
+/**
+ * Revoke a DID or a key — see {@link RevokeEvent.x} for the two spellings.
+ *
+ * Naming the device DID rather than a `jti` makes this one entry per device for its life — covering
+ * capabilities the verifier has never seen and future re-mints, where per-`jti` revocation would grow
+ * with every renewal. A key target retires a leaked key for material it *already* signed: `rotate`
+ * only retires it for new issuance (`resolve` is head-only), but already-issued material verifies
+ * through `resolveHistoric`, which survives a rotate by design, so a thief holding a rotated-away key
+ * could still mint one that verified. Retirement is therefore explicit, keeping the promise that a
+ * routine rotate does not invalidate already-issued material intact.
+ *
+ * **A key the profile currently publishes cannot be denied** — the fold rejects it (see the `rev`
+ * branch of `stepEvent`). Rotate first, then deny the key the rotate retired.
+ *
+ * `prior` answers "next sequence, what to chain to"; `keyPosition` separately answers "where the
+ * active authority key lives". They coincide only for an `icp`/`rot` prior — a `rev` establishes no
+ * key, so a revoke on a revoke still points at the last `icp`/`rot` position.
+ */
+export declare function createRevoke({ seed, profile, did, prior, target, keyPosition, cap, }: CreateRevokeParams): SignedEvent<RevokeEvent>;
+export type CreateRevokeOptions = {
+    /** A serialized capability authorising this signer, when the signer is not an authority key. */
+    cap?: string;
+};
+export type CreateRevokeWithKeyParams = {
+    privateKey: Uint8Array;
+    did: string;
+    prior: EventCommon;
+    target: string;
+    /** A serialized capability authorising this signer, when the signer is not an authority key. */
+    cap?: string;
+};
+/**
+ * Revoke a DID, signing with an Ed25519 key the caller already holds rather than deriving one from
+ * the profile seed.
+ *
+ * The builder for the actor a capability-authorised revoke exists for: a device holding a management
+ * capability, which by design never receives the profile sub-seed. `createRevoke` can only sign as
+ * the profile itself, so without this the feature had no API but re-implementing the signing
+ * convention per consumer — the duplication `createControllerCapabilityVerifier` prevents on the
+ * verifying side.
+ *
+ * The key is the audience key the capability pins in `cnf`, and the fold checks the event's signature
+ * against exactly that, so the two must match. Ed25519 only. Takes the private key rather than an
+ * identity because no identity type here signs raw bytes — a `KeyStore` entry hands back exactly this
+ * shape. Byte-identical to {@link createRevoke} given the same key; no `keyPosition`, which exists
+ * only to derive a key from a seed.
+ */
+export declare function createRevokeWithKey({ privateKey, did, prior, target, cap, }: CreateRevokeWithKeyParams): SignedEvent<RevokeEvent>;
+/** Authority-signed revoke. Capability-authorised revokes are checked in the fold. */
+export declare function verifyRevoke(signed: SignedEvent<RevokeEvent>, prior: {
+    digest: string;
+    keys: Array<string>;
+}): boolean;