@kokuin/controller 0.1.0 → 0.2.0

package/lib/log.js

@@ -0,0 +1,268 @@
+import { digestOf } from './canonical.js';
+import { DEFAULT_EPOCH_LIMITS, foldEpochDetailed } from './epoch.js';
+import { isEpochEventShape } from './epoch-events.js';
+import { foldLog } from './fold.js';
+import { MAX_EPOCH_EVENTS, MAX_EVENT_PARENTS, MAX_LOG_EVENTS } from './limits.js';
+import { resolveBranches } from './supersede.js';
+/** What a request carrying more epoch events than {@link MAX_LOG_EVENTS} fails with. */ export const LOG_TOO_LARGE = 'controller log exceeds request limits';
+/**
+ * Request limit for a log this party holds or is about to merge into what it holds: one saturated
+ * epoch kept in memory (`MAX_EPOCH_EVENTS + 1` events) plus one presentation (`MAX_LOG_EVENTS`).
+ * What {@link epochHeads}, {@link pruneLog} and {@link mergeLogs} accept; anything larger is no log
+ * a verifier could have built and fails `LOG_TOO_LARGE`.
+ */ const MAX_HELD_EVENTS = MAX_EPOCH_EVENTS + 1 + MAX_LOG_EVENTS;
+/** What an input that is not a {@link ControllerLog} at all fails with. */ export const MALFORMED_LOG = 'malformed log';
+/**
+ * Whether `value` has the two lists a log is made of. Only the outer shape: every entry is untrusted
+ * and is checked by the fold that reads it, which reports a bad one rather than throwing.
+ */ export function isControllerLog(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    const log = value;
+    return Array.isArray(log.chain) && Array.isArray(log.events);
+}
+/** What a resolver answers with when the loaded log 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';
+/** What {@link mergeLogs} and {@link pruneLog} fail with when no chain they were given folds. */ export const LOG_UNFOLDABLE = 'no controller log chain folds';
+/**
+ * Fold a log this party already holds: the chain through the full fold, the epoch under the held
+ * request limit rather than `MAX_LOG_EVENTS`. The request limit bounds what one *input* may make a
+ * verifier do; a held log is the union of inputs that each passed it and is already bounded by what
+ * memory keeps (one epoch, at most `MAX_EPOCH_EVENTS + 1` events once saturated), but the union with a
+ * fresh presentation can exceed it. Folding through {@link foldLog} would turn that into
+ * `LOG_TOO_LARGE` — "no memory" — which is exactly the forgetting the history exists to prevent.
+ *
+ * Nothing in `log` is trusted: every signature is checked, under the failed-signature limit.
+ */ export function foldHeld(did, log, limits) {
+    if (!isControllerLog(log)) {
+        return {
+            ok: false,
+            reason: MALFORMED_LOG,
+            index: 0
+        };
+    }
+    if (log.events.length > MAX_HELD_EVENTS) {
+        return {
+            ok: false,
+            reason: LOG_TOO_LARGE,
+            index: -1
+        };
+    }
+    const chain = foldLog(did, {
+        chain: log.chain,
+        events: []
+    });
+    if (!chain.ok) {
+        return chain;
+    }
+    return withEpoch(did, chain.states, log.events, limits);
+}
+/**
+ * The chain's states merged with `events` as the current epoch, as {@link foldLog} reports it.
+ * `trusted` is this party's own memory (see `FoldEpochParams.trusted`), never a presentation. Refused,
+ * at index -1, when `events` passes the failed-signature limit.
+ */ export function withEpoch(did, states, events, limits, trusted) {
+    const merged = foldEpochDetailed({
+        did,
+        chainStates: states,
+        events,
+        limits,
+        trusted
+    });
+    if (!merged.ok) {
+        return {
+            ok: false,
+            reason: merged.reason,
+            index: -1
+        };
+    }
+    return {
+        result: {
+            ok: true,
+            states,
+            head: merged.head,
+            applied: merged.applied,
+            pending: merged.pending,
+            rejected: merged.rejected
+        },
+        authentic: merged.authentic
+    };
+}
+/**
+ * The parents an epoch event built now should name: the current epoch's applied events that no
+ * applied event names as a parent, sorted ascending, or `[head.epoch]` when none applied. An event
+ * naming every tip is causally after everything its author has seen, and authorisation is judged
+ * against exactly that causal past -- naming fewer leaves the author's own view out of it.
+ *
+ * Pending and rejected events are never heads: they are not part of the folded epoch. Throws, with
+ * the fold's reason, when the log does not fold; a builder has nothing to extend then.
+ *
+ * At most `MAX_EVENT_PARENTS` are returned, so the answer is always a valid `parents`: when the epoch
+ * has more tips (concurrent events are free to make), the smallest digests. The event built on them is
+ * causally after those alone; the rest stay tips, and the next event built from `epochHeads` names
+ * them, so repeated building folds every tip in. Throws `LOG_TOO_LARGE` on a log larger than any a
+ * verifier holds.
+ */ export function epochHeads(did, log) {
+    const held = foldHeld(did, log);
+    if ('ok' in held) {
+        throw new Error(`${held.reason}: ${did}`);
+    }
+    const { result, authentic } = held;
+    const named = new Set();
+    for (const digest of result.applied){
+        for (const parent of authentic.get(digest)?.event.p ?? []){
+            named.add(parent);
+        }
+    }
+    const heads = result.applied.filter((digest)=>!named.has(digest)).sort();
+    return heads.length === 0 ? [
+        result.head.epoch
+    ] : heads.slice(0, MAX_EVENT_PARENTS);
+}
+/**
+ * One copy of each event the fold applied, in the fold's own order (parents first): all that may be
+ * remembered of an epoch. An entry the fold did not apply was never authenticated, so it never
+ * reaches memory however it was presented.
+ *
+ * The copy is the one the fold itself verified, never re-derived here. Copies of one body share a
+ * digest and differ only in signatures, and the fold applies the event if *any* copy verifies — so
+ * "applied" alone does not say which copy to keep. Keeping the first one presented would let a relay
+ * put a forged copy ahead of the genuine one and have memory keep the forgery, losing the event on
+ * the next fold; re-checking signatures against a signer looked up afresh would answer a subtly
+ * different question from the one the fold answered, and drop the event whenever they disagree.
+ *
+ * Saturation: an epoch holding more than `MAX_EPOCH_EVENTS` applied events is kept as only the
+ * first `MAX_EPOCH_EVENTS + 1` of them. A prefix of the fold's topological order is closed under
+ * ancestors, and an event's authorisation is a function of its ancestors alone, so the prefix refolds
+ * to the same events applied — one more than the limit, saturated on every refold, never more held.
+ */ export function appliedCopies({ result, authentic }, limits) {
+    const maxEvents = limits?.MAX_EPOCH_EVENTS ?? DEFAULT_EPOCH_LIMITS.MAX_EPOCH_EVENTS;
+    const keep = result.head.saturated ? result.applied.slice(0, maxEvents + 1) : result.applied;
+    const kept = [];
+    for (const digest of keep){
+        const copy = authentic.get(digest);
+        if (copy !== undefined) {
+            kept.push({
+                event: copy.event,
+                sigs: [
+                    ...copy.sigs
+                ]
+            });
+        }
+    }
+    return kept;
+}
+function sameSignatures(a, b) {
+    return a.length === b.length && a.every((sig, i)=>sig === b[i]);
+}
+/**
+ * The chain two logs agree on: `b`'s when it extends (or is) `a`'s, otherwise whatever
+ * {@link resolveBranches} names. Throws when that is nothing — a fork ({@link LOG_FORKED}) or no
+ * chain that folds ({@link LOG_UNFOLDABLE}).
+ */ function settledChain(did, a, b) {
+    const left = foldLog(did, {
+        chain: a,
+        events: []
+    });
+    const right = foldLog(did, {
+        chain: b,
+        events: []
+    });
+    if (left.ok && right.ok) {
+        const through = left.states[left.states.length - 1]?.digest;
+        if (right.states.some((state)=>state.digest === through)) {
+            return b;
+        }
+    }
+    const resolved = resolveBranches(did, [
+        a,
+        b
+    ]);
+    if (!resolved.ok) {
+        throw new Error(`${resolved.failure === 'duplicity' ? LOG_FORKED : LOG_UNFOLDABLE}: ${did}`);
+    }
+    return resolved.winner;
+}
+/**
+ * Two views of one controller's log, combined. A pure merge, for a party joining what it holds with
+ * what it was handed (a grant's proof, a peer's copy) before folding.
+ *
+ * The chain is settled by the branch rules: `b`'s when it extends `a`'s, else the winner of
+ * {@link resolveBranches}, and a fork throws rather than merging two histories root never wrote as
+ * one. The events are a union, deduplicated by digest *and signatures*: a copy carrying different
+ * signatures is kept beside the first, since the fold applies an event when any copy verifies and
+ * keeping only the first would let a forged copy shadow the genuine one. Entries that are not epoch
+ * events at all are dropped; the fold would only have refused them.
+ *
+ * Nothing here authenticates an event. The result is input to a fold, not memory: persist what
+ * `authoritativeLog` returns instead. A union of two inputs can exceed the request limit a single
+ * input is held to, which {@link foldLog} then reports. Each input may be at most what a verifier
+ * holds plus one presentation; a larger one throws `LOG_TOO_LARGE` before any work.
+ */ export function mergeLogs(did, a, b) {
+    if (a.events.length > MAX_HELD_EVENTS || b.events.length > MAX_HELD_EVENTS) {
+        throw new Error(`${LOG_TOO_LARGE}: ${did}`);
+    }
+    const chain = settledChain(did, a.chain, b.chain);
+    const events = [];
+    const kept = new Map();
+    for (const entry of [
+        ...a.events,
+        ...b.events
+    ]){
+        if (!isEpochEventShape(entry)) continue;
+        const digest = digestOf(entry.event);
+        const signatures = kept.get(digest);
+        if (signatures?.some((sigs)=>sameSignatures(sigs, entry.sigs))) continue;
+        if (signatures === undefined) {
+            kept.set(digest, [
+                entry.sigs
+            ]);
+        } else {
+            signatures.push(entry.sigs);
+        }
+        events.push({
+            event: entry.event,
+            sigs: [
+                ...entry.sigs
+            ]
+        });
+    }
+    return {
+        chain,
+        events
+    };
+}
+/**
+ * The least of a log that still folds to the same head: the inception, the current generation's
+ * chain, and the current epoch's applied events.
+ *
+ * Earlier generations go because a reset chains to the inception, not to what preceded it, and the
+ * generation's keys and tombstones are read off the generation alone. Unknown events the chain fold
+ * skipped go too: they moved no state, so nothing chains to them. Earlier epochs' events go because
+ * an event naming another epoch has no effect; unapplied ones because they were never authenticated.
+ * A saturated epoch keeps exactly enough to stay saturated (see {@link appliedCopies}).
+ *
+ * Meant for a log this party already holds: the epoch is folded under the held request limit, not
+ * `MAX_LOG_EVENTS` (see {@link foldHeld}). Throws {@link LOG_UNFOLDABLE} when the chain does not fold,
+ * and the request limit's reason when the log passes one.
+ */ export function pruneLog(did, log) {
+    const held = foldHeld(did, log);
+    if (!('result' in held)) {
+        // Index -1 is a request limit: the chain may fold fine, the log is refused as too much work.
+        throw new Error(held.index === -1 ? `${held.reason}: ${did}` : `${LOG_UNFOLDABLE}: ${did}: ${held.reason} at event ${held.index}`);
+    }
+    const { states, head } = held.result;
+    const chain = [];
+    for (const [i, signed] of log.chain.entries()){
+        const state = states[i];
+        const prior = states[i - 1];
+        if (i === 0 || state?.gen === head.gen && state.digest !== prior?.digest) {
+            chain.push(signed);
+        }
+    }
+    return {
+        chain,
+        events: appliedCopies(held)
+    };
+}

package/lib/members.d.ts

@@ -0,0 +1,103 @@
+import { type MemberEntry, type StateSnapshot } from './events.js';
+/** What a non-reset rotate missing either half of its state snapshot fails with. */
+export declare const ROTATE_NEEDS_SNAPSHOT = "rotate carries no state snapshot";
+/**
+ * What a snapshot fails with when its shape is wrong: `m` not a list of {@link MemberEntry}, a pin
+ * that is not an Ed25519 key, two entries for one `add` or one pinned key, or `d` not a key list.
+ */
+export declare const SNAPSHOT_MALFORMED = "malformed state snapshot";
+/** A snapshot member pinning a key on, or committed by, the generation's root chain. */
+export declare const SNAPSHOT_MEMBER_KEY_IS_ROOT = "snapshot member key is a root key";
+/** A snapshot member whose DID is not a `did:key` or long-form `did:peer:4` carrying its pin. */
+export declare const SNAPSHOT_MEMBER_DID_MISMATCH = "snapshot member DID does not carry its key";
+/** A rotate whose deny set leaves out a retired-key denial an earlier rotate checkpointed. */
+export declare const SNAPSHOT_DROPS_RETIRED_KEY = "snapshot drops a retired key denial";
+/**
+ * Whether `did` carries exactly `key` as its signing key: a `did:key` of that key, or a long-form
+ * `did:peer:4` whose document carries that one Ed25519 signing key and no other. Everything else is
+ * false — a short-form `did:peer:4` or a network-backed DID carries no key to check, and a document
+ * carrying a second signing key would let a grant verifier that reads the DID rather than the pin
+ * accept a key the log never admitted.
+ *
+ * Total: an identifier that claims to carry a key and does not (`signingKeysOf` throws on it) is
+ * simply not a match.
+ */
+export declare function memberCarriesKey(did: string, key: string): boolean;
+/**
+ * **The** predicate for "this denial targets this membership", and the only one: the member-revoke
+ * guard and denial dominance use exactly this. True iff `entry` is `#` plus the member's pinned key,
+ * or the member's DID under canonical DID equivalence (`normalizeDID`: the long and short forms of a
+ * `did:peer:4` are one DID).
+ *
+ * Nothing broader. "Any DID containing that public key" is not an alias: anyone can manufacture a
+ * document containing someone else's public key, so a `did:key` of a peer member's pin is a
+ * different DID, denied through the key target or not at all.
+ */
+export declare function denialTargetsMember(entry: string, member: MemberEntry): boolean;
+/** {@link denialTargetsMember}, as one fold asks it many times over. */
+export type DenialMatcher = (entry: string, member: MemberEntry) => boolean;
+/**
+ * {@link denialTargetsMember} with each DID canonicalised once. The predicate is the same; only the
+ * work is shared. A fold asks it for every deny entry against every member it judges, and a hostile
+ * entry can be a long-form `did:peer:4` close to the event byte limit, which `normalizeDID` decodes
+ * in full on every call. Scoped to one fold by its caller, so the cache holds only strings that
+ * fold was handed and dies with it.
+ */
+export declare function createDenialMatcher(): DenialMatcher;
+/**
+ * Every root key a member pin must stay clear of, for one generation: each `k`/`ka` on its chain,
+ * each commitment in an `n`, and the inception's recovery commitment (one recovery key per profile
+ * for its life, so a root key in every generation).
+ */
+export type RootKeySet = {
+    keys: ReadonlySet<string>;
+    /** Digests, as `n` carries them. */
+    commitments: ReadonlySet<string>;
+    /** A digest, as `r` carries it. */
+    recovery: string;
+};
+/**
+ * Whether `key` is a root key of the generation `root` describes. **The** disjointness test: a
+ * snapshot's members and an epoch's adds are judged by exactly this, so the two paths that admit a
+ * member cannot drift apart on which keys a management device may never hold.
+ */
+export declare function isRootKey(key: string, root: RootKeySet): boolean;
+export type ValidateSnapshotParams = {
+    snapshot: StateSnapshot;
+    /** Every `k`/`ka` on the current generation's chain, including the event carrying the snapshot. */
+    generationKeys: Array<string>;
+    /** Every `n` on the current generation's chain, including the event carrying the snapshot. */
+    generationCommitments: Array<string>;
+    /**
+     * The inception's recovery commitment (`r`, `KeyState.recovery`). Kept apart from
+     * `generationCommitments` because it is not a generation's: one recovery key per profile for its
+     * life, so it is a root key across every generation, the reset that reveals it included.
+     */
+    recovery: string;
+    /**
+     * The retired-key denials the snapshot must keep: the prior chain state's key-target denials that
+     * name a key in `generationKeys`. Empty on a reset, which opens a new generation.
+     */
+    tombstones: ReadonlySet<string>;
+};
+/**
+ * Judge a state snapshot against the generation it lands on: `null` when it may become the state,
+ * else the fold reason. Total on wire data — `snapshot` arrives from `JSON.parse` like everything
+ * else on the log, so no part of it is trusted to have the type it claims.
+ *
+ * Rules, in order:
+ *
+ * - **Shape** ({@link SNAPSHOT_MALFORMED}): `members` is a list of {@link MemberEntry} whose pins
+ *   decode as Ed25519, no two sharing an `add` (one incarnation, one entry) or a pinned key (one key
+ *   twice would let it renew itself through the alias); `deny` is a key list.
+ * - **Disjoint from root** ({@link SNAPSHOT_MEMBER_KEY_IS_ROOT}): no pin is a `k`/`ka` on the
+ *   generation's chain, committed in one of its `n`, or the recovery key the inception commits. A
+ *   management device never holds a root key, so member authority and root authority cannot be
+ *   confused for each other.
+ * - **The DID carries the pin** ({@link SNAPSHOT_MEMBER_DID_MISMATCH}): see {@link memberCarriesKey}.
+ * - **Checkpointed retirements stay** ({@link SNAPSHOT_DROPS_RETIRED_KEY}): every tombstone is in
+ *   `deny`. Historic resolution would otherwise accept fresh tokens signed with a retired key again,
+ *   and the chain alone enforces it, so a pruned and a full store agree. Holder DID denials carry no
+ *   such rule: dropping one is a deliberate re-authorisation.
+ */
+export declare function validateSnapshot(params: ValidateSnapshotParams): string | null;

package/lib/members.js

@@ -0,0 +1,152 @@
+import { normalizeDID, signingKeysOf } from '@kokuin/token';
+import { digestOf } from './canonical.js';
+import { isKeyList, isMemberEntry, keyTarget } from './events.js';
+import { encodeKey, tryDecodeKey } from './keys.js';
+/** What a non-reset rotate missing either half of its state snapshot fails with. */ export const ROTATE_NEEDS_SNAPSHOT = 'rotate carries no state snapshot';
+/**
+ * What a snapshot fails with when its shape is wrong: `m` not a list of {@link MemberEntry}, a pin
+ * that is not an Ed25519 key, two entries for one `add` or one pinned key, or `d` not a key list.
+ */ export const SNAPSHOT_MALFORMED = 'malformed state snapshot';
+/** A snapshot member pinning a key on, or committed by, the generation's root chain. */ export const SNAPSHOT_MEMBER_KEY_IS_ROOT = 'snapshot member key is a root key';
+/** A snapshot member whose DID is not a `did:key` or long-form `did:peer:4` carrying its pin. */ export const SNAPSHOT_MEMBER_DID_MISMATCH = 'snapshot member DID does not carry its key';
+/** A rotate whose deny set leaves out a retired-key denial an earlier rotate checkpointed. */ export const SNAPSHOT_DROPS_RETIRED_KEY = 'snapshot drops a retired key denial';
+/**
+ * Whether `did` carries exactly `key` as its signing key: a `did:key` of that key, or a long-form
+ * `did:peer:4` whose document carries that one Ed25519 signing key and no other. Everything else is
+ * false — a short-form `did:peer:4` or a network-backed DID carries no key to check, and a document
+ * carrying a second signing key would let a grant verifier that reads the DID rather than the pin
+ * accept a key the log never admitted.
+ *
+ * Total: an identifier that claims to carry a key and does not (`signingKeysOf` throws on it) is
+ * simply not a match.
+ */ export function memberCarriesKey(did, key) {
+    let keys;
+    try {
+        keys = signingKeysOf(did);
+    } catch  {
+        return false;
+    }
+    if (keys == null || keys.length !== 1) {
+        return false;
+    }
+    const [carried] = keys;
+    return carried != null && carried.alg === 'EdDSA' && encodeKey(carried.publicKey, 'EdDSA') === key;
+}
+/**
+ * `normalizeDID`, total: it reads a `did:peer:4` long form apart, and a deny entry is arbitrary wire
+ * data. An entry it cannot read names nobody under canonical equivalence, so it compares as itself.
+ */ function canonicalDID(did) {
+    try {
+        return normalizeDID(did);
+    } catch  {
+        return did;
+    }
+}
+/**
+ * **The** predicate for "this denial targets this membership", and the only one: the member-revoke
+ * guard and denial dominance use exactly this. True iff `entry` is `#` plus the member's pinned key,
+ * or the member's DID under canonical DID equivalence (`normalizeDID`: the long and short forms of a
+ * `did:peer:4` are one DID).
+ *
+ * Nothing broader. "Any DID containing that public key" is not an alias: anyone can manufacture a
+ * document containing someone else's public key, so a `did:key` of a peer member's pin is a
+ * different DID, denied through the key target or not at all.
+ */ export function denialTargetsMember(entry, member) {
+    return targets(entry, member, canonicalDID);
+}
+function targets(entry, member, canonical) {
+    if (entry === keyTarget(member.key)) {
+        return true;
+    }
+    return entry.startsWith('did:') && canonical(entry) === canonical(member.did);
+}
+/**
+ * {@link denialTargetsMember} with each DID canonicalised once. The predicate is the same; only the
+ * work is shared. A fold asks it for every deny entry against every member it judges, and a hostile
+ * entry can be a long-form `did:peer:4` close to the event byte limit, which `normalizeDID` decodes
+ * in full on every call. Scoped to one fold by its caller, so the cache holds only strings that
+ * fold was handed and dies with it.
+ */ export function createDenialMatcher() {
+    const canonical = new Map();
+    const canonicalOnce = (did)=>{
+        let value = canonical.get(did);
+        if (value === undefined) {
+            value = canonicalDID(did);
+            canonical.set(did, value);
+        }
+        return value;
+    };
+    return (entry, member)=>targets(entry, member, canonicalOnce);
+}
+/**
+ * Whether `key` is a root key of the generation `root` describes. **The** disjointness test: a
+ * snapshot's members and an epoch's adds are judged by exactly this, so the two paths that admit a
+ * member cannot drift apart on which keys a management device may never hold.
+ */ export function isRootKey(key, root) {
+    if (root.keys.has(key)) {
+        return true;
+    }
+    const digest = digestOf(key);
+    return root.commitments.has(digest) || digest === root.recovery;
+}
+/**
+ * Judge a state snapshot against the generation it lands on: `null` when it may become the state,
+ * else the fold reason. Total on wire data — `snapshot` arrives from `JSON.parse` like everything
+ * else on the log, so no part of it is trusted to have the type it claims.
+ *
+ * Rules, in order:
+ *
+ * - **Shape** ({@link SNAPSHOT_MALFORMED}): `members` is a list of {@link MemberEntry} whose pins
+ *   decode as Ed25519, no two sharing an `add` (one incarnation, one entry) or a pinned key (one key
+ *   twice would let it renew itself through the alias); `deny` is a key list.
+ * - **Disjoint from root** ({@link SNAPSHOT_MEMBER_KEY_IS_ROOT}): no pin is a `k`/`ka` on the
+ *   generation's chain, committed in one of its `n`, or the recovery key the inception commits. A
+ *   management device never holds a root key, so member authority and root authority cannot be
+ *   confused for each other.
+ * - **The DID carries the pin** ({@link SNAPSHOT_MEMBER_DID_MISMATCH}): see {@link memberCarriesKey}.
+ * - **Checkpointed retirements stay** ({@link SNAPSHOT_DROPS_RETIRED_KEY}): every tombstone is in
+ *   `deny`. Historic resolution would otherwise accept fresh tokens signed with a retired key again,
+ *   and the chain alone enforces it, so a pruned and a full store agree. Holder DID denials carry no
+ *   such rule: dropping one is a deliberate re-authorisation.
+ */ export function validateSnapshot(params) {
+    const { snapshot, generationKeys, generationCommitments, recovery, tombstones } = params;
+    const members = snapshot.members;
+    const deny = snapshot.deny;
+    if (!Array.isArray(members) || !isKeyList(deny)) {
+        return SNAPSHOT_MALFORMED;
+    }
+    const adds = new Set();
+    const pins = new Set();
+    for (const entry of members){
+        if (!isMemberEntry(entry) || tryDecodeKey(entry.key)?.alg !== 'EdDSA') {
+            return SNAPSHOT_MALFORMED;
+        }
+        if (adds.has(entry.add) || pins.has(entry.key)) {
+            return SNAPSHOT_MALFORMED;
+        }
+        adds.add(entry.add);
+        pins.add(entry.key);
+    }
+    const root = {
+        keys: new Set(generationKeys),
+        commitments: new Set(generationCommitments),
+        recovery
+    };
+    for (const entry of members){
+        if (isRootKey(entry.key, root)) {
+            return SNAPSHOT_MEMBER_KEY_IS_ROOT;
+        }
+    }
+    for (const entry of members){
+        if (!memberCarriesKey(entry.did, entry.key)) {
+            return SNAPSHOT_MEMBER_DID_MISMATCH;
+        }
+    }
+    const denied = new Set(deny);
+    for (const tombstone of tombstones){
+        if (!denied.has(tombstone)) {
+            return SNAPSHOT_DROPS_RETIRED_KEY;
+        }
+    }
+    return null;
+}

package/lib/profiles.js

@@ -13,9 +13,15 @@ const VOWELS = 'aeou';
  * feed the DID).
  */ export function handleForDID(did) {
     const digest = sha256(encoder.encode(did));
+    const pick = (alphabet, byte)=>{
+        if (byte === undefined) {
+            throw new Error('handleForDID: digest too short');
+        }
+        return alphabet[byte % alphabet.length] ?? '';
+    };
     const syllables = [];
     for(let i = 0; i < 3; i++){
-        syllables.push(CONSONANTS[digest[i * 3] % CONSONANTS.length] + VOWELS[digest[i * 3 + 1] % VOWELS.length] + CONSONANTS[digest[i * 3 + 2] % CONSONANTS.length]);
+        syllables.push(pick(CONSONANTS, digest[i * 3]) + pick(VOWELS, digest[i * 3 + 1]) + pick(CONSONANTS, digest[i * 3 + 2]));
     }
     return syllables.join('-');
 }

package/lib/resolver.d.ts

@@ -1,45 +1,27 @@
 import type { DIDMethodResolver } from '@kokuin/token';
-import { type SignedEvent } from './events.js';
-import type { FoldOptions } from './fold.js';
+import type { EpochLimits } from './epoch.js';
 import { type LogStore } from './history.js';
+import { type ControllerLog } from './log.js';
 export type ControllerResolverOptions = {
     /**
      * Load a controller's event log. Returns undefined when the DID is unknown.
      *
-     * **Answer with the whole log**, even when a `verifyCapability` is configured. A capability
-     * authorising a revoke must be checked at the position the fold is at — a rotated-away key set must
-     * not verify a grant made under it, a device denied before that position must not author one —
-     * and neither question can be answered from a DID alone, all this callback receives. So neither is
-     * asked of it: the fold answers both by handing the verifier a resolver built from the prefix
-     * states. See `FoldOptions.verifyCapability`.
-     *
-     * ```ts
-     * const resolver = createControllerResolver({
-     *   loadLog: async (did) => await store.log(did),
-     *   verifyCapability: createControllerCapabilityVerifier(),
-     * })
-     * ```
+     * **Answer with the whole log**: the fold needs every chain event and every current-epoch event,
+     * and a prefix resolves to a head that is missing whatever came after it — a withheld epoch revoke
+     * is a denial this resolution does not see.
      *
      * Reuse the instance rather than building one per resolution: concurrent resolutions of one DID
      * share a single in-flight fold. Not a cache — the entry drops as soon as the fold settles.
      *
-     * One re-entry hazard remains, not this callback's: a `verifyToken` hook or a `resolver` passed to
-     * the capability verifier that resolves *this* DID through *this* resolver joins the calling fold
-     * and awaits a promise that cannot settle. Give such a hook a resolver of its own.
-     */
-    loadLog(did: string): Promise<Array<SignedEvent> | undefined>;
-    /**
-     * Verify a capability authorising a non-authority signer to revoke, forwarded to the fold. Optional
-     * because most logs carry none: without it a log containing one fails to fold rather than being
-     * trusted. `createControllerCapabilityVerifier()` from `@kokuin/capability` is the implementation;
-     * it needs a registry only for a chain delegate whose DID method is not resolvable from the
-     * identifier alone.
+     * One re-entry hazard remains, not this callback's: a `verifyToken` hook that resolves *this* DID
+     * through *this* resolver joins the calling fold and awaits a promise that cannot settle. Give such
+     * a hook a resolver of its own.
      */
-    verifyCapability?: FoldOptions['verifyCapability'];
+    loadLog(did: string): Promise<ControllerLog | undefined>;
     /**
      * Where to remember the last log accepted for each DID, so a later one that is *behind* it is
      * refused rather than answered from. Without one, truncation is a silent revocation bypass: a peer
-     * serving a prefix that stops just before the `rev` denying their device produces a log that folds
+     * serving a prefix that stops just before the event denying their device produces a log that folds
      * cleanly and yields a deny set missing exactly that entry.
      *
      * Optional, because the guarantee needs storage this package cannot provide and a first encounter
@@ -48,9 +30,32 @@ export type ControllerResolverOptions = {
      */
     history?: LogStore;
 };
+/**
+ * A `did:kokuin:` resolver that can also hand out frozen views of itself.
+ *
+ * `frozen()` returns a resolver that loads and folds each DID at most once for its lifetime and
+ * answers every member from that one fold. A verification asking several questions of one controller
+ * — is the issuer a member, which key does it pin, until when, is any audience on the delegation
+ * chain denied — must get them all from one state of the log: answered live, a revoke landing
+ * between two of them gives a verdict no single state of the log supports (a member checked before
+ * its removal, a denial checked after a settlement dropped it). Use one view per verification and
+ * drop it after, since it never sees anything newer than its first fold.
+ */
+export type ControllerResolver = DIDMethodResolver & {
+    frozen(): DIDMethodResolver;
+};
 /**
  * A `did:kokuin:` resolver for `@kokuin/token`. Injected rather than imported by token: this package
  * depends on token for signing, so the reverse import would cycle. Token resolves `iss` through the
  * interface without knowing the fold exists.
+ *
+ * Every member answers from the head (the chain's last state merged with the current epoch) except
+ * `resolveHistoric`, which scans the chain's states for a rotated-away key. While the epoch is
+ * saturated, every member refuses (see `resolverOver`).
+ */
+export declare function createControllerResolver(options: ControllerResolverOptions): ControllerResolver;
+/**
+ * {@link createControllerResolver} under lowered epoch limits. Test-only: saturation is then
+ * reachable without thousands of signatures. Not exported from the package.
  */
-export declare function createControllerResolver(options: ControllerResolverOptions): DIDMethodResolver;
+export declare function createControllerResolverWithin(options: ControllerResolverOptions, limits?: Partial<EpochLimits>): ControllerResolver;