@kokuin/controller 0.1.0

package/lib/fold.js

@@ -0,0 +1,499 @@
+import { digestOf, isCanonicalizable } from './canonical.js';
+import { keyFromTarget, keyTarget, verifyEventSignedBy, verifyInception, verifyReset, verifyRevoke, verifyRotate } from './events.js';
+import { createStateResolver } from './state-resolver.js';
+/**
+ * Whether a verifier's answer is one this fold can act on. Total, and strict about both arms: an
+ * `authorised: true` with no usable key would reach `verifyEventSignedBy` and throw, an
+ * `authorised: false` with no reason would produce a non-string `FoldResult.reason`. Neither is
+ * reachable from typed code, both from a stale build.
+ *
+ * The discriminant is compared against the literals, so a `'true'` string is malformed rather than
+ * authorising. The key bytes go through `ArrayBuffer.isView`, not `instanceof Uint8Array`, which is
+ * per-realm and would reject a correct answer built in a worker, a `vm` context, or across an
+ * Electron bridge — the one way this guard could turn away a good answer.
+ */ function isCapabilityAuthorisation(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    const answer = value;
+    if (answer.authorised === true) {
+        const key = answer.audienceKey;
+        return key != null && typeof key.alg === 'string' && ArrayBuffer.isView(key.publicKey);
+    }
+    return answer.authorised === false && typeof answer.reason === 'string';
+}
+function fail(reason, index) {
+    return {
+        ok: false,
+        reason,
+        index
+    };
+}
+/** What a log entry that is not a {@link SignedEvent} at all fails with. */ const MALFORMED_EVENT = 'malformed event';
+// The fold's capability-revoke failure reasons. Exported because they already are a contract:
+// `@kokuin/capability` asserts on them by string literal across a package boundary. `FoldResult.reason`
+// stays a plain string, so these name values rather than widening the type.
+/** A verifier threw. The thrown message is appended after `: `, so match with `startsWith`. */ export const CAPABILITY_VERIFIER_FAILED = 'capability verifier failed';
+/** A verifier answered with something that is not a {@link CapabilityAuthorisation}. */ export 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 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 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 const CAPABILITY_REVOKE_NEEDS_VERIFIER = 'capability-authorised revoke needs a verifier';
+/**
+ * Whether a log entry has the envelope shape everything downstream reads without checking. The
+ * fold's input is untrusted (`JSON.parse` of whatever was on the wire), so `signed.event`/`signed.sigs`
+ * are assumptions until checked; unchecked they are reachable `TypeError`s, and the worst case is
+ * not the throw but that `resolveBranches` filters branches by folding them — so one malformed entry
+ * could crash duplicity resolution for every honest branch beside it.
+ *
+ * Only the envelope is checked here; what the body must contain depends on `t` and stays with each
+ * verifier. Canonicalizability is checked here too: every path out canonicalizes the whole body
+ * (signature hash, `digestOf`), and both ways it can refuse (`Infinity` from `1e400`, nesting past
+ * `MAX_CANONICAL_DEPTH`) arrive as ordinary wire input. Both are the same failure as a bad shape — a
+ * `FoldResult`, not an exception from a fold documented total.
+ */ function isSignedEventShape(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    const signed = value;
+    if (signed.event == null || typeof signed.event !== 'object') {
+        return false;
+    }
+    if (!Array.isArray(signed.sigs) || signed.sigs.some((sig)=>typeof sig !== 'string')) {
+        return false;
+    }
+    if (signed.recoveryKey !== undefined && typeof signed.recoveryKey !== 'string') {
+        return false;
+    }
+    // The body is canonicalized as the top-level value, so this is exactly what the canonicalizer sees.
+    return isCanonicalizable(signed.event);
+}
+/**
+ * Validate one event against the state so far and produce the next state. Pure and total — every
+ * rejection is a returned reason, never a throw. Criticality is decided here so both entry points
+ * inherit it: an unknown critical event fails closed, an unknown `crit: false` event at the next
+ * position is skipped (prior state carried forward unchanged), and anything else fails closed.
+ */ function stepEvent(did, inception, signed, prior) {
+    if (!isSignedEventShape(signed)) {
+        return {
+            status: 'fail',
+            reason: MALFORMED_EVENT
+        };
+    }
+    const event = signed.event;
+    if (event.i !== did) {
+        return {
+            status: 'fail',
+            reason: 'event names a different controller'
+        };
+    }
+    if (event.t === 'rot') {
+        const rot = signed;
+        const isReset = rot.event.g > prior.gen;
+        if (isReset) {
+            // A reset chains to the inception, not the head, so `p` is recomputable without the log. This
+            // reason is unobservable (`verifyReset` below rejects the same event with `invalid reset`) but
+            // stays because `s` is wire data and this states what a reset's sequence must be — do not spend
+            // a round trying to reach it.
+            if (rot.event.s !== 0) {
+                return {
+                    status: 'fail',
+                    reason: 'reset must restart the sequence'
+                };
+            }
+            if (!verifyReset(rot, inception)) {
+                return {
+                    status: 'fail',
+                    reason: 'invalid reset'
+                };
+            }
+        } else {
+            if (rot.event.p !== prior.digest) {
+                return {
+                    status: 'fail',
+                    reason: 'event does not chain to the previous digest'
+                };
+            }
+            if (rot.event.g !== prior.gen || rot.event.s !== prior.seq + 1) {
+                return {
+                    status: 'fail',
+                    reason: 'sequence gap'
+                };
+            }
+            if (!verifyRotate(rot, {
+                digest: prior.digest,
+                n: prior.next
+            })) {
+                return {
+                    status: 'fail',
+                    reason: 'invalid rotate'
+                };
+            }
+        }
+        // The deny set this rotate leaves behind: its own snapshot when it carries one (validated by
+        // `isPublishedRotate`), else the accumulated set carried forward.
+        const denyAfter = rot.event.d == null ? prior.deny : new Set(rot.event.d);
+        // A key this event *establishes* must not be one it denies. `d` and the carried-forward set are
+        // both attacker-influenced, so without this a single rotate could publish a key and deny it in
+        // one breath, and the `KeyState.deny` invariant would hold only by good manners. Failing the fold
+        // is the only answer: applying it leaves a head whose `k` resolves to nothing.
+        const establishedButDenied = [
+            ...rot.event.k,
+            ...rot.event.ka
+        ].find((key)=>denyAfter.has(keyTarget(key)));
+        if (establishedButDenied != null) {
+            return {
+                status: 'fail',
+                reason: `rotate establishes a denied key: ${establishedButDenied}`
+            };
+        }
+        return {
+            status: 'ok',
+            state: {
+                did,
+                gen: rot.event.g,
+                seq: rot.event.s,
+                // New keys are one derivation index on from the last that established one — not at `s`, which
+                // any intervening revoke advanced. A reset opens a fresh generation, so its index restarts at
+                // 0 (also its `s`).
+                keyGen: rot.event.g,
+                keySeq: isReset ? 0 : prior.keySeq + 1,
+                keys: rot.event.k,
+                agreement: rot.event.ka,
+                next: rot.event.n,
+                // Carried, never replaced — including across a reset. See `KeyState.recovery`.
+                recovery: prior.recovery,
+                deny: denyAfter,
+                digest: digestOf(rot.event)
+            }
+        };
+    }
+    if (event.p !== prior.digest) {
+        return {
+            status: 'fail',
+            reason: 'event does not chain to the previous digest'
+        };
+    }
+    if (event.t === 'rev') {
+        const rev = signed;
+        if (rev.event.g !== prior.gen || rev.event.s !== prior.seq + 1) {
+            return {
+                status: 'fail',
+                reason: 'sequence gap'
+            };
+        }
+        // `x` goes into the deny set and, for a cap-authorised revoke, into the verifier as the resource
+        // asked for — where a wildcard grant would happily authorise denying `undefined`.
+        if (typeof rev.event.x !== 'string') {
+            return {
+                status: 'fail',
+                reason: 'revoke names no target'
+            };
+        }
+        // `cap` crosses a callback boundary into caller-supplied code, the one place a wire value is
+        // handed to something that cannot have checked it. `x` above was checked and this was not.
+        if (rev.event.cap !== undefined && typeof rev.event.cap !== 'string') {
+            return {
+                status: 'fail',
+                reason: 'revoke capability is not a serialized token'
+            };
+        }
+        // A key target may not name a key this position currently publishes. `resolve` is head-only, so
+        // a key still in `k` is one the profile asserts it signs with *now*; the event that stops that is
+        // `rotate` (whose pre-rotation commitment the leaked-key holder cannot forge), and denial is for
+        // what the rotate leaves behind — the historic path, which survives a rotate. So: rotate-then-deny.
+        // Allowing it would let one cap-authorised revoke (wildcard `res`) from a device that never held
+        // the sub-seed disable the root tier, and leave a head whose own `k` the resolver must refuse.
+        const deniedKey = keyFromTarget(rev.event.x);
+        if (deniedKey != null && (prior.keys.includes(deniedKey) || prior.agreement.includes(deniedKey))) {
+            return {
+                status: 'fail',
+                reason: `revoke names a key the profile publishes: ${rev.event.x}`
+            };
+        }
+        const deny = new Set(prior.deny);
+        deny.add(rev.event.x);
+        // `keyGen`/`keySeq` ride along in the spread: a revoke establishes no key, so the active position
+        // is still wherever the last icp/rot put it.
+        const state = {
+            ...prior,
+            seq: rev.event.s,
+            deny,
+            digest: digestOf(rev.event)
+        };
+        if (rev.event.cap != null) {
+            return {
+                status: 'capability',
+                cap: rev.event.cap,
+                target: rev.event.x,
+                state,
+                signed: rev
+            };
+        }
+        if (!verifyRevoke(rev, {
+            digest: prior.digest,
+            keys: prior.keys
+        })) {
+            return {
+                status: 'fail',
+                reason: 'invalid revoke'
+            };
+        }
+        return {
+            status: 'ok',
+            state
+        };
+    }
+    // Unknown type. Criticality lives in the envelope so this decision needs no understanding of `t`;
+    // failing closed on a critical event stops a verifier that does not understand `rev` accepting a
+    // revoked device. Only an explicit `crit: false` skips: `crit` is wire data, an absent member is
+    // falsy, so a truthiness test would let an attacker claim the skip path by *omitting* the flag. The
+    // two reasons separate "declared critical" from "declared nothing".
+    if (event.crit !== false) {
+        return {
+            status: 'fail',
+            reason: event.crit ? `unknown critical event type: ${String(event.t)}` : `unknown event type with no criticality flag: ${String(event.t)}`
+        };
+    }
+    // A skipped event is the only one accepted without a signature check, so it must not claim a
+    // position it did not earn. `p` is checked above; without this, `g`/`s` were free wire data on an
+    // unsigned event, and anything ordering branches by the raw head could be handed
+    // `Number.MAX_SAFE_INTEGER` by someone holding no key material.
+    if (event.g !== prior.gen || event.s !== prior.seq + 1) {
+        return {
+            status: 'fail',
+            reason: 'sequence gap'
+        };
+    }
+    // Non-critical: skip, carrying state forward so positions stay aligned with the input array. `seq`
+    // deliberately does not advance — the skipped event established nothing — so a run of skipped
+    // events all claim the same `s`.
+    return {
+        status: 'ok',
+        state: {
+            ...prior,
+            digest: prior.digest
+        },
+        skipped: true
+    };
+}
+/**
+ * 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 const MAX_SKIPPED_SLACK = 8;
+/** What a log padded past {@link MAX_SKIPPED_SLACK} fails with. */ export const TOO_MANY_UNKNOWN_EVENTS = 'too many unknown events';
+/**
+ * The running budget for skipped events, shared by both fold entry points so the two cannot drift.
+ * `understood` counts validated events (the inception is the first), `skipped` the ones carried past.
+ * Checked as each skipped event arrives, so a padded log stops folding at the point it exceeds the
+ * budget rather than after.
+ */ function skipBudget() {
+    let understood = 1;
+    let skipped = 0;
+    return {
+        understood () {
+            understood++;
+        },
+        skip () {
+            skipped++;
+            return skipped <= understood + MAX_SKIPPED_SLACK;
+        }
+    };
+}
+/**
+ * Validate the inception and seed the state array both fold entry points start from. Shared so the
+ * sync/async split begins only where the two loops differ.
+ */ function initFold(did, events) {
+    if (!Array.isArray(events)) {
+        return {
+            ok: false,
+            result: fail('malformed log', 0)
+        };
+    }
+    if (events.length === 0) {
+        return {
+            ok: false,
+            result: fail('empty log', 0)
+        };
+    }
+    if (!isSignedEventShape(events[0])) {
+        return {
+            ok: false,
+            result: fail(MALFORMED_EVENT, 0)
+        };
+    }
+    const first = events[0];
+    // Unobservable, like `reset must restart the sequence`: `verifyInception` checks `t` too and
+    // rejects the same log with `invalid inception`. Kept because `t` is wire data and this states what
+    // a log must open with; recorded as unreachable so the next reader does not hunt for the test.
+    if (first.event.t !== 'icp') {
+        return {
+            ok: false,
+            result: fail('first event must be an inception', 0)
+        };
+    }
+    if (!verifyInception(first, did)) {
+        return {
+            ok: false,
+            result: fail('invalid inception', 0)
+        };
+    }
+    return {
+        ok: true,
+        inception: first.event,
+        states: [
+            {
+                did,
+                gen: first.event.g,
+                seq: first.event.s,
+                keyGen: first.event.g,
+                // The derivation index, not the event position — the same number for every inception this
+                // package builds (`s` is 0). Writing `s` here would hand a self-certifying log carrying any
+                // `s` a `KeyState` naming a key it never committed.
+                keySeq: 0,
+                keys: first.event.k,
+                agreement: first.event.ka,
+                next: first.event.n,
+                recovery: first.event.r,
+                deny: new Set(),
+                digest: digestOf(first.event)
+            }
+        ]
+    };
+}
+/**
+ * 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 function foldLog(did, events) {
+    const init = initFold(did, events);
+    if (!init.ok) {
+        return init.result;
+    }
+    const { inception, states } = init;
+    const budget = skipBudget();
+    for(let i = 1; i < events.length; i++){
+        const outcome = stepEvent(did, inception, events[i], states[i - 1]);
+        if (outcome.status === 'fail') {
+            return fail(outcome.reason, i);
+        }
+        if (outcome.status === 'capability') {
+            return fail(`${CAPABILITY_REVOKE_NEEDS_ASYNC_FOLD}: ${outcome.cap}`, i);
+        }
+        if (outcome.skipped) {
+            if (!budget.skip()) {
+                return fail(TOO_MANY_UNKNOWN_EVENTS, i);
+            }
+        } else {
+            budget.understood();
+        }
+        states.push(outcome.state);
+    }
+    return {
+        ok: true,
+        states
+    };
+}
+/**
+ * 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 async function foldLogAsync(did, events, options = {}) {
+    const init = initFold(did, events);
+    if (!init.ok) {
+        return init.result;
+    }
+    const { inception, states } = init;
+    const budget = skipBudget();
+    for(let i = 1; i < events.length; i++){
+        const outcome = stepEvent(did, inception, events[i], states[i - 1]);
+        if (outcome.status === 'fail') {
+            return fail(outcome.reason, i);
+        }
+        if (outcome.status === 'capability') {
+            if (options.verifyCapability == null) {
+                return fail(`${CAPABILITY_REVOKE_NEEDS_VERIFIER}: ${outcome.cap}`, i);
+            }
+            // The fold is total by contract; a verifier is caller-supplied code TypeScript cannot police
+            // across a package boundary or a stale build. Both ways it can break the contract — throwing,
+            // and answering with the wrong shape — come back as a `FoldResult` with a real reason, never an
+            // escaping exception or an `undefined` reason. Our adapter never throws; a third party's need
+            // not, and a throw is not evidence the capability authorises anything.
+            let authorisation;
+            try {
+                authorisation = await options.verifyCapability({
+                    cap: outcome.cap,
+                    subject: did,
+                    target: outcome.target,
+                    // A copy: `states` keeps growing, and this resolver must keep answering for the position it
+                    // was built at even if the verifier holds on to it.
+                    subjectAtPosition: createStateResolver(did, [
+                        ...states
+                    ])
+                });
+            } catch (cause) {
+                return fail(`${CAPABILITY_VERIFIER_FAILED}: ${cause instanceof Error ? cause.message : String(cause)}`, i);
+            }
+            if (!isCapabilityAuthorisation(authorisation)) {
+                return fail(CAPABILITY_VERIFIER_MALFORMED_ANSWER, i);
+            }
+            if (!authorisation.authorised) {
+                return fail(authorisation.reason, i);
+            }
+            // The capability authorises its audience, not its bearer. Checked here rather than left to the
+            // verifier so a verifier that simply forgot cannot make the fold accept a revoke from anyone
+            // who read the log — see `CapabilityAuthorisation`.
+            if (!verifyEventSignedBy(outcome.signed, authorisation.audienceKey)) {
+                return fail(REVOKE_NOT_SIGNED_BY_AUDIENCE, i);
+            }
+        }
+        if (outcome.status === 'ok' && outcome.skipped) {
+            if (!budget.skip()) {
+                return fail(TOO_MANY_UNKNOWN_EVENTS, i);
+            }
+        } else {
+            budget.understood();
+        }
+        states.push(outcome.state);
+    }
+    return {
+        ok: true,
+        states
+    };
+}
+export function keyStateAt(result, position) {
+    return result.ok ? result.states[position] : 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 function pruneDenySet(state, drop) {
+    const dropped = new Set(drop);
+    return [
+        ...state.deny
+    ].filter((entry)=>!dropped.has(entry));
+}

package/lib/history.d.ts

@@ -0,0 +1,63 @@
+import type { SignedEvent } from './events.js';
+import { type FoldOptions, type KeyState } from './fold.js';
+/**
+ * Where a consumer keeps the last log it accepted for a DID, so the next one can be compared against
+ * it.
+ *
+ * A folded log carries no proof it is the *whole* log: a peer serving a prefix — stopping just before
+ * the `rev` denying their device — produces one that folds cleanly and yields a deny set missing
+ * exactly the entry that matters. Nothing inside a single log distinguishes truncation from a log
+ * that is simply short, so the fork-detection limitation does not reach it: there is no second branch,
+ * only an honest-looking prefix. Comparing against what this party has already seen supplies the
+ * missing second branch — a local guarantee, not a global one (it does nothing on a first encounter),
+ * but the difference between a suppression attack that works once and one that works every time.
+ *
+ * Deliberately not a high-water mark over `(gen, seq)`. Supersession legitimately *lowers* the
+ * sequence: a thief's long current-key branch is beaten by the owner's recovering rotate at a much
+ * lower `seq`, which a "never go backwards" mark would reject, bricking the profile as it is rescued.
+ * A divergence is settled by {@link resolveBranchesAsync} instead.
+ */
+export type LogStore = {
+    /** The last accepted log for this DID, or undefined when none has been seen. */
+    get(did: string): Promise<Array<SignedEvent> | undefined>;
+    /** Record a log as the last accepted one. Called only after it has folded. */
+    set(did: string, log: Array<SignedEvent>): Promise<void>;
+};
+/** What a resolver answers with when the log it loaded loses to the one already seen. */
+export declare const LOG_NOT_AUTHORITATIVE = "the loaded log does not supersede the one already seen";
+/** What a resolver answers with when the loaded log and the one already seen are a genuine fork. */
+export declare const LOG_FORKED = "the loaded log and the one already seen are a fork";
+/**
+ * An in-memory {@link LogStore}. Enough for a process that resolves the same DIDs repeatedly, and for
+ * tests; a consumer that survives restarts wants a persistent one, since the guarantee is only as
+ * durable as the memory of what was seen.
+ */
+export declare function createMemoryLogStore(): LogStore;
+/**
+ * Fold the loaded log, having established that it is not behind one this party has already seen.
+ *
+ * The two rejections are throws because a resolver has no other way to say "I will not answer for this
+ * DID", and answering from the loser is the failure this prevents: a prefix loses to the log it is a
+ * prefix of (truncation refused), and a fork is refused outright (resolving to either side is a
+ * guess). The comparison is on the **folded head digest**, never array identity — the same history
+ * re-loaded is a different array, and identity would reject the commonest call there is.
+ *
+ * A stored log that no longer folds is treated as no memory, but only when it *genuinely* no longer
+ * folds: local corruption or a tightened fold rule is one round of the guarantee to give up, since
+ * only a folded log was ever stored and refusing forever would brick every cached profile. A stored
+ * log that fails only because this call has no `verifyCapability` for a cap-authorised revoke it
+ * carries is the opposite — nothing changed, the call is simply not equipped — so it fails closed;
+ * treating it as no memory would disable the truncation guard for management-tier profiles.
+ *
+ * The states are returned so the caller does not fold twice; the log travels with them for the store.
+ */
+export declare function authoritativeStates({ did, loaded, seen, context, options, }: {
+    did: string;
+    loaded: Array<SignedEvent>;
+    seen: Array<SignedEvent> | undefined;
+    context: string;
+    options: FoldOptions;
+}): Promise<{
+    log: Array<SignedEvent>;
+    states: Array<KeyState>;
+}>;

package/lib/history.js

@@ -0,0 +1,97 @@
+import { foldLogAsync } from './fold.js';
+import { allStatesAsync } from './state.js';
+import { needsCapabilityVerification, resolveBranchesAsync } from './supersede.js';
+/** What a resolver answers with when the log it loaded loses to the one already seen. */ export const LOG_NOT_AUTHORITATIVE = 'the loaded log does not supersede the one already seen';
+/** What a resolver answers with when the loaded log and the one already seen are a genuine fork. */ export const LOG_FORKED = 'the loaded log and the one already seen are a fork';
+/**
+ * An in-memory {@link LogStore}. Enough for a process that resolves the same DIDs repeatedly, and for
+ * tests; a consumer that survives restarts wants a persistent one, since the guarantee is only as
+ * durable as the memory of what was seen.
+ */ export function createMemoryLogStore() {
+    const logs = new Map();
+    return {
+        async get (did) {
+            return logs.get(did);
+        },
+        async set (did, log) {
+            logs.set(did, log);
+        }
+    };
+}
+/**
+ * Fold the loaded log, having established that it is not behind one this party has already seen.
+ *
+ * The two rejections are throws because a resolver has no other way to say "I will not answer for this
+ * DID", and answering from the loser is the failure this prevents: a prefix loses to the log it is a
+ * prefix of (truncation refused), and a fork is refused outright (resolving to either side is a
+ * guess). The comparison is on the **folded head digest**, never array identity — the same history
+ * re-loaded is a different array, and identity would reject the commonest call there is.
+ *
+ * A stored log that no longer folds is treated as no memory, but only when it *genuinely* no longer
+ * folds: local corruption or a tightened fold rule is one round of the guarantee to give up, since
+ * only a folded log was ever stored and refusing forever would brick every cached profile. A stored
+ * log that fails only because this call has no `verifyCapability` for a cap-authorised revoke it
+ * carries is the opposite — nothing changed, the call is simply not equipped — so it fails closed;
+ * treating it as no memory would disable the truncation guard for management-tier profiles.
+ *
+ * The states are returned so the caller does not fold twice; the log travels with them for the store.
+ */ export async function authoritativeStates({ did, loaded, seen, context, options }) {
+    const states = await allStatesAsync({
+        did,
+        events: loaded,
+        context,
+        options: options
+    });
+    if (seen == null || seen.length === 0) {
+        return {
+            log: loaded,
+            states
+        };
+    }
+    const previous = await foldLogAsync(did, seen, options);
+    if (!previous.ok) {
+        // "Fold rule tightened" is safe to treat as no memory (only a folded log was stored, so refusing
+        // forever would brick every cached profile). "I remember a management-tier log and got no verifier
+        // for it" is not: accepting the loaded log there disables the truncation guard for exactly those
+        // profiles, letting an attacker's prefix that stops before the cap-authorised `rev` be accepted
+        // because the fuller stored log is the one that could not be folded. Fail closed — what could not
+        // be checked is not evidence its target is absent.
+        if (needsCapabilityVerification(previous)) {
+            throw new Error(`${LOG_NOT_AUTHORITATIVE}: ${did}`);
+        }
+        return {
+            log: loaded,
+            states
+        };
+    }
+    const head = states[states.length - 1].digest;
+    // The loaded log extends, or is, the history seen: its fold passed through that head. Ordinary path.
+    if (states.some((state)=>state.digest === previous.states[previous.states.length - 1].digest)) {
+        return {
+            log: loaded,
+            states
+        };
+    }
+    // They diverge. Which is authoritative is what branch resolution answers, and the only thing that
+    // knows a superseding rotate outranks a longer branch of current-key events.
+    const resolved = await resolveBranchesAsync(did, [
+        seen,
+        loaded
+    ], options);
+    if (!resolved.ok) {
+        throw new Error(`${resolved.failure === 'duplicity' ? LOG_FORKED : LOG_NOT_AUTHORITATIVE}: ${did}`);
+    }
+    // A comparison that did not happen is a refusal, not a pass: `unverified` means one side could not
+    // be folded for want of a verifier. Always zero with one configured.
+    if (resolved.unverified > 0) {
+        throw new Error(`${LOG_NOT_AUTHORITATIVE}: ${did}`);
+    }
+    const winner = await foldLogAsync(did, resolved.winner, options);
+    if (!winner.ok || winner.states[winner.states.length - 1].digest !== head) {
+        throw new Error(`${LOG_NOT_AUTHORITATIVE}: ${did}`);
+    }
+    return {
+        log: loaded,
+        states
+    };
+}