@kokuin/controller 0.1.0

package/lib/events.js

@@ -0,0 +1,465 @@
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { base64urlnopad } from '@scure/base';
+import { canonicalBytes, digestOf, isCanonicalizable } from './canonical.js';
+import { agreementPath, authorityPath, deriveKeyPair, recoveryPath } from './derivation.js';
+import { encodeKey, tryDecodeKey } from './keys.js';
+export const DID_PREFIX = 'did:kokuin:';
+export function signEvent(event, privateKeys) {
+    const bytes = canonicalBytes(event);
+    return privateKeys.map((key)=>base64urlnopad.encode(ed25519.sign(bytes, key)));
+}
+/**
+ * Whether a published threshold agrees with what the fold enforces.
+ *
+ * `kt`/`nt` are published and digested into the event (and, for an inception, the DID), but the fold
+ * enforces n-of-n and nothing else: one valid signature per published key, every committed key
+ * revealed and signing. So the only threshold these fields can truthfully carry is the size of the
+ * set they govern; anything else is an event whose declaration contradicts the rule judging it. A
+ * field nothing reads is a trap for the next reader inside a wire format fixed by the DID; if quorum
+ * ever lands, the check moves with the enforcement. `===` against the length, so `"1"` fails.
+ */ function isEnforcedThreshold(threshold, keys) {
+    return threshold === keys.length;
+}
+/**
+ * A published key list: an array of strings. `k`, `n`, `ka` and the deny snapshot are carried into
+ * the folded state, so a bad shape must be rejected where it is published, not one event away where
+ * it is next read (a non-array `n` would throw in the *next* rotate; a non-array `k` is a `KeyState`
+ * whose type lies).
+ */ function isKeyList(value) {
+    return Array.isArray(value) && value.every((entry)=>typeof entry === 'string');
+}
+/**
+ * A key agreement set is valid when non-empty and every entry is a well-formed X25519-tagged key.
+ * Shared by every event that carries `ka` (inception, rotate, reset), which must reject the same
+ * malformed shapes everywhere.
+ */ function verifyAgreementKeys(ka) {
+    if (!isKeyList(ka) || ka.length === 0) {
+        return false;
+    }
+    for (const entry of ka){
+        const key = tryDecodeKey(entry);
+        if (key == null || key.alg !== 'X25519') {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 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 function verifySignatures(event, sigs, keys) {
+    if (!Array.isArray(sigs) || !Array.isArray(keys)) {
+        return false;
+    }
+    if (sigs.length !== keys.length || sigs.length === 0) {
+        return false;
+    }
+    if (!isCanonicalizable(event)) {
+        return false;
+    }
+    const bytes = canonicalBytes(event);
+    for(let i = 0; i < sigs.length; i++){
+        try {
+            const key = tryDecodeKey(keys[i]);
+            if (key == null || key.alg !== 'EdDSA') {
+                return false;
+            }
+            if (!ed25519.verify(base64urlnopad.decode(sigs[i]), bytes, key.publicKey)) {
+                return false;
+            }
+        } catch  {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 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 function verifyEventSignedBy(signed, key) {
+    // Both arms are unkillable through the fold (`isSignedEventShape` already established `sigs` is a
+    // string array; a non-EdDSA key would fail `ed25519.verify`; `[].some()` is `false`) and both stay
+    // by the file's guard rule: a direct caller reaches this with a parsed body.
+    if (key.alg !== 'EdDSA' || signed.sigs.length === 0) {
+        return false;
+    }
+    if (!isCanonicalizable(signed.event)) {
+        return false;
+    }
+    const bytes = canonicalBytes(signed.event);
+    return signed.sigs.some((sig)=>{
+        try {
+            return ed25519.verify(base64urlnopad.decode(sig), bytes, key.publicKey);
+        } catch  {
+            return false;
+        }
+    });
+}
+/**
+ * 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 function createInception(seed, profile) {
+    const event = inceptionEvent(seed, profile);
+    const current = deriveKeyPair(seed, authorityPath(profile, 0, 0), 'EdDSA');
+    return {
+        event,
+        sigs: signEvent(event, [
+            current.privateKey
+        ])
+    };
+}
+/**
+ * The inception body alone, unsigned. Split out because {@link createRotate} needs the DID this seed
+ * and profile produce to know whether it is the log's root, and signing a throwaway inception to
+ * find out is the one expensive step.
+ */ function inceptionEvent(seed, profile) {
+    const current = deriveKeyPair(seed, authorityPath(profile, 0, 0), 'EdDSA');
+    const next = deriveKeyPair(seed, authorityPath(profile, 0, 1), 'EdDSA');
+    const recovery = deriveKeyPair(seed, recoveryPath(profile), 'EdDSA');
+    const agreement = deriveKeyPair(seed, agreementPath(profile, 0, 0), 'X25519');
+    return {
+        v: 1,
+        t: 'icp',
+        g: 0,
+        s: 0,
+        crit: true,
+        k: [
+            encodeKey(current.publicKey, 'EdDSA')
+        ],
+        ka: [
+            encodeKey(agreement.publicKey, 'X25519')
+        ],
+        n: [
+            digestOf(encodeKey(next.publicKey, 'EdDSA'))
+        ],
+        kt: 1,
+        nt: 1,
+        r: digestOf(encodeKey(recovery.publicKey, 'EdDSA'))
+    };
+}
+export function didFromInception(event) {
+    return `${DID_PREFIX}${digestOf(event)}`;
+}
+/** The did:kokuin: identifier a seed and profile produce, without signing an inception. */ export function didFor(seed, profile) {
+    return didFromInception(inceptionEvent(seed, profile));
+}
+export function verifyInception(signed, did) {
+    if (signed.event.t !== 'icp' || signed.event.i !== undefined) {
+        return false;
+    }
+    // An inception is self-certifying: *any* body an attacker writes is a valid log for the DID it
+    // hashes to, which is why the thresholds and key lists it publishes must mean something. `k`/`n`/`r`
+    // go straight into the folded state where the next event reads them.
+    if (!isKeyList(signed.event.k) || !isKeyList(signed.event.n) || typeof signed.event.r !== 'string') {
+        return false;
+    }
+    if (!isEnforcedThreshold(signed.event.kt, signed.event.k) || !isEnforcedThreshold(signed.event.nt, signed.event.n)) {
+        return false;
+    }
+    if (didFromInception(signed.event) !== did) {
+        return false;
+    }
+    // An icp-only log must not be a valid DID publishing no agreement key.
+    if (!verifyAgreementKeys(signed.event.ka)) {
+        return false;
+    }
+    return verifySignatures(signed.event, signed.sigs, signed.event.k);
+}
+/**
+ * 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 function createRotate({ seed, profile, did, prior, options = {} }) {
+    const gen = prior.g;
+    const seq = prior.s + 1;
+    // The commitment the revealed key must match, when `prior` carries one. An `icp`/`rot` does; a
+    // `rev` and any hand-built prior of another shape does not.
+    const commitment = prior.n;
+    const committed = isKeyList(commitment) && commitment.length > 0 ? commitment : undefined;
+    // The checks below only have an answer when this seed *is* the log's root — otherwise the
+    // commitment was written by somebody else's key material and a mismatch says nothing. Refusing
+    // there would stop this generator building a foreign rotate at all (which the conformance suite
+    // legitimately does); the fold is the layer that rejects it.
+    const root = didFromInception(inceptionEvent(seed, profile)) === did;
+    if (root && committed == null && options.keyPosition == null) {
+        throw new Error('createRotate: prior event pre-commits no key, so keyPosition is required — pass the fold`s ' + 'KeyState.keyGen / keySeq for the position the last icp/rot established');
+    }
+    // The key this rotate reveals is the one the last icp/rot committed, one past *its* position; the
+    // agreement key lands at the same index so `KeyState.keyGen`/`keySeq` names it for a recipient
+    // re-deriving from the seed. See `CreateRotateOptions.keyPosition` for why these diverge from `s`.
+    const keyGen = options.keyPosition?.gen ?? gen;
+    const keySeq = (options.keyPosition?.seq ?? prior.s) + 1;
+    const current = deriveKeyPair(seed, authorityPath(profile, keyGen, keySeq), 'EdDSA');
+    const next = deriveKeyPair(seed, authorityPath(profile, keyGen, keySeq + 1), 'EdDSA');
+    const agreement = deriveKeyPair(seed, agreementPath(profile, keyGen, keySeq), 'X25519');
+    if (root && committed != null) {
+        // Exactly what `verifyRotate` checks, checked here where the caller can still act. Arity first:
+        // this generator emits a single key, so a prior committing any other number has no rotate here.
+        const revealed = encodeKey(current.publicKey, 'EdDSA');
+        if (committed.length !== 1 || digestOf(revealed) !== committed[0]) {
+            throw new Error(`createRotate: the key at (gen ${keyGen}, seq ${keySeq}) is not the one the prior event ` + 'pre-committed — pass options.keyPosition naming where the last icp/rot established a ' + 'key (the fold`s KeyState.keyGen / keySeq). A revoke advances `s` without establishing ' + 'one, so `s` and the derivation index part company at the first revoke of a generation ' + 'and stay apart.');
+        }
+    }
+    const event = {
+        v: 1,
+        t: 'rot',
+        i: did,
+        g: gen,
+        s: seq,
+        p: digestOf(prior),
+        crit: true,
+        k: [
+            encodeKey(current.publicKey, 'EdDSA')
+        ],
+        ka: [
+            encodeKey(agreement.publicKey, 'X25519')
+        ],
+        n: [
+            digestOf(encodeKey(next.publicKey, 'EdDSA'))
+        ],
+        kt: 1,
+        nt: 1,
+        a: options.seal,
+        d: options.denySnapshot
+    };
+    return {
+        event,
+        sigs: signEvent(event, [
+            current.privateKey
+        ])
+    };
+}
+/**
+ * Whether the members a rotate publishes into the folded state have the shape the fold will carry.
+ * Shared by {@link verifyRotate} and {@link verifyReset}: both hand `k`/`n`/`d` to the next
+ * `KeyState`, and a reset verifies against the recovery key not `k`, so without this it could publish
+ * a key set of any shape.
+ *
+ * `r` is refused outright — the runtime half of removing it from {@link RotateEvent}. A member the
+ * fold silently ignored would be the field-that-lies this removal is about: a reader seeing `r` on a
+ * rotate would take the recovery key to have moved when nothing moved it.
+ */ function isPublishedRotate(event) {
+    return isKeyList(event.k) && isKeyList(event.n) && isEnforcedThreshold(event.kt, event.k) && isEnforcedThreshold(event.nt, event.n) && // A seal is opaque but still a digest string on the wire (see `RotateEvent.a`); a non-string one
+    // is a member a reader would have to guess at.
+    (event.a == null || typeof event.a === 'string') && event.r === undefined && // The snapshot replaces the accumulated set, so the fold builds a `Set` from it: a scalar `d`
+    // throws, a string `d` would silently become a set of characters.
+    (event.d == null || isKeyList(event.d));
+}
+/**
+ * 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 function verifyRotate(signed, prior) {
+    const { event, sigs } = signed;
+    if (event.t !== 'rot' || event.p !== prior.digest) {
+        return false;
+    }
+    if (!isPublishedRotate(event)) {
+        return false;
+    }
+    if (event.k.length !== prior.n.length) {
+        return false;
+    }
+    for(let i = 0; i < event.k.length; i++){
+        if (digestOf(event.k[i]) !== prior.n[i]) {
+            return false;
+        }
+    }
+    if (!verifyAgreementKeys(event.ka)) {
+        return false;
+    }
+    return verifySignatures(event, sigs, event.k);
+}
+/**
+ * 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 function createReset(seed, profile, gen) {
+    if (gen < 1) {
+        throw new Error(`Reset: gen must be >= 1, got ${gen}`);
+    }
+    const inception = createInception(seed, profile);
+    const did = didFromInception(inception.event);
+    const current = deriveKeyPair(seed, authorityPath(profile, gen, 0), 'EdDSA');
+    const next = deriveKeyPair(seed, authorityPath(profile, gen, 1), 'EdDSA');
+    const recovery = deriveKeyPair(seed, recoveryPath(profile), 'EdDSA');
+    const agreement = deriveKeyPair(seed, agreementPath(profile, gen, 0), 'X25519');
+    const event = {
+        v: 1,
+        t: 'rot',
+        i: did,
+        g: gen,
+        s: 0,
+        p: digestOf(inception.event),
+        crit: true,
+        k: [
+            encodeKey(current.publicKey, 'EdDSA')
+        ],
+        ka: [
+            encodeKey(agreement.publicKey, 'X25519')
+        ],
+        n: [
+            digestOf(encodeKey(next.publicKey, 'EdDSA'))
+        ],
+        kt: 1,
+        nt: 1,
+        // A reset clears the deny set: every capability under the prior generation is gone anyway.
+        d: []
+    };
+    return {
+        event,
+        sigs: signEvent(event, [
+            recovery.privateKey
+        ]),
+        recoveryKey: encodeKey(recovery.publicKey, 'EdDSA')
+    };
+}
+/**
+ * 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 function verifyReset(signed, inception) {
+    const { event, sigs } = signed;
+    if (event.t !== 'rot' || event.p !== digestOf(inception) || event.s !== 0 || event.g < 1) {
+        return false;
+    }
+    if (!isPublishedRotate(event)) {
+        return false;
+    }
+    // A reset carries an empty deny set and no seal (see {@link createReset}) — the idempotency the
+    // branch selector relies on. Only the recovery-key holder can sign one, so this is not an
+    // attacker's event; it is the rule that makes "blind reset" mean the same bytes for every holder of
+    // the seed. Enforced here too so a reset carrying a non-empty `d` or a seal cannot fold as valid.
+    if (event.a !== undefined || event.d == null || event.d.length !== 0) {
+        return false;
+    }
+    if (!Array.isArray(sigs) || sigs.length !== 1) {
+        return false;
+    }
+    if (!verifyAgreementKeys(event.ka)) {
+        return false;
+    }
+    // The recovery key is committed as a digest and unpublished until used, so a reset must carry the
+    // revealed key on the envelope for the commitment to be checkable.
+    const revealed = signed.recoveryKey;
+    if (revealed == null || digestOf(revealed) !== inception.r) {
+        return false;
+    }
+    return verifySignatures(event, sigs, [
+        revealed
+    ]);
+}
+/**
+ * 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 const KEY_TARGET_PREFIX = '#';
+/** The deny-set spelling of `key` — what {@link createRevoke} takes as its target to deny it. */ export function keyTarget(key) {
+    return `${KEY_TARGET_PREFIX}${key}`;
+}
+/**
+ * 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 function keyFromTarget(target) {
+    return target.startsWith(KEY_TARGET_PREFIX) ? target.slice(KEY_TARGET_PREFIX.length) : null;
+}
+/**
+ * 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 function createRevoke({ seed, profile, did, prior, target, keyPosition, cap }) {
+    const current = deriveKeyPair(seed, authorityPath(profile, keyPosition.gen, keyPosition.seq), 'EdDSA');
+    return createRevokeWithKey({
+        privateKey: current.privateKey,
+        did,
+        prior,
+        target,
+        cap
+    });
+}
+/**
+ * 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 function createRevokeWithKey({ privateKey, did, prior, target, cap }) {
+    const event = {
+        v: 1,
+        t: 'rev',
+        i: did,
+        g: prior.g,
+        s: prior.s + 1,
+        p: digestOf(prior),
+        crit: true,
+        x: target,
+        cap
+    };
+    return {
+        event,
+        sigs: signEvent(event, [
+            privateKey
+        ])
+    };
+}
+/** Authority-signed revoke. Capability-authorised revokes are checked in the fold. */ export function verifyRevoke(signed, prior) {
+    const { event, sigs } = signed;
+    if (event.t !== 'rev' || event.p !== prior.digest) {
+        return false;
+    }
+    return verifySignatures(event, sigs, prior.keys);
+}

package/lib/fold.d.ts

@@ -0,0 +1,162 @@
+import type { DIDMethodResolver, ResolvedSigningKey } from '@kokuin/token';
+import { type SignedEvent } from './events.js';
+export type KeyState = {
+    did: string;
+    gen: number;
+    seq: number;
+    /** Generation in which the current `keys` were established. */
+    keyGen: number;
+    /**
+     * Derivation index of the current `keys`: key-establishing events this generation, counting the
+     * `icp`/`rot` that opened it as 0. Equal to `seq` until a revoke intervenes, and deliberately not
+     * the same thing — a revoke advances `seq` while establishing no key, so the pre-rotation chain
+     * (which commits the *next* key's digest, one index on) stops tracking `seq` there. Deriving at
+     * `seq` after a revoke produces a key the log never committed.
+     */
+    keySeq: number;
+    keys: Array<string>;
+    /** Key agreement keys — an OR set. Established by icp/rot, carried forward across rev. */
+    agreement: Array<string>;
+    next: Array<string>;
+    /**
+     * The inception's recovery commitment, carried unchanged through every event. Fixed for the life
+     * of the DID, and this field says so because {@link verifyReset} checks the revealed recovery key
+     * against `inception.r` and nothing else. A state that disagreed with the verifier would be worse
+     * than no state — see {@link RotateEvent} for the `r` that was removed.
+     */
+    recovery: string;
+    /**
+     * What this position denies, in the two spellings a `rev` target may take — see `RevokeEvent.x`. A
+     * `did:…` entry denies a *holder* (`@kokuin/capability` refuses a capability whose `aud` it names);
+     * a `#<multibase key>` entry denies a *signer* (`signingKeyFrom` refuses that key, `agreementKeysFrom`
+     * drops it).
+     *
+     * One heterogeneous set rather than two fields: the spellings cannot collide, and every mechanism
+     * the set already has (position-dependence, the `d` snapshot, a reset's clear, `resolveDenySet`,
+     * the `@kokuin/capability` wrapper that forwards it) then covers keys with nothing new to wire or
+     * forget. A second optional resolver member is a second thing a wrapper can drop, and dropping it
+     * fails open.
+     *
+     * **Invariant, enforced by both branches of `stepEvent`: no key in this state's `keys` or
+     * `agreement` is denied here.** So every reader may take a folded head's key set at face value.
+     */
+    deny: ReadonlySet<string>;
+    /** Digest of the event that produced this state — the `p` any successor must carry. */
+    digest: string;
+};
+export type FoldResult = {
+    ok: true;
+    states: Array<KeyState>;
+} | {
+    ok: false;
+    reason: string;
+    index: number;
+};
+/**
+ * What a capability verifier answers a cap-bearing revoke with.
+ *
+ * `audienceKey` is the key the capability pins as its audience at mint time, never resolved at
+ * verification time; the fold checks the event's own signature against it, binding the grant to the
+ * party it was issued to.
+ *
+ * A key rather than a boolean because the fold, not the verifier, must tie the answer to the event
+ * in hand. The log is public, so the serialized capability inside a revoke is readable by everyone
+ * who can resolve the profile; with a boolean, any such reader could lift it out and chain a revoke
+ * of their own with any bytes in `sigs`, covering whatever the capability's `res` covers — a
+ * wildcard, for a management capability, so every device. Among divisions keeping a *single*
+ * callback, this is the only one where neither side can leave the binding out.
+ */
+export type CapabilityAuthorisation = {
+    authorised: true;
+    audienceKey: ResolvedSigningKey;
+}
+/** `reason` becomes the fold's failure reason verbatim, so it must describe this rejection. */
+ | {
+    authorised: false;
+    reason: string;
+};
+export type FoldOptions = {
+    /**
+     * Verify a capability authorising a non-authority signer to revoke. Injected rather than imported
+     * so the sync path stays free of a capability dependency.
+     *
+     * Receives the serialized capability, the controller DID (which must be the capability `sub`), the
+     * DID being denied, and a resolver for the controller **at the position being verified**. That
+     * fourth argument makes the position contract keepable: the capability is issued by the very
+     * profile whose log carries the revoke, and the state to resolve it against is the prefix before
+     * this event — not the head (which would let a device revoked at event 1 keep authoring at event 2,
+     * the deny set being position-dependent only inside the fold) and not the whole log (which would
+     * recurse into the asking fold). Nothing outside the fold knows which position is being verified,
+     * so the fold answers rather than asks: this resolver holds exactly `states[0..i-1]`, is complete
+     * for the profile, and answers `Unknown DID` for anything else so a verifier can merge it into a
+     * wider registry for a chain's delegates. See {@link CapabilityAuthorisation}.
+     */
+    verifyCapability?: (params: VerifyCapabilityParams) => Promise<CapabilityAuthorisation>;
+};
+/** What the fold hands {@link FoldOptions.verifyCapability} — see that member for each field. */
+export type VerifyCapabilityParams = {
+    cap: string;
+    subject: string;
+    target: string;
+    subjectAtPosition: DIDMethodResolver;
+};
+/** A verifier threw. The thrown message is appended after `: `, so match with `startsWith`. */
+export declare const CAPABILITY_VERIFIER_FAILED = "capability verifier failed";
+/** A verifier answered with something that is not a {@link CapabilityAuthorisation}. */
+export declare const CAPABILITY_VERIFIER_MALFORMED_ANSWER = "capability verifier returned a malformed answer";
+/**
+ * The capability authorised the revoke and pinned an audience key, and somebody else signed the
+ * event. Distinct from a rejected grant: the delegation is sound and the signature is not.
+ */
+export declare const REVOKE_NOT_SIGNED_BY_AUDIENCE = "revoke is not signed by the capability audience";
+/**
+ * The sync fold met a capability-authorised revoke, which it cannot verify by construction — the
+ * management tier working as designed, answered by `foldLogAsync`. The capability follows after `: `,
+ * so match with `startsWith`. Exported so speculative folders (`resolveBranches`) can tell it from a
+ * genuinely broken log.
+ */
+export declare const CAPABILITY_REVOKE_NEEDS_ASYNC_FOLD = "capability-authorised revoke needs an async fold";
+/**
+ * The async fold met a capability-authorised revoke with no `verifyCapability` configured. Same
+ * shape: the log is fine and the call was not equipped for it.
+ */
+export declare const CAPABILITY_REVOKE_NEEDS_VERIFIER = "capability-authorised revoke needs a verifier";
+/**
+ * How many events a log may carry that this version cannot understand, beyond the number it can.
+ *
+ * A skipped event is accepted without a signature and advances neither `seq` nor the digest, so
+ * nothing about it is authenticated: a relaying peer can insert any number anywhere and the log still
+ * folds to the same head. The resolver re-folds on every resolution and a group replays the whole log
+ * at every welcome, so an unbounded skip path makes log size — and the verifier's CPU/memory — an
+ * attacker's choice. Bounded against the log's own real length so the ceiling stays proportional to
+ * work the verifier was doing anyway; the slack keeps a v1 verifier able to fold a log with a few
+ * later-version non-critical types near the front, which is the whole point of the skip path.
+ */
+export declare const MAX_SKIPPED_SLACK = 8;
+/** What a log padded past {@link MAX_SKIPPED_SLACK} fails with. */
+export declare const TOO_MANY_UNKNOWN_EVENTS = "too many unknown events";
+/**
+ * Fold a controller's log into per-position key state. `states[i]` is the state *after* `events[i]`,
+ * which a verifier evaluating at position `i` must use — that is what makes the deny set
+ * position-dependent: clearing a DID later never retroactively validates its earlier actions.
+ *
+ * Synchronous, so it stays usable on an offline verifier's apply path. A capability-authorised revoke
+ * needs async verification, so it fails closed here rather than trusting an unchecked capability — use
+ * `foldLogAsync` when one may be present.
+ */
+export declare function foldLog(did: string, events: Array<SignedEvent>): FoldResult;
+/**
+ * Async counterpart of {@link foldLog}. Shares {@link stepEvent}, so the only difference is a
+ * capability-authorised revoke: this entry point awaits `options.verifyCapability` instead of failing
+ * closed.
+ */
+export declare function foldLogAsync(did: string, events: Array<SignedEvent>, options?: FoldOptions): Promise<FoldResult>;
+export declare function keyStateAt(result: FoldResult, position: number): KeyState | undefined;
+/**
+ * The deny set of `state` with `drop` removed — what to pass as a rotate's `denySnapshot` to prune a
+ * few entries rather than replace the set. A rotate's `d` replaces the accumulated set outright, so
+ * pruning by hand means writing out everything that stays; miss one and the profile silently
+ * un-revokes a device or un-retires a leaked key. This builds it from the fold's own answer instead.
+ * Entries in `drop` the state does not carry are ignored.
+ */
+export declare function pruneDenySet(state: KeyState, drop: Iterable<string>): Array<string>;