@kokuin/controller 0.1.0

package/lib/identity.d.ts

@@ -0,0 +1,74 @@
+import { type FullIdentity, type SigningIdentity } from '@kokuin/token';
+import { type SignedEvent } from './events.js';
+import type { FoldOptions } from './fold.js';
+export type CreateControllerIdentityParams = {
+    seed: Uint8Array;
+    profile: number;
+    log: Array<SignedEvent>;
+};
+/**
+ * A signing identity for a `did:kokuin:` profile, whose `iss` is the profile DID.
+ *
+ * Takes the log and folds it here, so the signing key is always the one that log's current state
+ * establishes, never one the caller named. The log is the caller's freshness contract: an identity
+ * built from a stale or truncated log signs with a retired key, minting tokens a current verifier
+ * rejects. Rebuild from a re-read log after a rotation rather than holding one across it.
+ *
+ * The key is derived at `keyGen`/`keySeq`, not `gen`/`seq`: a revoke advances the sequence without
+ * establishing a key (Amendment A), so deriving at `gen`/`seq` would produce a key never in `k` — an
+ * unverifiable token, silently. Every token carries `kid: #<the key that signed it>`, so there is no
+ * `kid` parameter — one naming any other key is a request it could not honour, and is rejected on
+ * mismatch rather than dropped.
+ *
+ * Synchronous, and stays so (kubun's apply path depends on it): a log whose revoke carries a
+ * capability cannot fold without awaiting a verifier, so it throws here — use
+ * {@link createControllerIdentityAsync}.
+ *
+ * @throws when the log does not fold, or when the derived key is not one of the profile's current
+ * authority keys (a wrong `seed` or `profile` for this log).
+ */
+export declare function createControllerIdentity({ seed, profile, log, }: CreateControllerIdentityParams): FullIdentity;
+export type CreateControllerIdentityAsyncParams = CreateControllerIdentityParams & {
+    options?: FoldOptions;
+};
+/**
+ * Async sibling of {@link createControllerIdentity} for a log whose revoke carries a capability
+ * authorising a non-authority signer, which only `foldLogAsync` can check. Identical otherwise, so a
+ * log without such a revoke resolves to the same identity through either entry point.
+ *
+ * @param options forwarded to the async fold; without `verifyCapability` such a log still fails to
+ * fold rather than being trusted.
+ */
+export declare function createControllerIdentityAsync({ seed, profile, log, options, }: CreateControllerIdentityAsyncParams): Promise<FullIdentity>;
+export type CreateControllerIdentityWithKeyParams = {
+    privateKey: Uint8Array;
+    log: Array<SignedEvent>;
+};
+/**
+ * A signing identity for a `did:kokuin:` profile, from the current authority private key rather than
+ * the profile seed.
+ *
+ * The seed form above needs the root seed to derive the key, but the custody tiers say the daily path
+ * must not touch it: the root seed lives on a Ledger or cold mnemonic, and a device never receives the
+ * profile sub-seed (a sub-seed holder can derive the *next* key and therefore rotate, voiding
+ * pre-rotation). This is the same split {@link createRevokeWithKey} makes, for the same reason.
+ *
+ * What the key in hand can do is exactly the intended granularity: it signs as the profile and cannot
+ * rotate, since a rotate must reveal the key the log committed in `n` and only the seed derives that.
+ * Losing it costs a rotate-then-deny, not the identity. Takes the raw private key (no identity type
+ * here signs raw bytes; a `KeyStore` entry hands back exactly this); the public half is derived from
+ * it, so a caller cannot present one key and sign with another.
+ *
+ * @throws when the log does not fold, or when the key's public half is not one of the profile's
+ * current authority keys — a stale log, or a key the profile has rotated away.
+ */
+export declare function createControllerIdentityWithKey({ privateKey, log, }: CreateControllerIdentityWithKeyParams): SigningIdentity;
+export type CreateControllerIdentityWithKeyAsyncParams = CreateControllerIdentityWithKeyParams & {
+    options?: FoldOptions;
+};
+/**
+ * Async sibling of {@link createControllerIdentityWithKey}, for a log whose revoke carries a
+ * capability authorising a non-authority signer. The pairing is not incidental: a profile that uses
+ * the management tier is the same profile whose daily signer should not hold the seed.
+ */
+export declare function createControllerIdentityWithKeyAsync({ privateKey, log, options, }: CreateControllerIdentityWithKeyAsyncParams): Promise<SigningIdentity>;

package/lib/identity.js

@@ -0,0 +1,190 @@
+import { createKeyAgreementIdentityForDID, createSigningIdentityForDID } from '@kokuin/token';
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { agreementPath, authorityPath, deriveKeyPair } from './derivation.js';
+import { didFromInception } from './events.js';
+import { encodeKey } from './keys.js';
+import { currentState, currentStateAsync } from './state.js';
+const CONTEXT = 'Controller identity';
+/**
+ * The DID the log claims to be, read from its inception before any fold runs — the fold needs the DID
+ * to check the inception against, so it cannot be the thing that produces it.
+ */ function didFromLog(log) {
+    if (log.length === 0) {
+        throw new Error(`${CONTEXT}: empty log`);
+    }
+    const first = log[0];
+    if (first.event.t !== 'icp') {
+        throw new Error(`${CONTEXT}: first event must be an inception`);
+    }
+    return didFromInception(first.event);
+}
+/**
+ * Stamp `kid` on every token this identity signs, naming the key that produced the signature. The
+ * identity derives exactly one key pair, so `kid` is a fact about the signature, not an input: a
+ * caller-supplied one is only ever checked, never honoured — dropping a mismatched one silently would
+ * mint a token whose header names a key that did not sign it. Both spellings are checked:
+ * `options.kid` and `options.header.kid`.
+ */ function withKid(identity, kid) {
+    return {
+        ...identity,
+        async signToken (payload, options = {}) {
+            for (const supplied of [
+                options.kid,
+                options.header?.kid
+            ]){
+                if (supplied != null && supplied !== kid) {
+                    throw new Error(`${CONTEXT}: cannot sign under kid ${String(supplied)}, this identity holds ${kid}`);
+                }
+            }
+            return identity.signToken(payload, {
+                ...options,
+                header: {
+                    ...options.header,
+                    kid
+                }
+            });
+        }
+    };
+}
+/**
+ * Bind a private key the caller holds to the DID, having checked the folded state publishes its
+ * public half. Shared by all four entry points, so the membership rule and `kid` binding are written
+ * once. Membership, not `keys[0]`: a set may publish several keys and the one in hand need not be
+ * first (co-signers' keys belong to other holders); what must hold is that the resolver can answer
+ * with this key. A key outside the set signs unverifiable tokens, so fail loudly at construction.
+ */ function identityForKey({ privateKey, publicKey, did, state, mismatch }) {
+    if (state.keys.length === 0) {
+        // Defensive, unreachable through either fold today (`verifySignatures` rejects an empty key set,
+        // `rev` carries `keys` forward). Kept so a future event type that can empty the set fails here
+        // rather than deriving a key for a controller that publishes none. `resolver.ts` holds it too.
+        throw new Error(`Controller ${did} has no signing key`);
+    }
+    const key = encodeKey(publicKey, 'EdDSA');
+    if (!state.keys.includes(key)) {
+        throw new Error(`${CONTEXT}: ${mismatch} of ${did}`);
+    }
+    // The resolver picks by `kid` and defaults to `keys[0]`, so a token whose key is not first is
+    // unverifiable unless the header names the key that signed it.
+    return withKid(createSigningIdentityForDID(did, privateKey), `#${key}`);
+}
+/**
+ * Derive the signing key the folded state establishes and bind it to the DID. Shared by the sync and
+ * async seed entry points, which differ only in how they reach the state.
+ */ function identityForState({ seed, profile, did, state }) {
+    const authority = deriveKeyPair(seed, authorityPath(profile, state.keyGen, state.keySeq), 'EdDSA');
+    const signing = identityForKey({
+        privateKey: authority.privateKey,
+        publicKey: authority.publicKey,
+        did,
+        state,
+        mismatch: 'derived key is not one of the current authority keys'
+    });
+    // The agreement key sits at the same (keyGen, keySeq) as the authority key — both icp and rot
+    // derive them at matching indices, and a rev carries the agreement set forward — so one position
+    // locates both. Verified against the folded set, failing closed like the authority membership check.
+    const agreement = deriveKeyPair(seed, agreementPath(profile, state.keyGen, state.keySeq), 'X25519');
+    const encoded = encodeKey(agreement.publicKey, 'X25519');
+    if (!state.agreement.includes(encoded)) {
+        throw new Error(`${CONTEXT}: derived agreement key is not one of the current agreement keys of ${did}`);
+    }
+    return {
+        ...signing,
+        ...createKeyAgreementIdentityForDID(did, agreement.privateKey)
+    };
+}
+/**
+ * A signing identity for a `did:kokuin:` profile, whose `iss` is the profile DID.
+ *
+ * Takes the log and folds it here, so the signing key is always the one that log's current state
+ * establishes, never one the caller named. The log is the caller's freshness contract: an identity
+ * built from a stale or truncated log signs with a retired key, minting tokens a current verifier
+ * rejects. Rebuild from a re-read log after a rotation rather than holding one across it.
+ *
+ * The key is derived at `keyGen`/`keySeq`, not `gen`/`seq`: a revoke advances the sequence without
+ * establishing a key (Amendment A), so deriving at `gen`/`seq` would produce a key never in `k` — an
+ * unverifiable token, silently. Every token carries `kid: #<the key that signed it>`, so there is no
+ * `kid` parameter — one naming any other key is a request it could not honour, and is rejected on
+ * mismatch rather than dropped.
+ *
+ * Synchronous, and stays so (kubun's apply path depends on it): a log whose revoke carries a
+ * capability cannot fold without awaiting a verifier, so it throws here — use
+ * {@link createControllerIdentityAsync}.
+ *
+ * @throws when the log does not fold, or when the derived key is not one of the profile's current
+ * authority keys (a wrong `seed` or `profile` for this log).
+ */ export function createControllerIdentity({ seed, profile, log }) {
+    const did = didFromLog(log);
+    return identityForState({
+        seed,
+        profile,
+        did,
+        state: currentState(did, log, CONTEXT)
+    });
+}
+/**
+ * Async sibling of {@link createControllerIdentity} for a log whose revoke carries a capability
+ * authorising a non-authority signer, which only `foldLogAsync` can check. Identical otherwise, so a
+ * log without such a revoke resolves to the same identity through either entry point.
+ *
+ * @param options forwarded to the async fold; without `verifyCapability` such a log still fails to
+ * fold rather than being trusted.
+ */ export async function createControllerIdentityAsync({ seed, profile, log, options }) {
+    const did = didFromLog(log);
+    return identityForState({
+        seed,
+        profile,
+        did,
+        state: await currentStateAsync({
+            did,
+            events: log,
+            context: CONTEXT,
+            options: options
+        })
+    });
+}
+/**
+ * A signing identity for a `did:kokuin:` profile, from the current authority private key rather than
+ * the profile seed.
+ *
+ * The seed form above needs the root seed to derive the key, but the custody tiers say the daily path
+ * must not touch it: the root seed lives on a Ledger or cold mnemonic, and a device never receives the
+ * profile sub-seed (a sub-seed holder can derive the *next* key and therefore rotate, voiding
+ * pre-rotation). This is the same split {@link createRevokeWithKey} makes, for the same reason.
+ *
+ * What the key in hand can do is exactly the intended granularity: it signs as the profile and cannot
+ * rotate, since a rotate must reveal the key the log committed in `n` and only the seed derives that.
+ * Losing it costs a rotate-then-deny, not the identity. Takes the raw private key (no identity type
+ * here signs raw bytes; a `KeyStore` entry hands back exactly this); the public half is derived from
+ * it, so a caller cannot present one key and sign with another.
+ *
+ * @throws when the log does not fold, or when the key's public half is not one of the profile's
+ * current authority keys — a stale log, or a key the profile has rotated away.
+ */ export function createControllerIdentityWithKey({ privateKey, log }) {
+    const did = didFromLog(log);
+    return identityForKey({
+        privateKey,
+        publicKey: ed25519.getPublicKey(privateKey),
+        did,
+        state: currentState(did, log, CONTEXT),
+        mismatch: 'the supplied key is not one of the current authority keys'
+    });
+}
+/**
+ * Async sibling of {@link createControllerIdentityWithKey}, for a log whose revoke carries a
+ * capability authorising a non-authority signer. The pairing is not incidental: a profile that uses
+ * the management tier is the same profile whose daily signer should not hold the seed.
+ */ export async function createControllerIdentityWithKeyAsync({ privateKey, log, options }) {
+    const did = didFromLog(log);
+    return identityForKey({
+        privateKey,
+        publicKey: ed25519.getPublicKey(privateKey),
+        did,
+        state: await currentStateAsync({
+            did,
+            events: log,
+            context: CONTEXT,
+            options: options
+        }),
+        mismatch: 'the supplied key is not one of the current authority keys'
+    });
+}

package/lib/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * did:kokuin controller key event log.
+ *
+ * ## Installation
+ *
+ * ```sh
+ * npm install @kokuin/controller
+ * ```
+ *
+ * @module controller
+ */
+export { canonicalBytes, digestOf, isCanonicalizable, MAX_CANONICAL_DEPTH, verifyDigest, withinCanonicalDepth, } from './canonical.js';
+export { agreementPath, authorityPath, deriveKeyMaterial, deriveKeyPair, recoveryPath, } from './derivation.js';
+export { type CreateRevokeOptions, type CreateRotateOptions, createInception, createReset, createRevoke, createRevokeWithKey, createRotate, DID_PREFIX, didFor, didFromInception, type EventCommon, type EventType, type InceptionEvent, KEY_TARGET_PREFIX, keyFromTarget, keyTarget, type RevokeEvent, type RotateEvent, type SignedEvent, verifyInception, verifyReset, verifyRevoke, verifyRotate, verifySignatures, } from './events.js';
+export { CAPABILITY_REVOKE_NEEDS_ASYNC_FOLD, CAPABILITY_REVOKE_NEEDS_VERIFIER, CAPABILITY_VERIFIER_FAILED, CAPABILITY_VERIFIER_MALFORMED_ANSWER, type CapabilityAuthorisation, type FoldOptions, type FoldResult, foldLog, foldLogAsync, type KeyState, keyStateAt, MAX_SKIPPED_SLACK, pruneDenySet, REVOKE_NOT_SIGNED_BY_AUDIENCE, TOO_MANY_UNKNOWN_EVENTS, type VerifyCapabilityParams, } from './fold.js';
+export { authoritativeStates, createMemoryLogStore, LOG_FORKED, LOG_NOT_AUTHORITATIVE, type LogStore, } from './history.js';
+export { createControllerIdentity, createControllerIdentityAsync, createControllerIdentityWithKey, createControllerIdentityWithKeyAsync, } from './identity.js';
+export { decodeKey, encodeKey, type KeyAlgorithm, type TaggedKey, tryDecodeKey, } from './keys.js';
+export { type ProvideControllerIdentityParams, provideControllerIdentity, } from './keystore-identity.js';
+export { enumerateProfiles, handleForDID, type ProfileEntry } from './profiles.js';
+export { type ControllerResolverOptions, createControllerResolver } from './resolver.js';
+export { type Duplicity, type ResolveFailure, type ResolveResult, resolveBranches, resolveBranchesAsync, } from './supersede.js';
+export { VERSION_TAG } from './version.js';

package/lib/index.js

@@ -0,0 +1,22 @@
+/**
+ * did:kokuin controller key event log.
+ *
+ * ## Installation
+ *
+ * ```sh
+ * npm install @kokuin/controller
+ * ```
+ *
+ * @module controller
+ */ export { canonicalBytes, digestOf, isCanonicalizable, MAX_CANONICAL_DEPTH, verifyDigest, withinCanonicalDepth } from './canonical.js';
+export { agreementPath, authorityPath, deriveKeyMaterial, deriveKeyPair, recoveryPath } from './derivation.js';
+export { createInception, createReset, createRevoke, createRevokeWithKey, createRotate, DID_PREFIX, didFor, didFromInception, KEY_TARGET_PREFIX, keyFromTarget, keyTarget, verifyInception, verifyReset, verifyRevoke, verifyRotate, verifySignatures } from './events.js';
+export { CAPABILITY_REVOKE_NEEDS_ASYNC_FOLD, CAPABILITY_REVOKE_NEEDS_VERIFIER, CAPABILITY_VERIFIER_FAILED, CAPABILITY_VERIFIER_MALFORMED_ANSWER, foldLog, foldLogAsync, keyStateAt, MAX_SKIPPED_SLACK, pruneDenySet, REVOKE_NOT_SIGNED_BY_AUDIENCE, TOO_MANY_UNKNOWN_EVENTS } from './fold.js';
+export { authoritativeStates, createMemoryLogStore, LOG_FORKED, LOG_NOT_AUTHORITATIVE } from './history.js';
+export { createControllerIdentity, createControllerIdentityAsync, createControllerIdentityWithKey, createControllerIdentityWithKeyAsync } from './identity.js';
+export { decodeKey, encodeKey, tryDecodeKey } from './keys.js';
+export { provideControllerIdentity } from './keystore-identity.js';
+export { enumerateProfiles, handleForDID } from './profiles.js';
+export { createControllerResolver } from './resolver.js';
+export { resolveBranches, resolveBranchesAsync } from './supersede.js';
+export { VERSION_TAG } from './version.js';

package/lib/keys.d.ts

@@ -0,0 +1,9 @@
+export type KeyAlgorithm = 'EdDSA' | 'X25519';
+export type TaggedKey = {
+    alg: KeyAlgorithm;
+    publicKey: Uint8Array;
+};
+export declare function encodeKey(publicKey: Uint8Array, alg: KeyAlgorithm): string;
+/** Total: any malformed, unknown-codec, or wrong-length value yields undefined rather than throwing. */
+export declare function tryDecodeKey(value: string): TaggedKey | undefined;
+export declare function decodeKey(value: string): TaggedKey;

package/lib/keys.js

@@ -0,0 +1,61 @@
+import { decodeMultibase, encodeMultibase } from '@kokuin/token';
+/**
+ * Multicodec prefixes, following the `did:key` convention. Tagging is what makes a new algorithm
+ * additive: an untagged key is opaque bytes, and telling X25519 from a future algorithm of the
+ * same length would mean sniffing the length.
+ */ const CODECS = {
+    EdDSA: new Uint8Array([
+        0xed,
+        0x01
+    ]),
+    X25519: new Uint8Array([
+        0xec,
+        0x01
+    ])
+};
+/**
+ * Expected payload length per algorithm, checked after the codec prefix is stripped. A per-algorithm
+ * table rather than a bare `=== 32`, so a future algorithm with a different length slots in without
+ * touching this check. Without this, a bare untagged key can collide with a codec prefix by chance
+ * (about 1 in 65536) and be silently accepted at the wrong length, and a truncated payload of the
+ * right prefix but wrong length would mint a key that throws downstream instead of failing here.
+ */ const KEY_LENGTHS = {
+    EdDSA: 32,
+    X25519: 32
+};
+export function encodeKey(publicKey, alg) {
+    const codec = CODECS[alg];
+    const bytes = new Uint8Array(codec.length + publicKey.length);
+    bytes.set(codec, 0);
+    bytes.set(publicKey, codec.length);
+    return encodeMultibase(bytes);
+}
+/** Total: any malformed, unknown-codec, or wrong-length value yields undefined rather than throwing. */ export function tryDecodeKey(value) {
+    let bytes;
+    try {
+        bytes = decodeMultibase(value);
+    } catch  {
+        return undefined;
+    }
+    for (const alg of Object.keys(CODECS)){
+        const codec = CODECS[alg];
+        if (bytes.length > codec.length && bytes[0] === codec[0] && bytes[1] === codec[1]) {
+            const publicKey = bytes.slice(codec.length);
+            if (publicKey.length !== KEY_LENGTHS[alg]) {
+                return undefined;
+            }
+            return {
+                alg,
+                publicKey
+            };
+        }
+    }
+    return undefined;
+}
+export function decodeKey(value) {
+    const key = tryDecodeKey(value);
+    if (key == null) {
+        throw new Error(`Unrecognised key encoding: ${value}`);
+    }
+    return key;
+}

package/lib/keystore-identity.d.ts

@@ -0,0 +1,22 @@
+import type { FullIdentity, KeyEntry } from '@kokuin/token';
+import type { FoldOptions } from './fold.js';
+import type { LogStore } from './history.js';
+export type ProvideControllerIdentityParams = {
+    /** The seed source: `provideAsync()`'s bytes are the controller root seed. Generates on first use. */
+    entry: KeyEntry<Uint8Array>;
+    /** Which profile under the seed to resolve. */
+    profile: number;
+    /** Where the last accepted log for the DID lives — loaded to restore, written to on first generate. */
+    logStore: LogStore;
+    /** Forwarded to the fold for a log whose revoke carries a capability only the async fold can verify. */
+    options?: FoldOptions;
+};
+/**
+ * Resolve a `did:kokuin:` {@link FullIdentity} from a keystore entry and a log store.
+ *
+ * Generate and restore in one call: the entry yields the seed (a fresh one on first use, the stored
+ * one after), and the log store yields the event log (bootstrapping the inception when the DID has no
+ * log yet). The DID is a pure function of `(seed, profile)`, so the same entry and profile always
+ * resolve the same identity. A `KeyStore` caller passes `keyStore.entry(keyID)` as `entry`.
+ */
+export declare function provideControllerIdentity({ entry, profile, logStore, options, }: ProvideControllerIdentityParams): Promise<FullIdentity>;

package/lib/keystore-identity.js

@@ -0,0 +1,26 @@
+import { createInception, didFor } from './events.js';
+import { createControllerIdentityAsync } from './identity.js';
+/**
+ * Resolve a `did:kokuin:` {@link FullIdentity} from a keystore entry and a log store.
+ *
+ * Generate and restore in one call: the entry yields the seed (a fresh one on first use, the stored
+ * one after), and the log store yields the event log (bootstrapping the inception when the DID has no
+ * log yet). The DID is a pure function of `(seed, profile)`, so the same entry and profile always
+ * resolve the same identity. A `KeyStore` caller passes `keyStore.entry(keyID)` as `entry`.
+ */ export async function provideControllerIdentity({ entry, profile, logStore, options }) {
+    const seed = await entry.provideAsync();
+    const did = didFor(seed, profile);
+    let log = await logStore.get(did);
+    if (log == null) {
+        log = [
+            createInception(seed, profile)
+        ];
+        await logStore.set(did, log);
+    }
+    return createControllerIdentityAsync({
+        seed,
+        profile,
+        log,
+        options
+    });
+}

package/lib/profiles.d.ts

@@ -0,0 +1,21 @@
+export type ProfileEntry = {
+    index: number;
+    did: string;
+    handle: string;
+};
+/**
+ * A three-syllable handle derived from the DID itself — no stored data, no wordlist, so a cold picker
+ * can label profiles with no network or cache. Each syllable is consonant-vowel-consonant, so it is
+ * pronounceable; ~30 bits across three, ample to tell a handful of profiles apart and not a security
+ * boundary. The label is a function of the identifier, never the reverse (a user label must never
+ * feed the DID).
+ */
+export declare function handleForDID(did: string): string;
+/**
+ * Enumerate the first `count` profiles for a seed.
+ *
+ * Every index yields a valid-looking DID whether or not the profile was ever used — which
+ * profiles were used is not seed-derived. A picker should present all of them and let a probe
+ * grey out the unused ones when a group, hub, or cache is reachable.
+ */
+export declare function enumerateProfiles(seed: Uint8Array, count: number): Array<ProfileEntry>;

package/lib/profiles.js

@@ -0,0 +1,42 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { createInception, didFromInception } from './events.js';
+const encoder = new TextEncoder();
+// Frozen forever: a handle a user wrote down must keep resolving to the same profile. Letters
+// that are easily confused when read aloud or handwritten are left out — no c/k or q, no i/l.
+const CONSONANTS = 'bdfghjkmnprstvwz';
+const VOWELS = 'aeou';
+/**
+ * A three-syllable handle derived from the DID itself — no stored data, no wordlist, so a cold picker
+ * can label profiles with no network or cache. Each syllable is consonant-vowel-consonant, so it is
+ * pronounceable; ~30 bits across three, ample to tell a handful of profiles apart and not a security
+ * boundary. The label is a function of the identifier, never the reverse (a user label must never
+ * feed the DID).
+ */ export function handleForDID(did) {
+    const digest = sha256(encoder.encode(did));
+    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]);
+    }
+    return syllables.join('-');
+}
+/**
+ * Enumerate the first `count` profiles for a seed.
+ *
+ * Every index yields a valid-looking DID whether or not the profile was ever used — which
+ * profiles were used is not seed-derived. A picker should present all of them and let a probe
+ * grey out the unused ones when a group, hub, or cache is reachable.
+ */ export function enumerateProfiles(seed, count) {
+    if (!Number.isInteger(count) || count < 1) {
+        throw new Error('enumerateProfiles: count must be at least 1');
+    }
+    const entries = [];
+    for(let index = 0; index < count; index++){
+        const did = didFromInception(createInception(seed, index).event);
+        entries.push({
+            index,
+            did,
+            handle: handleForDID(did)
+        });
+    }
+    return entries;
+}

package/lib/resolver.d.ts

@@ -0,0 +1,56 @@
+import type { DIDMethodResolver } from '@kokuin/token';
+import { type SignedEvent } from './events.js';
+import type { FoldOptions } from './fold.js';
+import { type LogStore } from './history.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(),
+     * })
+     * ```
+     *
+     * 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.
+     */
+    verifyCapability?: FoldOptions['verifyCapability'];
+    /**
+     * 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
+     * cleanly and yields a deny set missing exactly that entry.
+     *
+     * Optional, because the guarantee needs storage this package cannot provide and a first encounter
+     * has nothing to compare against. **Configure one if this process resolves the same DIDs more than
+     * once.** See {@link LogStore}, and `createMemoryLogStore` for the process-lifetime version.
+     */
+    history?: LogStore;
+};
+/**
+ * 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.
+ */
+export declare function createControllerResolver(options: ControllerResolverOptions): DIDMethodResolver;