@kubun/credential 0.13.0

package/lib/manager.js

@@ -0,0 +1,881 @@
+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';
+/** 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);
+}
+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
+    });
+    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 factors = change(factorsFromDescriptors(existing.factors, inputs));
+        const suite = getSuite(key.suite);
+        const wrappingID = runtime.getRandomID();
+        const { descriptors, iv, wrappedKey } = await suite.wrap({
+            runtime,
+            contentKey,
+            factors,
+            wrappingID,
+            keyID,
+            keyVersion: key.version,
+            methods
+        });
+        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.
+   */ async function openKey(keyID, inputs) {
+        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
+                };
+            }
+            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;
+                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('; '));
+    }
+    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) {
+                await openKey(keyID, inputs);
+                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);
+            } 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) {
+            cache.evict(keyID);
+        },
+        lockAll () {
+            cache.evictAll();
+        },
+        async status (keyID) {
+            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'
+                };
+            }
+            if (cache.get(keyID, key.version) != null) {
+                return {
+                    state: 'unlocked'
+                };
+            }
+            const wrappings = await store.listWrappings(keyID, key.version);
+            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 own identity. 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: identity.id
+                    }
+                ]
+            ];
+            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
+            });
+            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;
+            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);
+            // 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);
+            // Zeroes `previousKey` on the way in, which is why nothing above may read
+            // it afterwards. The rotation's own key-op labels the branch it just made.
+            cache.set(keyID, contentKey, newVersion, branchID);
+            return newVersion;
+        },
+        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 { descriptors, iv, wrappedKey } = await getSuite(key.suite).wrap({
+                runtime,
+                contentKey,
+                factors: [
+                    {
+                        kind: 'did',
+                        recipientDID: recipientWrappableDID
+                    }
+                ],
+                wrappingID,
+                keyID,
+                keyVersion: key.version,
+                methods: params?.methods
+            });
+            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
+            };
+        },
+        async listKeys () {
+            return (await store.listKeys(normalizeDID(identity.id))).map((key)=>key.key_id);
+        },
+        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;
+        },
+        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()));
+        },
+        async putEntry (keyID, plaintext) {
+            const { contentKey, version, branchID } = await openKey(keyID);
+            const key = await store.getKey(keyID);
+            const 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
+            });
+            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);
+            const suite = getSuite((await store.getKey(existing.key_id))?.suite ?? SUITE_KUBUN_CRED_1);
+            // 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.
+            const { iv, ciphertext } = suite.encryptEntry({
+                runtime,
+                contentKey,
+                plaintext,
+                keyID: existing.key_id,
+                keyVersion: version,
+                entryID
+            });
+            const updated = {
+                entryID,
+                keyID: existing.key_id,
+                keyVersion: version,
+                iv,
+                ciphertext,
+                hlc: await nextHLC()
+            };
+            await store.putEntry(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);
+            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
+            });
+        },
+        async getEntryProvenance (entryID) {
+            const entry = await store.getEntryWithProvenance(entryID);
+            if (entry == null) {
+                return {
+                    updatedAt: null,
+                    writerDID: null
+                };
+            }
+            return entryProvenanceFields(entry);
+        },
+        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);
+            const 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
+            });
+            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.
+            const { iv, ciphertext } = getSuite(toKey.suite).encryptEntry({
+                runtime,
+                contentKey: toContentKey,
+                plaintext,
+                keyID: toKeyID,
+                keyVersion: version,
+                entryID
+            });
+            const moved = {
+                entryID,
+                keyID: toKeyID,
+                keyVersion: version,
+                iv,
+                ciphertext,
+                hlc: await nextHLC()
+            };
+            await store.moveEntry(moved, await ops.entry(moved, branchID));
+        }
+    };
+}