@kubun/credential 0.17.4 → 0.18.0

package/lib/manager.js

@@ -1,1081 +1,46 @@
-import { isKeyAgreementIdentity, normalizeDID } from '@kokuin/token';
-import { HLC } from '@kubun/hlc';
-import { createDeviceAuthority } from './authority.js';
-import { buildCredentialEntry, buildCredentialKey } from './builder.js';
-import { AmbiguousCredentialWrapping, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialSecretRejected, CredentialSupersededBranch, CredentialTampered, CredentialUnopenable, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite } from './errors.js';
-import { createKeyCache } from './key-cache.js';
-import { createCredentialOpSigner, selectWinningBranch } from './op.js';
-import { createPinThrottle } from './pin-throttle.js';
-import { entryProvenanceFields } from './provenance.js';
-import { getSuite, isSupportedSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
-import { wrappableDID } from './wrappable.js';
-/** Kinds a user can be prompted for, as opposed to ones held as key material. */ const SECRET_FACTOR_KINDS = [
-    'passphrase',
-    'pin'
-];
-function isSecretFactorKind(kind) {
-    return SECRET_FACTOR_KINDS.includes(kind);
-}
+import { createManagerContext } from './manager-context.js';
+import { createEntryFunctions } from './manager-entries.js';
+import { createKeyMethods } from './manager-keys.js';
+import { createOpenFunctions } from './manager-open.js';
+import { createRecordFunctions } from './manager-records.js';
+import { createRemovalRecoveryFunctions } from './manager-removal-recovery.js';
+import { createRotateFunctions } from './manager-rotate.js';
 export function createCredentialManager(params) {
-    const { store, identity, runtime, hlc } = params;
-    const authority = params.authority ?? createDeviceAuthority(identity.id);
-    const decrypting = isKeyAgreementIdentity(identity) ? identity : null;
-    const ops = createCredentialOpSigner(identity);
-    const cache = createKeyCache({
-        ttl: params.unlockTTL,
-        now: params.now
-    });
-    const throttle = createPinThrottle({
-        ...params.pinThrottle,
-        now: params.now
-    });
-    // Concurrency guards for `openKey`:
-    // - `inFlight` collapses a thundering herd of input-free opens of one key into
-    //   a single unwrap; each waiter then takes its own clone from the cache.
-    // - `keyGeneration` (bumped by `lock`) and `lockAllEpoch` (bumped by `lockAll`)
-    //   let a lock landing mid-open suppress that open's `cache.set`, so an open
-    //   begun before the lock cannot re-warm the cache the lock just cleared. The
-    //   in-flight read still returns its key — it was already authorized; the lock
-    //   only means "do not stay warm."
-    const inFlight = new Map();
-    const keyGeneration = new Map();
-    let lockAllEpoch = 0;
-    // Input-bearing opens (a supplied pin/passphrase) never dedup: their outcome
-    // and the PIN throttle are caller-specific, so one caller's attempt must not
-    // stand in for another's.
-    const hasSuppliedInputs = (inputs)=>inputs != null && Object.values(inputs).some((value)=>value != null);
-    let floorPromise;
-    /**
-   * Floor the shared clock to the greatest stored entry HLC, once per manager.
-   *
-   * The engine floors from the graph mutation log, which credential writes never
-   * touch — they advance the same clock and leave no trace there, so this is the
-   * only read that can see them again after a restart where the OS clock stepped
-   * backward. Memoized so concurrent first-writes await one read.
-   */ async function ensureFloored() {
-        floorPromise ??= (async ()=>{
-            const max = await store.getMaxEntryHLC();
-            // An applied grant stores the granter's HLC verbatim, so the maximum can be
-            // a remote peer's string — and `HLC.parse` answers a malformed one with NaN
-            // fields that `receive` would carry into the clock.
-            const parsed = max == null ? null : HLC.tryParse(max);
-            if (parsed != null) {
-                hlc.receive(parsed);
-            }
-        })();
-        await floorPromise;
-    }
-    async function nextHLC() {
-        await ensureFloored();
-        return HLC.serialize(hlc.now());
-    }
-    /**
-   * Whether this device could ever satisfy a wrapping, given the chance to
-   * prompt.
-   *
-   * This is what separates "locked" from "unopenable", and the two need opposite
-   * responses from a caller. `recipient` is normalized at the comparison and
-   * never at the write: it is a key-resolution input stored in peer:4 long form,
-   * and folding it would make the wrapping unopenable.
-   */ function satisfiableFactors(descriptors) {
-        const needed = [];
-        for (const descriptor of descriptors){
-            if (isSecretFactorKind(descriptor.kind)) {
-                needed.push(descriptor.kind);
-                continue;
-            }
-            if (descriptor.kind !== 'did') {
-                return null;
-            }
-            const recipient = descriptor.params.recipient;
-            if (decrypting == null || typeof recipient !== 'string') {
-                return null;
-            }
-            if (normalizeDID(recipient) !== normalizeDID(identity.id)) {
-                return null;
-            }
-        }
-        return needed;
-    }
-    /**
-   * The wrapping this device holds by its own `did`.
-   *
-   * Not found by `recipient_did`: that column is populated only for the
-   * single-`did` headless default, so a `[did, pin]` wrapping has it null. The
-   * descriptors are the authority. More than one match throws rather than
-   * picking — silently re-wrapping the wrong row would leave the other one
-   * un-gated and look like success.
-   */ async function ownWrapping(keyID, keyVersion) {
-        const wrappings = await store.listWrappings(keyID, keyVersion);
-        const mine = wrappings.filter((wrapping)=>satisfiableFactors(wrapping.factors) != null && wrapping.factors.some((descriptor)=>descriptor.kind === 'did' && typeof descriptor.params.recipient === 'string' && normalizeDID(descriptor.params.recipient) === normalizeDID(identity.id)));
-        if (mine.length === 0) {
-            throw new CredentialNotFound('Credential wrapping for this device on key', keyID);
-        }
-        if (mine.length > 1) {
-            throw new AmbiguousCredentialWrapping(keyID, mine.length);
-        }
-        return mine[0];
-    }
-    /**
-   * Rebuild wrap-time inputs from stored descriptors.
-   *
-   * A `did` descriptor carries its recipient, so it reconstructs itself. A
-   * secret one carries a salt and a cost but never the secret, so the caller has
-   * to supply it again — the new wrapping's key is derived from every surviving
-   * factor, not only the one being changed.
-   */ function factorsFromDescriptors(descriptors, inputs) {
-        return descriptors.map((descriptor)=>{
-            if (descriptor.kind === 'did') {
-                const recipient = descriptor.params.recipient;
-                if (typeof recipient !== 'string') {
-                    throw new CredentialTampered('did factor descriptor carries no recipient');
-                }
-                return {
-                    kind: 'did',
-                    recipientDID: recipient
-                };
-            }
-            if (!isSecretFactorKind(descriptor.kind)) {
-                throw new NoAvailableFactor(descriptor.kind);
-            }
-            const input = inputs?.[descriptor.kind];
-            if (input == null) {
-                throw new NoAvailableFactor(descriptor.kind);
-            }
-            const { m, t, p } = descriptor.params;
-            // The cost travels with the factor: re-wrapping is not the moment to
-            // silently reset a wrapping that was deliberately made expensive.
-            const cost = typeof m === 'number' && typeof t === 'number' && typeof p === 'number' ? {
-                m,
-                t,
-                p
-            } : undefined;
-            return {
-                kind: descriptor.kind,
-                input,
-                cost
-            };
-        });
-    }
-    /**
-   * Re-wrap this device's own wrapping under a new factor list.
-   *
-   * The new row is written before the old one is deleted. A crash between the
-   * two leaves the key with two wrappings that both work; the reverse order
-   * could leave it with none, which for a credential key is unrecoverable.
-   */ async function rewrapOwn(keyID, inputs, change, methods) {
-        const key = await loadKey(keyID);
-        const existing = await ownWrapping(keyID, key.version);
-        const { contentKey, branchID } = await openKey(keyID, inputs);
-        const suite = getSuite(key.suite);
-        const wrappingID = runtime.getRandomID();
-        // `contentKey` is our own private clone from the cache; zero it once its use — this
-        // rewrap — is done, on success or throw. The `try` opens right after the
-        // acquisition so the caller-supplied `change` throwing also cannot leak it.
-        let wrapped;
-        try {
-            const factors = change(factorsFromDescriptors(existing.factors, inputs));
-            wrapped = await suite.wrap({
-                runtime,
-                contentKey,
-                factors,
-                wrappingID,
-                keyID,
-                keyVersion: key.version,
-                methods
-            });
-        } finally{
-            contentKey.fill(0);
-        }
-        const { descriptors, iv, wrappedKey } = wrapped;
-        const replacement = {
-            wrappingID,
-            keyID,
-            keyVersion: key.version,
-            factors: descriptors,
-            iv,
-            wrappedKey,
-            recipientDID: existing.recipient_did
-        };
-        await store.putWrapping(replacement, await ops.wrapping(replacement, await nextHLC(), branchID));
-        await store.deleteWrapping(existing.wrapping_id, await ops.tombstone({
-            subjectKind: 'wrapping',
-            subjectID: existing.wrapping_id,
-            keyID,
-            keyVersion: existing.key_version
-        }, await nextHLC()));
-    }
-    async function loadKey(keyID) {
-        const key = await store.getKey(keyID);
-        if (key == null) {
-            throw new CredentialNotFound('Credential key', keyID);
-        }
-        if (!isSupportedSuite(key.suite)) {
-            throw new UnsupportedCredentialSuite(key.suite);
-        }
-        return key;
-    }
-    /**
-   * Recover a key's content key by trying its wrappings.
-   *
-   * The wrappings are an OR: any one opening is enough. If none opens, which
-   * failure this is depends on whether any of them COULD have opened with input
-   * this device is able to ask for — locked and unopenable are the same event
-   * with opposite remedies.
-   */ /**
-   * Recover a key's content key. Wrapped by `openKey`, which adds the input-free
-   * dedup; this is the actual open. Captures the lock generation and epoch at
-   * entry so a `lock`/`lockAll` that lands before the terminal `cache.set` can
-   * suppress it — the key is still returned to this caller, but the cache is not
-   * re-warmed behind a lock.
-   */ async function doOpenKey(keyID, inputs, genAtStart, epochAtStart) {
-        // `genAtStart`/`epochAtStart` are captured by `openKey` at the moment the
-        // caller entered — before any dedup wait — so a lock that lands while a
-        // waiter is queued still suppresses that waiter's eventual re-warm.
-        const lockedSince = ()=>(keyGeneration.get(keyID) ?? 0) !== genAtStart || lockAllEpoch !== epochAtStart;
-        const key = await loadKey(keyID);
-        const proven = new Set((await store.listKeyBranches(keyID, key.version)).map((branch)=>branch.branch_id));
-        const winner = proven.size >= 2 ? selectWinningBranch([
-            ...proven
-        ]) : null;
-        const cached = cache.get(keyID, key.version);
-        if (cached != null) {
-            if (winner == null || cached.branchID === winner) {
-                return {
-                    contentKey: cached.contentKey,
-                    version: key.version,
-                    branchID: cached.branchID
-                };
-            }
-            // A fork-losing hit: `cached.contentKey` is our private clone that
-            // we are about to discard for a re-unwrap, so zero it rather than orphan it.
-            cached.contentKey.fill(0);
-            cache.evict(keyID);
-        }
-        const suite = getSuite(key.suite);
-        const wrappings = await store.listWrappingsWithBranch(keyID, key.version);
-        if (wrappings.length === 0) {
-            throw new CredentialUnopenable(keyID, `no wrapping at version ${key.version}`);
-        }
-        // Concurrent rotations leave two content-key branches under one version. The
-        // labels a keyless party could already partition by resolve, here, which one
-        // this device opens — so every device converges on the same branch instead
-        // of the first-listed wrapping, which is order-dependent and diverges. An
-        // empty label is branch-agnostic (legacy/non-rotation state), not a branch of
-        // its own, so it never counts toward a fork.
-        // A label no key-op vouches for cannot be allowed to win or to open.
-        const eligible = wrappings.filter((wrapping)=>wrapping.branch_id === '' || proven.has(wrapping.branch_id));
-        // No fork: try every wrapping in listed order, unchanged. Fork: only the
-        // winner-labelled wrappings, with empty-label ones as a last-resort fallback
-        // — a loser-labelled wrapping opens the wrong content key and is skipped.
-        const toTry = winner == null ? eligible : [
-            ...eligible.filter((wrapping)=>wrapping.branch_id === winner),
-            ...eligible.filter((wrapping)=>wrapping.branch_id === '')
-        ];
-        const reasons = [];
-        const promptable = new Set();
-        let rejected = null;
-        for (const wrapping of toTry){
-            const satisfiable = satisfiableFactors(wrapping.factors);
-            if (satisfiable == null) {
-                reasons.push(`wrapping ${wrapping.wrapping_id}: not addressed to this device`);
-                continue;
-            }
-            try {
-                const contentKey = await suite.unwrap({
-                    identity: decrypting,
-                    descriptors: wrapping.factors,
-                    inputs,
-                    iv: new Uint8Array(wrapping.iv),
-                    wrappedKey: new Uint8Array(wrapping.wrapped_key),
-                    wrappingID: wrapping.wrapping_id,
-                    keyID,
-                    keyVersion: wrapping.key_version
-                });
-                // In a fork every device names the same winner keylessly, so caching the
-                // winner as the resolved branch converges post-fork writes even when an
-                // empty-label fallback wrapping is what actually opened.
-                const branchID = winner ?? wrapping.branch_id;
-                // Suppress the re-warm if a lock landed while we were unwrapping: the
-                // caller still gets its key, but the cache stays cleared.
-                if (!lockedSince()) {
-                    cache.set(keyID, contentKey, key.version, branchID);
-                }
-                return {
-                    contentKey,
-                    version: key.version,
-                    branchID
-                };
-            } catch (error) {
-                reasons.push(error instanceof Error ? error.message : String(error));
-                if (error instanceof CredentialSecretRejected) {
-                    rejected = error;
-                }
-                for (const kind of satisfiable){
-                    promptable.add(kind);
-                }
-            }
-        }
-        // A secret WAS given and was wrong. Distinct from the case below, and it has
-        // to survive: a caller retries on one and prompts on the other, and the PIN
-        // throttle only counts an attempt that was actually made.
-        if (rejected != null) {
-            throw rejected;
-        }
-        // A wrapping this device is addressed by, that failed only for want of a
-        // secret nobody was asked for, is a prompt — not a dead end.
-        if (promptable.size > 0) {
-            throw new CredentialKeyLocked(keyID, [
-                ...promptable
-            ]);
-        }
-        throw new CredentialUnopenable(keyID, reasons.join('; '));
-    }
-    /**
-   * Open a key, collapsing concurrent input-free opens of the same key into one
-   * unwrap. A waiter shares only the fact that an open ran, then takes its own
-   * clone from the cache; on a miss — the leader hit a lock and skipped its set,
-   * or failed — it falls through to its own open. Input-bearing opens never join
-   * the herd (see `hasSuppliedInputs`).
-   */ async function openKey(keyID, inputs) {
-        // Captured once, at entry, so a lock landing while this call is queued behind
-        // another open still counts against it (see `doOpenKey`).
-        const genAtStart = keyGeneration.get(keyID) ?? 0;
-        const epochAtStart = lockAllEpoch;
-        if (hasSuppliedInputs(inputs)) {
-            return doOpenKey(keyID, inputs, genAtStart, epochAtStart);
-        }
-        // Join any open already in flight for this key; on a miss, re-contend for
-        // leadership rather than opening in parallel — so post-miss opens (a leader
-        // that failed or was lock-suppressed) serialize into one leader at a time
-        // instead of re-forming the herd.
-        while(true){
-            const pending = inFlight.get(keyID);
-            if (pending == null) {
-                break;
-            }
-            await pending;
-            const key = await loadKey(keyID);
-            const hit = cache.get(keyID, key.version);
-            if (hit != null) {
-                return {
-                    contentKey: hit.contentKey,
-                    version: key.version,
-                    branchID: hit.branchID
-                };
-            }
-        }
-        const run = doOpenKey(keyID, inputs, genAtStart, epochAtStart);
-        // A gate that never rejects, so a waiter's `await pending` cannot throw the
-        // leader's error into the wrong caller; the waiter re-derives its own result
-        // from the cache (or its own open) after the gate settles.
-        const gate = run.then(()=>undefined, ()=>undefined);
-        inFlight.set(keyID, gate);
-        try {
-            return await run;
-        } finally{
-            // Only clear our own entry — a later leader may already have replaced it.
-            if (inFlight.get(keyID) === gate) {
-                inFlight.delete(keyID);
-            }
-        }
-    }
-    return {
-        availableFactors () {
-            // A passphrase or pin needs no key material, only someone to ask. They are
-            // available on every device, including one that cannot decrypt at all.
-            return decrypting == null ? [
-                ...SECRET_FACTOR_KINDS
-            ] : [
-                'did',
-                ...SECRET_FACTOR_KINDS
-            ];
-        },
-        async unlock (keyID, inputs) {
-            if (inputs?.pin == null) {
-                // Unlock only warms the cache; the returned clone is ours to zero.
-                ;
-                (await openKey(keyID, inputs)).contentKey.fill(0);
-                return;
-            }
-            // Refused BEFORE `openKey`, so a throttled attempt never reaches Argon2.
-            // Below the KDF the 340ms is paid either way and the counter buys the
-            // defender nothing it does not also cost.
-            const wait = throttle.retryAfter(keyID);
-            if (wait > 0) {
-                throw new CredentialPinRejected(keyID, {
-                    attemptsRemaining: throttle.attemptsRemaining(keyID),
-                    retryAfter: wait
-                });
-            }
-            try {
-                ;
-                (await openKey(keyID, inputs)).contentKey.fill(0);
-            } catch (error) {
-                // Only a rejected secret advances the counter. A key that is simply not
-                // addressed to this device, or whose suite is unknown, is not someone
-                // guessing — counting it would lock a user out over a fault.
-                if (error instanceof CredentialSecretRejected) {
-                    throttle.recordFailure(keyID);
-                    throw new CredentialPinRejected(keyID, {
-                        cause: error,
-                        attemptsRemaining: throttle.attemptsRemaining(keyID),
-                        retryAfter: throttle.retryAfter(keyID)
-                    });
-                }
-                throw error;
-            }
-            throttle.recordSuccess(keyID);
-        },
-        async addFactor (keyID, factor, params) {
-            // Ownership, not possession of a wrapping. A rotation has to re-make every
-            // retained wrapping at the new version, and a secret factor cannot be
-            // re-made without its secret — so a recipient gating its own wrapping of
-            // someone else's key would make that key un-rotatable, and revocation is
-            // rotation.
-            //
-            // Asked for the verb rather than only for the secret kinds: a `did` added
-            // to a foreign wrapping re-makes unattended, but it is still a change to a
-            // key this identity does not administer, and the narrower rule buys the
-            // caller nothing it could use.
-            const key = await loadKey(keyID);
-            if (!await (params?.authority ?? authority).authorize('administer', {
-                key,
-                store
-            })) {
-                throw new CredentialNotAuthorized('administer', keyID);
-            }
-            await rewrapOwn(keyID, params?.inputs, (factors)=>[
-                    ...factors,
-                    factor
-                ], params?.methods);
-        },
-        async removeFactor (keyID, kind, params) {
-            // Dropping a factor (a pin, say) weakens the key exactly as adding one
-            // strengthens it, so it is administration too — see `addFactor`.
-            const key = await loadKey(keyID);
-            if (!await (params?.authority ?? authority).authorize('administer', {
-                key,
-                store
-            })) {
-                throw new CredentialNotAuthorized('administer', keyID);
-            }
-            await rewrapOwn(keyID, params?.inputs, (factors)=>{
-                const remaining = factors.filter((factor)=>factor.kind !== kind);
-                if (remaining.length === factors.length) {
-                    throw new CredentialNotFound(`Credential factor "${kind}" on this device's wrapping of`, keyID);
-                }
-                // Nothing here refuses a removal that would leave a pin without a did,
-                // or nothing at all: `suite.wrap` validates the list it is given, so
-                // the refusal happens once, where every path reaches it.
-                return remaining;
-            }, params?.methods);
-        },
-        lock (keyID) {
-            // Bump before evicting so an `openKey` already past its generation capture
-            // sees the change and skips its `cache.set`.
-            keyGeneration.set(keyID, (keyGeneration.get(keyID) ?? 0) + 1);
-            cache.evict(keyID);
-        },
-        lockAll () {
-            lockAllEpoch += 1;
-            cache.evictAll();
-        },
-        async status (keyID, version) {
-            const key = await store.getKey(keyID);
-            if (key == null) {
-                throw new CredentialNotFound('Credential key', keyID);
-            }
-            // Reported, not thrown. `loadKey` raises here, which would make the call
-            // that exists to say "this device cannot read that key" fail on exactly
-            // the key it was asked about.
-            if (!isSupportedSuite(key.suite)) {
-                return {
-                    state: 'unopenable',
-                    reason: 'unsupported-suite'
-                };
-            }
-            // Defaults to the key's current version; a caller checking a manifest
-            // target passes the expected version so a stale wrapping is never
-            // reported openable for a newer one, or vice versa.
-            const targetVersion = version ?? key.version;
-            if (cache.has(keyID, targetVersion)) {
-                return {
-                    state: 'unlocked'
-                };
-            }
-            const wrappings = await store.listWrappings(keyID, targetVersion);
-            if (wrappings.length === 0) {
-                return {
-                    state: 'unopenable',
-                    reason: 'no-wrapping'
-                };
-            }
-            const unlockOptions = [];
-            for (const wrapping of wrappings){
-                const satisfiable = satisfiableFactors(wrapping.factors);
-                if (satisfiable == null) {
-                    continue;
-                }
-                // Nothing to ask for: this one opens on the identity alone, so the key
-                // needs no interaction however many other wrappings do.
-                if (satisfiable.length === 0) {
-                    return {
-                        state: 'available'
-                    };
-                }
-                unlockOptions.push(satisfiable);
-            }
-            return unlockOptions.length > 0 ? {
-                state: 'locked',
-                unlockOptions
-            } : {
-                state: 'unopenable',
-                reason: 'not-addressed'
-            };
-        },
-        async createKey (createParams = {}) {
-            const suiteID = createParams.suite ?? SUITE_KUBUN_CRED_1;
-            if (createParams.factors != null && createParams.wrappings != null) {
-                throw new InvalidCredentialFactors('pass either "factors" or "wrappings", not both');
-            }
-            // The headless default: one wrapping to this device's wrappable form. Taking
-            // it without a decrypting identity would mint a key whose only wrapping
-            // this device can never open, so it refuses here rather than at first read.
-            const explicit = createParams.wrappings ?? (createParams.factors && [
-                createParams.factors
-            ]);
-            const wrappings = explicit ?? [
-                [
-                    {
-                        kind: 'did',
-                        recipientDID: wrappableDID(identity)
-                    }
-                ]
-            ];
-            if (explicit == null && decrypting == null) {
-                throw new NoAvailableFactor('did');
-            }
-            const built = await buildCredentialKey({
-                runtime,
-                ownerDID: createParams.ownerDID ?? identity.id,
-                suite: suiteID,
-                wrappings,
-                methods: createParams.methods
-            });
-            // The wrappings already encapsulate the content key; createKey never reads
-            // `built.contentKey` again, so zero it rather than leave the generated
-            // secret live until collection.
-            built.contentKey.fill(0);
-            const keyParams = {
-                keyID: built.keyID,
-                ownerDID: built.ownerDID,
-                suite: built.suite,
-                version: built.version,
-                state: 'active'
-            };
-            // The key-op opens the content-key branch every wrapping here joins, so
-            // its label is threaded onto them.
-            const keyOp = await ops.key(keyParams, await nextHLC());
-            await store.recordKeyBranch({
-                keyID: built.keyID,
-                keyVersion: built.version,
-                authorDID: keyOp.authorDID,
-                hlc: keyOp.hlc,
-                opJWT: keyOp.opJWT,
-                opHash: keyOp.opHash,
-                branchID: keyOp.branchID
-            });
-            await store.putKey(keyParams, keyOp);
-            for (const wrapping of built.wrappings){
-                await store.putWrapping(wrapping, await ops.wrapping(wrapping, await nextHLC(), keyOp.branchID));
-            }
-            return built.keyID;
-        },
-        async rotate (keyID, rotateParams) {
-            const key = await loadKey(keyID);
-            // Rotation is administration, not use: it retires a content key every
-            // other recipient holds and re-makes their wrappings under one this
-            // identity chose. Asked before the first read, because everything below
-            // opens the key and decrypts every entry before it writes anything — a
-            // gate after that has already done the work it exists to refuse.
-            if (!await (rotateParams?.authority ?? authority).authorize('administer', {
-                key,
-                store
-            })) {
-                throw new CredentialNotAuthorized('administer', keyID);
-            }
-            const previousSuite = getSuite(key.suite);
-            const suiteID = rotateParams?.suite ?? key.suite;
-            const suite = getSuite(suiteID);
-            const newVersion = key.version + 1;
-            // Everything is read, and every plaintext recovered, before the first
-            // write. A wrapping this device cannot re-make, or an entry it cannot
-            // read, has to fail while the store is still untouched — past the first
-            // write there is nothing here that could put it back.
-            const previousKey = (await openKey(keyID, rotateParams?.inputs)).contentKey;
-            // Both key buffers are our private clones. One try spans from here to the end so
-            // a throw anywhere in the rotation zeros them, not only the success path.
-            // `previousKey` is read only in the plaintext-recovery loop; the generated
-            // key through the last write. It is declared here so the `finally` can zero
-            // it whether or not generation was reached.
-            let generatedKey;
-            try {
-                const retained = (await store.listWrappings(keyID, key.version)).map((wrapping)=>({
-                        recipientDID: wrapping.recipient_did,
-                        factors: factorsFromDescriptors(wrapping.factors, rotateParams?.inputs)
-                    }));
-                const plaintexts = (await store.listEntries(keyID)).map((entry)=>{
-                    // An entry left behind by a rotation that did not finish. Carrying it
-                    // forward is impossible — its ciphertext is under a content key nothing
-                    // holds — and skipping it would quietly strand it one version further.
-                    if (entry.key_version !== key.version) {
-                        throw new CredentialKeyVersionMismatch(entry.entry_id, entry.key_version, key.version);
-                    }
-                    return {
-                        entryID: entry.entry_id,
-                        plaintext: previousSuite.decryptEntry({
-                            contentKey: previousKey,
-                            iv: new Uint8Array(entry.iv),
-                            ciphertext: new Uint8Array(entry.ciphertext),
-                            keyID,
-                            keyVersion: entry.key_version,
-                            entryID: entry.entry_id
-                        })
-                    };
-                });
-                const contentKey = suite.generateContentKey(runtime);
-                generatedKey = contentKey;
-                // Signed before the entries and wrappings it labels — its branch is what
-                // they join — but persisted last, so the version bump still lands after
-                // the rows a reader needs at it. Signing touches no store, so this only
-                // moves the key-op's stamp ahead of the batch, which is where the branch
-                // it introduces belongs.
-                const rotatedKey = {
-                    keyID,
-                    ownerDID: key.owner_did,
-                    suite: suiteID,
-                    version: newVersion,
-                    state: key.state === 'retired' ? 'retired' : 'active'
-                };
-                const rotatedKeyOp = await ops.key(rotatedKey, await nextHLC());
-                const branchID = rotatedKeyOp.branchID;
-                await store.recordKeyBranch({
-                    keyID,
-                    keyVersion: newVersion,
-                    authorDID: rotatedKeyOp.authorDID,
-                    hlc: rotatedKeyOp.hlc,
-                    opJWT: rotatedKeyOp.opJWT,
-                    opHash: rotatedKeyOp.opHash,
-                    branchID: rotatedKeyOp.branchID
-                });
-                for (const { entryID, plaintext } of plaintexts){
-                    const { iv, ciphertext } = suite.encryptEntry({
-                        runtime,
-                        contentKey,
-                        plaintext,
-                        keyID,
-                        keyVersion: newVersion,
-                        entryID
-                    });
-                    const entryParams = {
-                        entryID,
-                        keyID,
-                        keyVersion: newVersion,
-                        iv,
-                        ciphertext,
-                        hlc: await nextHLC()
-                    };
-                    await store.putEntry(entryParams, await ops.entry(entryParams, branchID));
-                }
-                for (const { recipientDID, factors } of retained){
-                    const wrappingID = runtime.getRandomID();
-                    const { descriptors, iv, wrappedKey } = await suite.wrap({
-                        runtime,
-                        contentKey,
-                        factors,
-                        wrappingID,
-                        keyID,
-                        keyVersion: newVersion,
-                        methods: rotateParams?.methods
-                    });
-                    const wrappingParams = {
-                        wrappingID,
-                        keyID,
-                        keyVersion: newVersion,
-                        factors: descriptors,
-                        iv,
-                        wrappedKey,
-                        recipientDID
-                    };
-                    await store.putWrapping(wrappingParams, await ops.wrapping(wrappingParams, await nextHLC(), branchID));
-                }
-                // The version and the suite have to land together — an entry encrypted
-                // under one and read under the other fails its tag — and the op speaks
-                // for the whole row either way, so both branches sign the same shape. The
-                // op was signed above so its label could tag the rows; it persists here.
-                if (suiteID === key.suite) {
-                    await store.setKeyVersion(keyID, newVersion, rotatedKeyOp);
-                } else {
-                    await store.putKey(rotatedKey, rotatedKeyOp);
-                }
-                // Listed before the sweep so every removed row gets a tombstone: the
-                // delete predicate spans versions, and a row it takes with no tombstone
-                // comes back the first time a peer that still holds it ships it over.
-                const superseded = (await store.listWrappings(keyID)).filter((wrapping)=>wrapping.key_version < newVersion);
-                const tombstones = [];
-                for (const wrapping of superseded){
-                    tombstones.push(await ops.wrappingTombstone({
-                        subjectKind: 'wrapping',
-                        subjectID: wrapping.wrapping_id,
-                        keyID,
-                        keyVersion: wrapping.key_version
-                    }, await nextHLC()));
-                }
-                await store.deleteWrappingsBelowVersion(keyID, newVersion, tombstones);
-                // The rotation's own key-op labels the branch it just made. `cache.set`
-                // stores its own clone, so zeroing the local generated key in the
-                // `finally` does not disturb the cached one.
-                cache.set(keyID, contentKey, newVersion, branchID);
-                return newVersion;
-            } finally{
-                previousKey.fill(0);
-                generatedKey?.fill(0);
-            }
+    const ctx = createManagerContext(params);
+    const { store } = ctx;
+    const internals = {
+        get records () {
+            return records;
         },
-        async grant (keyID, recipientWrappableDID, params) {
-            const key = await loadKey(keyID);
-            // Administration, and by a stronger argument than `rotate`'s: this hands
-            // the content key to a party that did not have it, which is the one change
-            // no later rotation can take back from whoever received it.
-            if (!await (params?.authority ?? authority).authorize('administer', {
-                key,
-                store
-            })) {
-                throw new CredentialNotAuthorized('administer', keyID);
-            }
-            // Answered before the key is opened, so a re-grant needs no prompt on a
-            // locked device: it writes nothing either way.
-            const wrappings = await store.listWrappings(keyID, key.version);
-            const addressed = wrappings.some((wrapping)=>wrapping.factors.some((descriptor)=>descriptor.kind === 'did' && typeof descriptor.params.recipient === 'string' && normalizeDID(descriptor.params.recipient) === normalizeDID(recipientWrappableDID)));
-            // A second wrapping to a recipient that already holds one is precisely the
-            // state {@link AmbiguousCredentialWrapping} refuses, and it would break
-            // that recipient's own `addFactor` rather than widening anything. So a
-            // repeat grant — a push whose frame never arrived, retried — adds nothing.
-            if (addressed) {
-                return {
-                    version: key.version,
-                    created: false
-                };
-            }
-            // Opened before the write, as everything here is: a granter that cannot
-            // reach the content key has to fail against an untouched store rather than
-            // leave a wrapping nobody can open.
-            const { contentKey, branchID } = await openKey(keyID);
-            const wrappingID = runtime.getRandomID();
-            const suite = getSuite(key.suite);
-            let wrapped;
-            try {
-                wrapped = await suite.wrap({
-                    runtime,
-                    contentKey,
-                    factors: [
-                        {
-                            kind: 'did',
-                            recipientDID: recipientWrappableDID
-                        }
-                    ],
-                    wrappingID,
-                    keyID,
-                    keyVersion: key.version,
-                    methods: params?.methods
-                });
-            } finally{
-                contentKey.fill(0);
-            }
-            const { descriptors, iv, wrappedKey } = wrapped;
-            const granted = {
-                wrappingID,
-                keyID,
-                keyVersion: key.version,
-                factors: descriptors,
-                iv,
-                wrappedKey,
-                // Un-normalized, unlike `owner_did`: this column is a key-resolution
-                // input, and folding a peer:4 long form would make it unwrappable.
-                recipientDID: recipientWrappableDID
-            };
-            await store.putWrapping(granted, await ops.wrapping(granted, await nextHLC(), branchID));
-            return {
-                version: key.version,
-                created: true
-            };
+        get open () {
+            return open;
         },
-        async listKeys () {
-            return (await store.listKeys(normalizeDID(identity.id))).map((key)=>key.key_id);
+        get rotate () {
+            return rotate;
         },
-        async countWrappings (keyID) {
-            const key = await store.getKey(keyID);
-            if (key == null) {
-                throw new CredentialNotFound('Credential key', keyID);
-            }
-            return (await store.listWrappings(keyID, key.version)).length;
+        get removalRecovery () {
+            return removalRecovery;
         },
-        async deleteKey (keyID) {
-            // Read first, for the tombstone's version. A key that is not here leaves
-            // no tombstone: this device has nothing to say about a row it never held,
-            // and it could not name the version if it wanted to.
-            const key = await store.getKey(keyID);
-            if (key == null) {
-                return;
-            }
-            await store.deleteKey(keyID, await ops.tombstone({
-                subjectKind: 'key',
-                subjectID: keyID,
-                keyID,
-                keyVersion: key.version
-            }, await nextHLC()));
+        get manager () {
+            return manager;
         },
-        async putEntry (keyID, plaintext) {
-            const { contentKey, version, branchID } = await openKey(keyID);
-            let entry;
-            try {
-                const key = await store.getKey(keyID);
-                entry = buildCredentialEntry({
-                    runtime,
-                    key: {
-                        keyID,
-                        // The key's owner, not this device: an entry under a viewer's key
-                        // belongs to that viewer even when a server wrote it.
-                        ownerDID: key?.owner_did ?? identity.id,
-                        suite: key?.suite ?? SUITE_KUBUN_CRED_1,
-                        version,
-                        contentKey
-                    },
-                    plaintext
-                });
-            } finally{
-                contentKey.fill(0);
-            }
-            const entryParams = {
-                ...entry,
-                hlc: await nextHLC()
-            };
-            await store.putEntry(entryParams, await ops.entry(entryParams, branchID));
-            return entry.entryID;
-        },
-        async updateEntry (entryID, plaintext) {
-            const existing = await store.getEntry(entryID);
-            if (existing == null) {
-                throw new CredentialNotFound('Credential entry', entryID);
-            }
-            const { contentKey, version, branchID } = await openKey(existing.key_id);
-            // Re-encrypted under the key's CURRENT version, not the version the entry
-            // was written at: an update is a fresh write, and leaving it behind would
-            // keep a rotated-away version alive indefinitely. The suite lookup's store
-            // read is inside the `try` so a rejection cannot leak the key copy.
-            let encrypted;
-            try {
-                const suite = getSuite((await store.getKey(existing.key_id))?.suite ?? SUITE_KUBUN_CRED_1);
-                encrypted = suite.encryptEntry({
-                    runtime,
-                    contentKey,
-                    plaintext,
-                    keyID: existing.key_id,
-                    keyVersion: version,
-                    entryID
-                });
-            } finally{
-                contentKey.fill(0);
-            }
-            const { iv, ciphertext } = encrypted;
-            const updated = {
-                entryID,
-                keyID: existing.key_id,
-                keyVersion: version,
-                iv,
-                ciphertext,
-                hlc: await nextHLC()
-            };
-            await store.putEntry(updated, await ops.entry(updated, branchID));
-        },
-        async updateEntryIfPresent (entryID, plaintext) {
-            const existing = await store.getEntry(entryID);
-            if (existing == null) {
-                return 'absent';
-            }
-            const { contentKey, version, branchID } = await openKey(existing.key_id);
-            // Same re-encrypt-under-current-version shape as `updateEntry`: the suite
-            // lookup's store read stays inside the `try` so a rejection cannot leak the
-            // key copy.
-            let encrypted;
-            try {
-                const suite = getSuite((await store.getKey(existing.key_id))?.suite ?? SUITE_KUBUN_CRED_1);
-                encrypted = suite.encryptEntry({
-                    runtime,
-                    contentKey,
-                    plaintext,
-                    keyID: existing.key_id,
-                    keyVersion: version,
-                    entryID
-                });
-            } finally{
-                contentKey.fill(0);
-            }
-            const { iv, ciphertext } = encrypted;
-            const updated = {
-                entryID,
-                keyID: existing.key_id,
-                keyVersion: version,
-                iv,
-                ciphertext,
-                // A fresh stamp every time, not `existing.hlc` carried forward: the store
-                // primitive is op-first and gates the row write on this op winning LWW, so
-                // the writeback needs a current stamp to land at all.
-                hlc: await nextHLC()
-            };
-            return await store.updateEntryIfPresent(updated, await ops.entry(updated, branchID));
-        },
-        async readEntry (entryID) {
-            const entry = await store.getEntry(entryID);
-            if (entry == null) {
-                throw new CredentialNotFound('Credential entry', entryID);
-            }
-            const key = await store.getKey(entry.key_id);
-            if (key == null) {
-                throw new CredentialNotFound('Credential key', entry.key_id);
-            }
-            // A rotation re-encrypts every entry, so a lagging one means it crashed
-            // partway. Reading it under the older version would quietly return a value
-            // the rotation was retiring, so this refuses instead.
-            if (entry.key_version !== key.version) {
-                throw new CredentialKeyVersionMismatch(entryID, entry.key_version, key.version);
-            }
-            const { contentKey, branchID } = await openKey(entry.key_id);
-            // Zero our private clone on every exit — the branch-mismatch throw
-            // and the decrypt alike.
-            try {
-                const entryBranchID = (await store.getOp('entry', entryID))?.branch_id ?? '';
-                if (entryBranchID !== '' && branchID !== '' && entryBranchID !== branchID) {
-                    throw new CredentialSupersededBranch(entryID, entryBranchID, branchID);
-                }
-                return getSuite(key.suite).decryptEntry({
-                    contentKey,
-                    iv: new Uint8Array(entry.iv),
-                    ciphertext: new Uint8Array(entry.ciphertext),
-                    keyID: entry.key_id,
-                    keyVersion: entry.key_version,
-                    entryID
-                });
-            } finally{
-                contentKey.fill(0);
-            }
-        },
-        async getEntryProvenance (entryID) {
-            const entry = await store.getEntryWithProvenance(entryID);
-            if (entry == null) {
-                return {
-                    updatedAt: null,
-                    writerDID: null
-                };
-            }
-            return entryProvenanceFields(entry);
-        },
-        async getEntryKeyOwnerDID (entryID) {
-            const entry = await store.getEntry(entryID);
-            if (entry == null) {
-                return null;
-            }
-            const key = await store.getKey(entry.key_id);
-            return key == null ? null : key.owner_did;
-        },
-        async listEntries (keyID) {
-            return (await store.listEntries(keyID)).map((entry)=>entry.entry_id);
-        },
-        async deleteEntry (entryID) {
-            // Read first, as `deleteKey` does: the tombstone has to name the key the
-            // entry sat under, and the entry row is the only thing that knows it.
-            const entry = await store.getEntry(entryID);
-            if (entry == null) {
-                return;
-            }
-            await store.deleteEntry(entryID, await ops.tombstone({
-                subjectKind: 'entry',
-                subjectID: entryID,
-                keyID: entry.key_id,
-                keyVersion: entry.key_version
-            }, await nextHLC()));
-        },
-        async reKeyEntry (entryID, toKeyID, params) {
-            const entry = await store.getEntry(entryID);
-            if (entry == null) {
-                throw new CredentialNotFound('Credential entry', entryID);
-            }
-            const fromKey = await loadKey(entry.key_id);
-            // Both keys resolved before either gate, so an absent target reports as
-            // missing rather than as something this identity may not administer.
-            const toKey = await loadKey(toKeyID);
-            for (const key of [
-                fromKey,
-                toKey
-            ]){
-                if (!await (params?.authority ?? authority).authorize('administer', {
-                    key,
-                    store
-                })) {
-                    throw new CredentialNotAuthorized('administer', key.key_id);
-                }
-            }
-            // The refusal `readEntry` makes, for the same reason: the content key this
-            // entry was written under is gone with the rotation that did not finish,
-            // so it cannot be carried anywhere, and decrypting it under the current
-            // one would fail at the tag and read as tampering.
-            if (entry.key_version !== fromKey.version) {
-                throw new CredentialKeyVersionMismatch(entryID, entry.key_version, fromKey.version);
-            }
-            // Both keys opened, and the plaintext recovered, before the single write.
-            // A target this device cannot open has to fail while the entry is still
-            // where it was.
-            const { contentKey: fromContentKey } = await openKey(entry.key_id);
-            let plaintext;
-            try {
-                plaintext = getSuite(fromKey.suite).decryptEntry({
-                    contentKey: fromContentKey,
-                    iv: new Uint8Array(entry.iv),
-                    ciphertext: new Uint8Array(entry.ciphertext),
-                    keyID: entry.key_id,
-                    keyVersion: entry.key_version,
-                    entryID
-                });
-            } finally{
-                fromContentKey.fill(0);
-            }
-            const { contentKey: toContentKey, version, branchID } = await openKey(toKeyID);
-            // The target's CURRENT version, as an update is: landing on an older one
-            // would strand the entry the moment the key rotates.
-            let reEncrypted;
-            try {
-                reEncrypted = getSuite(toKey.suite).encryptEntry({
-                    runtime,
-                    contentKey: toContentKey,
-                    plaintext,
-                    keyID: toKeyID,
-                    keyVersion: version,
-                    entryID
-                });
-            } finally{
-                toContentKey.fill(0);
-            }
-            const { iv, ciphertext } = reEncrypted;
-            const moved = {
-                entryID,
-                keyID: toKeyID,
-                keyVersion: version,
-                iv,
-                ciphertext,
-                hlc: await nextHLC()
-            };
-            await store.moveEntry(moved, await ops.entry(moved, branchID));
-        }
+        createManager: createCredentialManager
+    };
+    const records = createRecordFunctions(ctx);
+    const open = createOpenFunctions(ctx, internals);
+    const rotate = createRotateFunctions(ctx, internals);
+    const removalRecovery = createRemovalRecoveryFunctions(ctx, internals);
+    const keyMethods = createKeyMethods(ctx, internals);
+    const entryFunctions = createEntryFunctions(ctx, internals);
+    const manager = {
+        get store () {
+            return store;
+        },
+        recoverRemovedDevices: removalRecovery.recoverRemovedDevices,
+        ensureRemovalRecovery: removalRecovery.checkRemovalRecovery,
+        repairFork: rotate.repairFork,
+        ...keyMethods,
+        ...entryFunctions
     };
+    return manager;
 }