@kubun/credential 0.17.4 → 0.18.0

package/lib/manager-context.js

@@ -0,0 +1,82 @@
+import { isKeyAgreementIdentity, normalizeDID } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import { createDeviceAuthority } from './authority.js';
+import { createKeyCache } from './key-cache.js';
+import { createPinThrottle } from './pin-throttle.js';
+/** Kinds a user can be prompted for, as opposed to ones held as key material. */ export const SECRET_FACTOR_KINDS = [
+    'passphrase',
+    'pin'
+];
+export function wrappingNamesRemovedDevice(wrapping, removed) {
+    return [
+        wrapping.recipient_did,
+        ...wrapping.factors.filter((factor)=>factor.kind === 'did').map((factor)=>factor.params.recipient)
+    ].some((recipient)=>typeof recipient === 'string' && removed.has(normalizeDID(recipient)));
+}
+export function isSecretFactorKind(kind) {
+    return SECRET_FACTOR_KINDS.includes(kind);
+}
+export function createManagerContext(params) {
+    const { store, identity, runtime, hlc } = params;
+    const authority = params.authority ?? createDeviceAuthority(identity.id);
+    const decrypting = isKeyAgreementIdentity(identity) ? identity : null;
+    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 state = {
+        inFlight: new Map(),
+        keyGeneration: new Map(),
+        lockAllEpoch: 0
+    };
+    /**
+   * 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() {
+        state.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 state.floorPromise;
+    }
+    async function nextHLC() {
+        await ensureFloored();
+        return HLC.serialize(hlc.now());
+    }
+    return {
+        params,
+        store,
+        identity,
+        runtime,
+        hlc,
+        authority,
+        decrypting,
+        cache,
+        throttle,
+        state,
+        ensureFloored,
+        nextHLC
+    };
+}

package/lib/manager-entries.d.ts

@@ -0,0 +1,3 @@
+import type { ManagerContext, ManagerInternals } from './manager-context.js';
+import type { CredentialManager } from './manager-types.js';
+export declare function createEntryFunctions(ctx: ManagerContext, internals: ManagerInternals): Pick<CredentialManager, 'putEntry' | 'updateEntry' | 'updateEntryIfPresent' | 'updateEntryIfUnchanged' | 'readEntry' | 'getEntryProvenance' | 'getEntryKeyOwnerDID' | 'listEntries' | 'reencryptGrantEntries' | 'deleteEntry' | 'reKeyEntry'>;

package/lib/manager-entries.js

@@ -0,0 +1,585 @@
+import { normalizeDID } from '@kokuin/token';
+import { verifySignedRecord } from '@kubun/records';
+import { buildCredentialEntry } from './builder.js';
+import { CredentialEntryConflict, CredentialEntryOwnerMismatch, CredentialInvalidEntry, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialRepairPending, CredentialSupersededBranch, CredentialUnopenable, UnsupportedCredentialSuite } from './errors.js';
+import { entryProvenanceFields } from './provenance.js';
+import { credentialGrantEntryID } from './record-types.js';
+import { getSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
+export function createEntryFunctions(ctx, internals) {
+    const { store, identity, runtime, authority, nextHLC } = ctx;
+    const { entryRecord, winningBranch, putRecord, branchRecordID, putEntryRecord, entryGrant, writableGrant, branchProofs, suiteForVersion } = internals.records;
+    const { loadKey, openKey, openSpecificBranch } = internals.open;
+    const { checkRemovalRecovery } = internals.removalRecovery;
+    const requireEntryAddress = (address)=>{
+        if (typeof address?.entryID !== 'string' || typeof address.ownerDID !== 'string' || !address.ownerDID) {
+            throw new CredentialInvalidEntry('credential entry address requires an ownerDID and entryID');
+        }
+        return address;
+    };
+    // The shared body of updateEntryIfPresent and updateEntryIfUnchanged; a null
+    // `expectedHLC` is the unconditional presence-gated write.
+    async function updateEntryConditionally({ entryID, plaintext, expectedHLC, attempt = 1, ownerDID }) {
+        const existing = await store.getEntry(entryID, ownerDID);
+        if (existing == null) {
+            return 'absent';
+        }
+        // Already rewritten since the caller read it: skip the key open and the
+        // re-encrypt. The store repeats the check atomically with the write.
+        if (expectedHLC != null && existing.hlc !== expectedHLC) {
+            return 'superseded';
+        }
+        const grant = await writableGrant(entryID, existing.owner_did);
+        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()
+        };
+        const outcome = await store.transaction(async (tx)=>{
+            await tx.lockKeyRow(updated.keyID);
+            const current = await tx.getEntry(entryID, existing.owner_did);
+            if (current == null) return 'absent';
+            if (expectedHLC != null && current.hlc !== expectedHLC) return 'superseded';
+            const key = await tx.getKey(updated.keyID);
+            if (key == null) throw new CredentialNotFound('Credential key', updated.keyID);
+            if (key.version !== version || current.key_id !== updated.keyID) return 'retry';
+            await putEntryRecord({
+                entry: updated,
+                owner: key.owner_did,
+                branchID,
+                contentHLC: updated.hlc,
+                target: tx,
+                authority,
+                grant
+            });
+            return 'updated';
+        });
+        if (outcome !== 'retry') return outcome;
+        if (attempt === 5) throw new CredentialEntryConflict(entryID);
+        return await updateEntryConditionally({
+            entryID,
+            plaintext,
+            expectedHLC,
+            attempt: attempt + 1,
+            ownerDID
+        });
+    }
+    async function reencryptGrantEntries(keyID) {
+        await checkRemovalRecovery();
+        for (const listed of (await store.listEntries(keyID))){
+            for(let attempt = 0; attempt < 5; attempt += 1){
+                const key = await loadKey(keyID);
+                const entry = await store.getEntry(listed.entry_id, key.owner_did);
+                if (entry == null || entry.key_id !== keyID || entry.key_version >= key.version) break;
+                const grant = await entryGrant(entry.entry_id, store, entry.owner_did);
+                if (grant === undefined || normalizeDID(grant.grantDeviceDID) !== normalizeDID(identity.id)) {
+                    break;
+                }
+                const previousRecord = await entryRecord(entry.entry_id, store, entry.owner_did);
+                const previousOp = previousRecord === null ? null : await verifySignedRecord(previousRecord);
+                const contentHLC = previousOp?.claim.meta.contentHLC;
+                if (typeof contentHLC !== 'string') break;
+                const old = await openKey(keyID, undefined, entry.key_version);
+                let plaintext;
+                try {
+                    plaintext = getSuite(await suiteForVersion(keyID, entry.key_version, key.suite)).decryptEntry({
+                        contentKey: old.contentKey,
+                        iv: new Uint8Array(entry.iv),
+                        ciphertext: new Uint8Array(entry.ciphertext),
+                        keyID,
+                        keyVersion: entry.key_version,
+                        entryID: entry.entry_id
+                    });
+                } finally{
+                    old.contentKey.fill(0);
+                }
+                let retry;
+                try {
+                    const expectedKey = await store.getKey(keyID);
+                    const current = await openKey(keyID);
+                    try {
+                        const stamp = await nextHLC();
+                        retry = await store.transaction(async (tx)=>{
+                            await tx.lockKeyRows([
+                                keyID
+                            ]);
+                            const latestKey = await tx.getKey(keyID);
+                            const latestEntry = await tx.getEntry(entry.entry_id, entry.owner_did);
+                            if (latestKey == null || expectedKey == null || latestKey.version !== expectedKey.version || latestKey.suite !== expectedKey.suite || latestKey.version !== current.version || latestEntry?.hlc !== entry.hlc || latestEntry.key_version !== entry.key_version) {
+                                return true;
+                            }
+                            const encrypted = getSuite(latestKey.suite).encryptEntry({
+                                runtime,
+                                contentKey: current.contentKey,
+                                plaintext,
+                                keyID,
+                                keyVersion: latestKey.version,
+                                entryID: entry.entry_id
+                            });
+                            await putEntryRecord({
+                                entry: {
+                                    entryID: entry.entry_id,
+                                    keyID,
+                                    keyVersion: latestKey.version,
+                                    ...encrypted,
+                                    hlc: stamp
+                                },
+                                owner: latestKey.owner_did,
+                                branchID: current.branchID,
+                                contentHLC,
+                                target: tx,
+                                authority,
+                                grant
+                            });
+                            return false;
+                        });
+                    } finally{
+                        current.contentKey.fill(0);
+                    }
+                } finally{
+                    plaintext.fill(0);
+                }
+                if (!retry) break;
+            }
+        }
+    }
+    return {
+        async putEntry (keyID, plaintext, grant) {
+            await checkRemovalRecovery();
+            if (grant !== undefined && grant.grantName === '') {
+                throw new CredentialInvalidEntry('Grant name is empty');
+            }
+            if (grant !== undefined && normalizeDID(grant.grantDeviceDID) !== normalizeDID(identity.id)) {
+                throw new CredentialNotAuthorized('administer', keyID);
+            }
+            for(;;){
+                const { contentKey, version, branchID } = await openKey(keyID);
+                let entry;
+                let candidateSuite;
+                try {
+                    const key = await loadKey(keyID);
+                    candidateSuite = key.suite;
+                    if (grant === undefined) {
+                        entry = buildCredentialEntry({
+                            runtime,
+                            key: {
+                                keyID,
+                                ownerDID: key.owner_did,
+                                suite: key.suite,
+                                version,
+                                contentKey
+                            },
+                            plaintext
+                        });
+                    } else {
+                        const entryID = credentialGrantEntryID(grant.grantOwnerDID ?? key.owner_did, grant.grantDeviceDID, grant.grantName);
+                        const encrypted = getSuite(key.suite).encryptEntry({
+                            runtime,
+                            contentKey,
+                            plaintext,
+                            keyID,
+                            keyVersion: version,
+                            entryID
+                        });
+                        entry = {
+                            entryID,
+                            keyID,
+                            keyVersion: version,
+                            ...encrypted
+                        };
+                    }
+                } finally{
+                    contentKey.fill(0);
+                }
+                const entryParams = {
+                    ...entry,
+                    hlc: await nextHLC()
+                };
+                const written = await store.transaction(async (tx)=>{
+                    await tx.lockKeyRow(keyID);
+                    const key = await tx.getKey(keyID);
+                    if (key == null) throw new CredentialNotFound('Credential key', keyID);
+                    if (key.version !== version || key.suite !== candidateSuite) return false;
+                    await putEntryRecord({
+                        entry: entryParams,
+                        owner: key.owner_did,
+                        branchID,
+                        contentHLC: entryParams.hlc,
+                        target: tx,
+                        authority,
+                        grant
+                    });
+                    return true;
+                });
+                if (written) return entry.entryID;
+            }
+        },
+        async updateEntry (address, plaintext) {
+            const { entryID, ownerDID } = requireEntryAddress(address);
+            await checkRemovalRecovery();
+            for(;;){
+                const existing = await store.getEntry(entryID, ownerDID);
+                if (existing == null) throw new CredentialNotFound('Credential entry', entryID);
+                const grant = await writableGrant(entryID, existing.owner_did);
+                const { contentKey, version, branchID } = await openKey(existing.key_id);
+                let encrypted;
+                let candidateSuite;
+                try {
+                    candidateSuite = (await loadKey(existing.key_id)).suite;
+                    encrypted = getSuite(candidateSuite).encryptEntry({
+                        runtime,
+                        contentKey,
+                        plaintext,
+                        keyID: existing.key_id,
+                        keyVersion: version,
+                        entryID
+                    });
+                } finally{
+                    contentKey.fill(0);
+                }
+                const updated = {
+                    entryID,
+                    keyID: existing.key_id,
+                    keyVersion: version,
+                    ...encrypted,
+                    hlc: await nextHLC()
+                };
+                const written = await store.transaction(async (tx)=>{
+                    await tx.lockKeyRow(existing.key_id);
+                    const key = await tx.getKey(existing.key_id);
+                    if (key == null) throw new CredentialNotFound('Credential key', existing.key_id);
+                    if (key.version !== version || key.suite !== candidateSuite) return false;
+                    const current = await tx.getEntry(entryID, existing.owner_did);
+                    if (current == null) throw new CredentialNotFound('Credential entry', entryID);
+                    if (current.key_id !== existing.key_id) return false;
+                    await putEntryRecord({
+                        entry: updated,
+                        owner: key.owner_did,
+                        branchID,
+                        contentHLC: updated.hlc,
+                        target: tx,
+                        authority,
+                        grant
+                    });
+                    return true;
+                });
+                if (written) return;
+            }
+        },
+        async updateEntryIfPresent (address, plaintext) {
+            const { entryID, ownerDID } = requireEntryAddress(address);
+            await checkRemovalRecovery();
+            // Unconditional, so never superseded.
+            return await updateEntryConditionally({
+                entryID,
+                plaintext,
+                expectedHLC: null,
+                attempt: 1,
+                ownerDID
+            });
+        },
+        async updateEntryIfUnchanged (input) {
+            const { entryID, ownerDID } = requireEntryAddress(input);
+            const { plaintext, expectedHLC } = input;
+            await checkRemovalRecovery();
+            return await updateEntryConditionally({
+                entryID,
+                plaintext,
+                expectedHLC,
+                attempt: 1,
+                ownerDID
+            });
+        },
+        async readEntry (address) {
+            const { entryID, ownerDID } = requireEntryAddress(address);
+            const entry = await store.getEntry(entryID, ownerDID);
+            if (entry == null) {
+                throw new CredentialNotFound('Credential entry', entryID);
+            }
+            if (entryID.startsWith('grant:')) {
+                try {
+                    await reencryptGrantEntries(entry.key_id);
+                } catch (error) {
+                    if (!(error instanceof UnsupportedCredentialSuite) && !(error instanceof CredentialUnopenable) && !(error instanceof CredentialKeyLocked)) {
+                        throw error;
+                    }
+                }
+            }
+            const currentEntry = await store.getEntry(entryID, entry.owner_did);
+            if (currentEntry == null) throw new CredentialNotFound('Credential entry', entryID);
+            const key = await store.getKey(currentEntry.key_id);
+            if (key == null) {
+                throw new CredentialNotFound('Credential key', entry.key_id);
+            }
+            if (currentEntry.key_version > key.version) {
+                throw new CredentialKeyVersionMismatch(entryID, currentEntry.key_version, key.version);
+            }
+            const { contentKey, branchID } = await openKey(currentEntry.key_id, undefined, currentEntry.key_version);
+            // Zero our private clone on every exit — the branch-mismatch throw
+            // and the decrypt alike.
+            try {
+                // The row's own label: a replicated entry record has no op row to read it from.
+                const entryBranchID = currentEntry.branch_id;
+                if (entryBranchID !== '' && branchID !== '' && entryBranchID !== branchID) {
+                    const proofs = await branchProofs(currentEntry.key_id, currentEntry.key_version);
+                    const entryProof = proofs.get(entryBranchID);
+                    const winnerProof = proofs.get(branchID);
+                    if (entryProof?.repairDigest === undefined || entryProof.repairDigest !== winnerProof?.repairDigest) {
+                        throw new CredentialSupersededBranch(entryID, entryBranchID, branchID);
+                    }
+                    const ownBranchKey = await openSpecificBranch({
+                        keyID: currentEntry.key_id,
+                        version: currentEntry.key_version,
+                        branchID: entryBranchID,
+                        suiteID: entryProof.suite
+                    });
+                    if (ownBranchKey === null) throw new CredentialRepairPending(currentEntry.key_id);
+                    try {
+                        return getSuite(entryProof.suite).decryptEntry({
+                            contentKey: ownBranchKey,
+                            iv: new Uint8Array(currentEntry.iv),
+                            ciphertext: new Uint8Array(currentEntry.ciphertext),
+                            keyID: currentEntry.key_id,
+                            keyVersion: currentEntry.key_version,
+                            entryID
+                        });
+                    } finally{
+                        ownBranchKey.fill(0);
+                    }
+                }
+                return getSuite(await suiteForVersion(currentEntry.key_id, currentEntry.key_version, key.suite)).decryptEntry({
+                    contentKey,
+                    iv: new Uint8Array(currentEntry.iv),
+                    ciphertext: new Uint8Array(currentEntry.ciphertext),
+                    keyID: currentEntry.key_id,
+                    keyVersion: currentEntry.key_version,
+                    entryID
+                });
+            } finally{
+                contentKey.fill(0);
+            }
+        },
+        async getEntryProvenance (address) {
+            const { entryID, ownerDID } = requireEntryAddress(address);
+            const entry = await store.getEntryWithProvenance(entryID, ownerDID);
+            if (entry == null) {
+                return {
+                    updatedAt: null,
+                    writerDID: null
+                };
+            }
+            const record = await entryRecord(entryID, store, entry.owner_did);
+            const op = record === null ? null : await verifySignedRecord(record);
+            return entryProvenanceFields({
+                hlc: entry.hlc,
+                author_did: op?.issuer ?? entry.author_did
+            });
+        },
+        async getEntryKeyOwnerDID (address) {
+            const { entryID, ownerDID } = requireEntryAddress(address);
+            const entry = await store.getEntry(entryID, ownerDID);
+            if (entry == null) {
+                return null;
+            }
+            const key = await store.getKey(entry.key_id, entry.owner_did);
+            return key == null ? null : key.owner_did;
+        },
+        async listEntries (keyID) {
+            await reencryptGrantEntries(keyID);
+            return (await store.listEntries(keyID)).map((entry)=>entry.entry_id);
+        },
+        reencryptGrantEntries,
+        async deleteEntry (address) {
+            const { entryID, ownerDID } = requireEntryAddress(address);
+            await checkRemovalRecovery();
+            for(;;){
+                const entry = await store.getEntry(entryID, ownerDID);
+                if (entry == null) return;
+                const key = await loadKey(entry.key_id);
+                if (!Number.isSafeInteger(entry.key_version) || entry.key_version < 0) {
+                    throw new CredentialKeyVersionMismatch(entryID, entry.key_version, key.version);
+                }
+                const grant = await entryGrant(entryID, store, entry.owner_did);
+                const deletionHLC = await nextHLC();
+                const result = await store.transaction(async (tx)=>{
+                    await tx.lockKeyRows([
+                        entry.key_id
+                    ]);
+                    const currentKey = await tx.getKey(entry.key_id);
+                    if (currentKey == null) throw new CredentialNotFound('Credential key', entry.key_id);
+                    const currentEntry = await tx.getEntry(entryID, entry.owner_did);
+                    if (currentEntry == null) return 'done';
+                    if (currentKey.version !== key.version || currentEntry.key_id !== entry.key_id || currentEntry.hlc !== entry.hlc) {
+                        return 'retry';
+                    }
+                    const currentBranches = await tx.listKeyBranches(entry.key_id, key.version);
+                    const deletionBranchID = currentEntry.key_version === key.version && currentEntry.branch_id !== '' ? currentEntry.branch_id : currentBranches.length > 0 ? await winningBranch(currentBranches) ?? '' : '';
+                    await putRecord({
+                        type: 'credential.entry',
+                        id: entryID,
+                        owner: currentKey.owner_did,
+                        hlc: deletionHLC,
+                        payload: null,
+                        meta: {
+                            keyID: entry.key_id,
+                            keyVersion: key.version,
+                            contentHLC: deletionHLC,
+                            ...deletionBranchID === '' ? {} : {
+                                branchID: deletionBranchID,
+                                branchRecordID: await branchRecordID({
+                                    keyID: entry.key_id,
+                                    version: key.version,
+                                    branchID: deletionBranchID,
+                                    target: tx
+                                })
+                            },
+                            ...grant === undefined ? {} : {
+                                grantDeviceDID: normalizeDID(grant.grantDeviceDID),
+                                grantName: grant.grantName,
+                                grantOwnerDID: normalizeDID(grant.grantOwnerDID ?? currentKey.owner_did)
+                            }
+                        },
+                        target: tx
+                    });
+                    return 'done';
+                });
+                if (result === 'done') return;
+            }
+        },
+        async reKeyEntry (input) {
+            const { entryID, ownerDID } = requireEntryAddress(input);
+            const { toKeyID } = input;
+            const params = input;
+            await checkRemovalRecovery();
+            const entry = await store.getEntry(entryID, ownerDID);
+            if (entry == null) {
+                throw new CredentialNotFound('Credential entry', entryID);
+            }
+            const grant = await writableGrant(entryID, entry.owner_did);
+            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);
+                }
+            }
+            if (normalizeDID(fromKey.owner_did) !== normalizeDID(toKey.owner_did)) {
+                throw new CredentialEntryOwnerMismatch(entryID, fromKey.owner_did, toKey.owner_did);
+            }
+            // 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, undefined, entry.key_version);
+            let plaintext;
+            try {
+                plaintext = getSuite(await suiteForVersion(entry.key_id, entry.key_version, 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);
+            }
+            let movedNow;
+            try {
+                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()
+                };
+                movedNow = await store.transaction(async (tx)=>{
+                    // A move touches both key scopes; the store orders advisory IDs.
+                    await tx.lockKeyRows([
+                        entry.key_id,
+                        toKeyID
+                    ]);
+                    const currentFrom = await tx.getKey(entry.key_id);
+                    const currentTo = await tx.getKey(toKeyID);
+                    const currentEntry = await tx.getEntry(entryID, entry.owner_did);
+                    if (currentFrom == null || currentTo == null || currentEntry == null) return false;
+                    if (currentFrom.version !== fromKey.version || currentTo.version !== version || currentEntry.key_id !== entry.key_id || currentEntry.hlc !== entry.hlc) {
+                        return false;
+                    }
+                    await putEntryRecord({
+                        entry: moved,
+                        owner: currentTo.owner_did,
+                        branchID,
+                        contentHLC: moved.hlc,
+                        target: tx,
+                        authority: params?.authority ?? authority,
+                        grant
+                    });
+                    return true;
+                });
+            } finally{
+                plaintext.fill(0);
+            }
+            if (!movedNow) await internals.manager.reKeyEntry({
+                ...input,
+                ownerDID: entry.owner_did
+            });
+        }
+    };
+}

package/lib/manager-keys.d.ts

@@ -0,0 +1,3 @@
+import { type ManagerContext, type ManagerInternals } from './manager-context.js';
+import type { CredentialManager } from './manager-types.js';
+export declare function createKeyMethods(ctx: ManagerContext, internals: ManagerInternals): Pick<CredentialManager, 'availableFactors' | 'unlock' | 'addFactor' | 'removeFactor' | 'lock' | 'lockAll' | 'status' | 'createKey' | 'rotate' | 'revoke' | 'grant' | 'listKeys' | 'countWrappings' | 'deleteKey'>;