@kubun/credential 0.17.4 → 0.18.0

package/lib/manager-rotate.js

@@ -0,0 +1,536 @@
+import { normalizeDID } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import { recordPayloadDigest, verifySignedRecord } from '@kubun/records';
+import { credentialRevocationRecordID, decodeCredentialRecord } from '@kubun/store-credential';
+import { CredentialInvalidEntry, CredentialKeyVersionMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialRepairPending, CredentialUnopenable } from './errors.js';
+import { isSecretFactorKind, wrappingNamesRemovedDevice } from './manager-context.js';
+import { getSuite } from './suite.js';
+export function createRotateFunctions(ctx, internals) {
+    const { store, identity, runtime, authority, cache, nextHLC, params } = ctx;
+    const { entryRecord, winningBranch, putRecord, keyRecord, keyUnique, putWrappingRecord, putEntryRecord, entryGrant, branchProofs, suiteForVersion } = internals.records;
+    const { factorsFromDescriptors, loadKey, openKey, openSpecificBranch } = internals.open;
+    async function rotateKey({ keyID, rotateParams, revokedDID, excludedRecipients = new Set() }) {
+        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 (revokedDID === undefined && !await (rotateParams?.authority ?? authority).authorize('administer', {
+            key,
+            store
+        })) {
+            throw new CredentialNotAuthorized('administer', keyID);
+        }
+        // An older partial rotation may have advanced the key row before writing
+        // this device's wrapping. Recover from the highest version we can open;
+        // locked factors and rejected secrets still require the caller's input.
+        let sourceVersion = key.version;
+        let previousKey;
+        for(let candidate = key.version; candidate >= 1; candidate -= 1){
+            try {
+                previousKey = (await openKey(keyID, rotateParams?.inputs, candidate)).contentKey;
+                sourceVersion = candidate;
+                break;
+            } catch (error) {
+                if (!(error instanceof CredentialUnopenable) || candidate === 1) throw error;
+            }
+        }
+        if (previousKey === undefined) throw new CredentialUnopenable(keyID, 'no openable version');
+        const previousSuite = getSuite(await suiteForVersion(keyID, sourceVersion, key.suite));
+        const suiteID = rotateParams?.suite ?? key.suite;
+        const suite = getSuite(suiteID);
+        const newVersion = key.version + 1;
+        // Open the old key before entering the transaction, then read every row
+        // being re-issued inside it. A concurrent grant or entry update must be
+        // included in the rotation, rather than replaced by an earlier snapshot.
+        // 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.
+        // Both keys are zeroed whether the transaction commits or rolls back.
+        let generatedKey;
+        try {
+            const contentKey = suite.generateContentKey(runtime);
+            generatedKey = contentKey;
+            // Mint the key-op stamp before the entries and wrappings it labels. All
+            // records commit together, so no reader sees its version bump alone.
+            const rotatedKey = {
+                keyID,
+                ownerDID: key.owner_did,
+                suite: suiteID,
+                version: newVersion,
+                state: key.state === 'retired' ? 'retired' : 'active'
+            };
+            const unique = await keyUnique(keyID);
+            const keyHLC = await nextHLC();
+            for(;;){
+                // Resolve recipient keys and derive any secret factors before taking a
+                // database lock. The locked read below validates this speculative set;
+                // a grant or rewrap that landed meanwhile makes us prepare again.
+                const observed = await store.listWrappings(keyID, sourceVersion);
+                const denied = new Set(excludedRecipients);
+                if (revokedDID !== undefined) denied.add(revokedDID);
+                const retained = observed.filter((wrapping)=>!wrappingNamesRemovedDevice(wrapping, denied)).map((wrapping)=>({
+                        recipientDID: wrapping.recipient_did,
+                        factors: factorsFromDescriptors(wrapping.factors, rotateParams?.inputs)
+                    }));
+                const prepared = [];
+                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
+                    });
+                    prepared.push({
+                        wrappingID,
+                        keyID,
+                        keyVersion: newVersion,
+                        factors: descriptors,
+                        iv,
+                        wrappedKey,
+                        recipientDID
+                    });
+                }
+                const branchID = await store.transaction(async (tx)=>{
+                    await tx.lockKeyRow(keyID);
+                    if ((await tx.getKey(keyID))?.version !== key.version) {
+                        throw new CredentialKeyVersionMismatch(keyID, key.version, (await tx.getKey(keyID))?.version ?? -1);
+                    }
+                    if (JSON.stringify(await tx.listWrappings(keyID, sourceVersion)) !== JSON.stringify(observed)) {
+                        return null;
+                    }
+                    const previousContentHLCs = new Map();
+                    const entryGrants = new Map();
+                    const plaintexts = [];
+                    try {
+                        for (const entry of (await tx.listEntries(keyID))){
+                            const entryID = entry.entry_id;
+                            const grant = await entryGrant(entryID, tx, entry.owner_did);
+                            if (grant !== undefined && normalizeDID(grant.grantDeviceDID) !== normalizeDID(identity.id)) {
+                                continue;
+                            }
+                            if (entry.key_version !== sourceVersion) {
+                                throw new CredentialKeyVersionMismatch(entry.entry_id, entry.key_version, sourceVersion);
+                            }
+                            const previous = await entryRecord(entryID, tx, entry.owner_did);
+                            const previousOp = previous === null ? null : await verifySignedRecord(previous);
+                            const stamp = previousOp?.claim.meta.contentHLC;
+                            if (typeof stamp === 'string' && (previousOp === null || !excludedRecipients.has(previousOp.issuer))) {
+                                previousContentHLCs.set(entryID, stamp);
+                            }
+                            if (grant !== undefined) entryGrants.set(entryID, grant);
+                            plaintexts.push({
+                                entryID,
+                                plaintext: previousSuite.decryptEntry({
+                                    contentKey: previousKey,
+                                    iv: new Uint8Array(entry.iv),
+                                    ciphertext: new Uint8Array(entry.ciphertext),
+                                    keyID,
+                                    keyVersion: entry.key_version,
+                                    entryID
+                                })
+                            });
+                        }
+                        const { branchID, branchRecordID: branchIDRecord } = await keyRecord({
+                            key: rotatedKey,
+                            keyUnique: unique,
+                            hlc: keyHLC,
+                            authority: rotateParams?.authority ?? authority,
+                            target: tx
+                        });
+                        for (const wrappingParams of prepared){
+                            await putWrappingRecord({
+                                wrapping: wrappingParams,
+                                owner: key.owner_did,
+                                branchID,
+                                branchRecordID: branchIDRecord,
+                                authority: rotateParams?.authority ?? authority,
+                                target: tx
+                            });
+                        }
+                        for (const { entryID, plaintext } of plaintexts){
+                            const grant = entryGrants.get(entryID);
+                            let encrypted;
+                            try {
+                                encrypted = suite.encryptEntry({
+                                    runtime,
+                                    contentKey,
+                                    plaintext,
+                                    keyID,
+                                    keyVersion: newVersion,
+                                    entryID
+                                });
+                            } finally{
+                                plaintext.fill(0);
+                            }
+                            const entryHLC = await nextHLC();
+                            await putEntryRecord({
+                                entry: {
+                                    entryID,
+                                    keyID,
+                                    keyVersion: newVersion,
+                                    ...encrypted,
+                                    hlc: entryHLC
+                                },
+                                owner: key.owner_did,
+                                branchID,
+                                contentHLC: previousContentHLCs.get(entryID) ?? entryHLC,
+                                target: tx,
+                                authority: rotateParams?.authority ?? authority,
+                                grant
+                            });
+                        }
+                        const revokedRecipients = new Set(excludedRecipients);
+                        if (revokedDID !== undefined) revokedRecipients.add(revokedDID);
+                        for (const recipientDID of revokedRecipients){
+                            await putRecord({
+                                type: 'credential.revocation',
+                                id: credentialRevocationRecordID(keyID, recipientDID),
+                                owner: key.owner_did,
+                                hlc: await nextHLC(),
+                                payload: {},
+                                meta: {
+                                    keyID,
+                                    revokedDID: recipientDID
+                                },
+                                target: tx,
+                                authority: rotateParams?.authority ?? authority
+                            });
+                        }
+                        if (revokedRecipients.size > 0) {
+                            for (const wrapping of (await tx.listWrappings(keyID))){
+                                const recipients = [
+                                    wrapping.recipient_did,
+                                    ...wrapping.factors.filter((factor)=>factor.kind === 'did').map((factor)=>factor.params.recipient)
+                                ];
+                                if (recipients.some((recipient)=>typeof recipient === 'string' && revokedRecipients.has(normalizeDID(recipient)))) {
+                                    await tx.deleteWrapping(wrapping.wrapping_id);
+                                }
+                            }
+                        }
+                        return branchID;
+                    } finally{
+                        for (const { plaintext } of plaintexts)plaintext.fill(0);
+                    }
+                });
+                if (branchID == null) continue;
+                // 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);
+        }
+    }
+    async function repairFork(keyID, inputs) {
+        await internals.removalRecovery.checkRemovalRecovery();
+        const key = await loadKey(keyID);
+        if (!await authority.authorize('administer', {
+            key,
+            store
+        })) {
+            throw new CredentialNotAuthorized('administer', keyID);
+        }
+        const branches = await store.listKeyBranches(keyID, key.version);
+        if (branches.length < 2) return {
+            status: 'not-needed'
+        };
+        const winner = await winningBranch(branches);
+        if (winner === null) throw new CredentialNotFound('Credential key branch', keyID);
+        const proofs = await branchProofs(keyID, key.version);
+        const digest = proofs.get(winner)?.repairDigest;
+        if (digest !== undefined && branches.every((branch)=>proofs.get(branch.branch_id)?.repairDigest === digest)) {
+            return {
+                status: 'not-needed'
+            };
+        }
+        const revocations = new Set((await store.listRevocations(keyID)).map((row)=>normalizeDID(row.recipient_did)));
+        const recovery = params.removalRecovery;
+        if (recovery !== undefined) {
+            for (const did of await recovery.removedDevices?.(key.owner_did) ?? []){
+                revocations.add(normalizeDID(did));
+            }
+        }
+        const wrappings = (await store.listWrappingsWithBranch(keyID, key.version)).filter((row)=>!wrappingNamesRemovedDevice(row, revocations));
+        const recipients = new Map();
+        const unaddressedWrappings = wrappings.filter((wrapping)=>wrapping.recipient_did === null);
+        const winnerRecipients = new Set();
+        for (const wrapping of wrappings){
+            const recipient = wrapping.recipient_did;
+            if (recipient === null) continue;
+            const normalized = normalizeDID(recipient);
+            if (wrapping.branch_id === winner) winnerRecipients.add(normalized);
+            if (!recipients.has(normalized) || wrapping.branch_id === winner) {
+                recipients.set(normalized, wrapping);
+            }
+        }
+        const candidates = [
+            ...await store.listEntryCandidates(keyID, key.version),
+            ...await store.listPriorEntryTombstones(keyID, key.version)
+        ];
+        const loserAddsRecipient = [
+            ...recipients.keys()
+        ].some((did)=>!winnerRecipients.has(did)) || unaddressedWrappings.some((wrapping)=>wrapping.branch_id !== winner);
+        const potentialLoserEntry = candidates.length > 0;
+        if (!potentialLoserEntry && !loserAddsRecipient) return {
+            status: 'not-needed'
+        };
+        const keys = new Map();
+        try {
+            for (const branch of branches){
+                const proof = proofs.get(branch.branch_id);
+                if (proof === undefined) return {
+                    status: 'pending'
+                };
+                const contentKey = await openSpecificBranch({
+                    keyID,
+                    version: key.version,
+                    branchID: branch.branch_id,
+                    suiteID: proof.suite,
+                    inputs
+                });
+                if (contentKey === null) return {
+                    status: 'pending'
+                };
+                keys.set(branch.branch_id, contentKey);
+            }
+            const byEntry = new Map();
+            const verifiedCandidates = await Promise.all(candidates.map(async (record)=>({
+                    record,
+                    op: await verifySignedRecord(record)
+                })));
+            for (const { record, op } of verifiedCandidates){
+                if (op === null) return {
+                    status: 'pending'
+                };
+                const branchID = op.claim.meta.branchID;
+                const contentHLC = op.claim.meta.contentHLC;
+                const keyVersion = op.claim.meta.keyVersion;
+                const priorTombstone = record.payload === null && typeof keyVersion === 'number' && keyVersion < key.version;
+                if (typeof branchID !== 'string' && !(branchID === undefined && record.payload === null) || typeof contentHLC !== 'string' || typeof keyVersion !== 'number' || typeof branchID === 'string' && !priorTombstone && !keys.has(branchID)) continue;
+                const list = byEntry.get(record.id) ?? [];
+                list.push({
+                    record,
+                    branchID: priorTombstone ? '' : branchID ?? '',
+                    contentHLC,
+                    keyVersion
+                });
+                byEntry.set(record.id, list);
+            }
+            const compareCandidates = (a, b)=>{
+                const contentOrder = HLC.compare(HLC.parse(a.contentHLC), HLC.parse(b.contentHLC));
+                if (contentOrder !== 0) return contentOrder;
+                if (a.keyVersion !== b.keyVersion) return a.keyVersion - b.keyVersion;
+                return a.record.opHash < b.record.opHash ? -1 : a.record.opHash > b.record.opHash ? 1 : 0;
+            };
+            const decryptCandidate = async (candidate)=>{
+                if (candidate.record.payload === null) return null;
+                const proof = proofs.get(candidate.branchID);
+                const sourceKey = keys.get(candidate.branchID);
+                const op = await verifySignedRecord(candidate.record);
+                if (proof === undefined || sourceKey === undefined || op === null) {
+                    throw new CredentialRepairPending(keyID);
+                }
+                const decoded = decodeCredentialRecord(candidate.record, op.claim.meta);
+                if (decoded.type !== 'credential.entry') throw new CredentialInvalidEntry(candidate.record.id);
+                return getSuite(proof.suite).decryptEntry({
+                    contentKey: sourceKey,
+                    iv: decoded.payload.iv,
+                    ciphertext: decoded.payload.ciphertext,
+                    keyID,
+                    keyVersion: candidate.keyVersion,
+                    entryID: candidate.record.id
+                });
+            };
+            const selected = [];
+            try {
+                let loserAddsEntry = false;
+                let unpreservableGrant = false;
+                for (const [entryID, versions] of byEntry){
+                    versions.sort(compareCandidates);
+                    const chosen = versions[versions.length - 1];
+                    if (chosen === undefined) continue;
+                    const plaintext = await decryptCandidate(chosen);
+                    const winnerCandidate = versions.filter((candidate)=>candidate.branchID === winner).sort(compareCandidates).at(-1);
+                    if (chosen.branchID !== winner) {
+                        const winnerPlaintext = winnerCandidate === undefined ? undefined : await decryptCandidate(winnerCandidate);
+                        const same = winnerPlaintext !== undefined && winnerCandidate?.contentHLC === chosen.contentHLC && (plaintext === null && winnerPlaintext === null || plaintext !== null && winnerPlaintext !== null && plaintext.length === winnerPlaintext.length && plaintext.every((byte, index)=>byte === winnerPlaintext[index]));
+                        winnerPlaintext?.fill(0);
+                        if (!same) loserAddsEntry = true;
+                    }
+                    const grant = await entryGrant(entryID, store, key.owner_did);
+                    if (grant !== undefined && normalizeDID(grant.grantDeviceDID) !== normalizeDID(identity.id)) {
+                        unpreservableGrant = true;
+                        plaintext?.fill(0);
+                        continue;
+                    }
+                    selected.push({
+                        entryID,
+                        plaintext,
+                        contentHLC: chosen.contentHLC,
+                        opHash: chosen.record.opHash,
+                        grant
+                    });
+                }
+                if (!loserAddsEntry && !loserAddsRecipient) return {
+                    status: 'not-needed'
+                };
+                if (unpreservableGrant) return {
+                    status: 'pending'
+                };
+                // Secret factors need the caller's input. Preserve the fork for a prompted retry
+                // instead of dropping a recovery wrap or changing its secret without consent.
+                if (wrappings.some((wrapping)=>wrapping.factors.some((factor)=>factor.kind !== 'did' && (!isSecretFactorKind(factor.kind) || inputs?.[factor.kind] == null)))) return {
+                    status: 'pending'
+                };
+                const stable = JSON.stringify({
+                    recipients: [
+                        ...recipients.keys()
+                    ].sort(),
+                    entries: selected.map(({ entryID, contentHLC, opHash })=>({
+                            entryID,
+                            contentHLC,
+                            opHash
+                        })).sort((a, b)=>a.entryID.localeCompare(b.entryID))
+                });
+                const repairDigest = recordPayloadDigest(new TextEncoder().encode(stable));
+                if (repairDigest === null) throw new Error('Missing repair digest');
+                const newVersion = key.version + 1;
+                const suite = getSuite(key.suite);
+                const contentKey = suite.generateContentKey(runtime);
+                try {
+                    const prepared = [];
+                    for (const wrapping of [
+                        ...recipients.values(),
+                        ...unaddressedWrappings
+                    ]){
+                        const wrappingID = runtime.getRandomID();
+                        const wrapped = await suite.wrap({
+                            runtime,
+                            contentKey,
+                            factors: factorsFromDescriptors(wrapping.factors, inputs),
+                            wrappingID,
+                            keyID,
+                            keyVersion: newVersion
+                        });
+                        prepared.push({
+                            wrappingID,
+                            keyID,
+                            keyVersion: newVersion,
+                            factors: wrapped.descriptors,
+                            iv: wrapped.iv,
+                            wrappedKey: wrapped.wrappedKey,
+                            recipientDID: wrapping.recipient_did
+                        });
+                    }
+                    const unique = await keyUnique(keyID);
+                    const keyHLC = await nextHLC();
+                    const expectedBranches = branches.map((branch)=>branch.branch_id).sort();
+                    await store.transaction(async (tx)=>{
+                        await tx.lockKeyRow(keyID);
+                        if ((await tx.getKey(keyID))?.version !== key.version) {
+                            throw new CredentialKeyVersionMismatch(keyID, key.version, (await tx.getKey(keyID))?.version ?? -1);
+                        }
+                        if (JSON.stringify((await tx.listKeyBranches(keyID, key.version)).map((row)=>row.branch_id).sort()) !== JSON.stringify(expectedBranches)) {
+                            throw new CredentialKeyVersionMismatch(keyID, key.version, -1);
+                        }
+                        const { branchID, branchRecordID } = await keyRecord({
+                            key: {
+                                keyID,
+                                ownerDID: key.owner_did,
+                                suite: key.suite,
+                                version: newVersion,
+                                state: key.state === 'retired' ? 'retired' : 'active'
+                            },
+                            keyUnique: unique,
+                            hlc: keyHLC,
+                            authority,
+                            target: tx,
+                            repairDigest
+                        });
+                        for (const wrapping of prepared){
+                            await putWrappingRecord({
+                                wrapping,
+                                owner: key.owner_did,
+                                branchID,
+                                branchRecordID,
+                                authority,
+                                target: tx
+                            });
+                        }
+                        for (const entry of selected){
+                            if (entry.plaintext === null) {
+                                await putRecord({
+                                    type: 'credential.entry',
+                                    id: entry.entryID,
+                                    owner: key.owner_did,
+                                    hlc: await nextHLC(),
+                                    payload: null,
+                                    meta: {
+                                        keyID,
+                                        keyVersion: newVersion,
+                                        contentHLC: entry.contentHLC,
+                                        branchID,
+                                        branchRecordID,
+                                        ...entry.grant === undefined ? {} : {
+                                            grantDeviceDID: normalizeDID(entry.grant.grantDeviceDID),
+                                            grantName: entry.grant.grantName,
+                                            grantOwnerDID: normalizeDID(entry.grant.grantOwnerDID ?? key.owner_did)
+                                        }
+                                    },
+                                    target: tx,
+                                    authority
+                                });
+                                continue;
+                            }
+                            const encrypted = suite.encryptEntry({
+                                runtime,
+                                contentKey,
+                                plaintext: entry.plaintext,
+                                keyID,
+                                keyVersion: newVersion,
+                                entryID: entry.entryID
+                            });
+                            await putEntryRecord({
+                                entry: {
+                                    entryID: entry.entryID,
+                                    keyID,
+                                    keyVersion: newVersion,
+                                    ...encrypted,
+                                    hlc: await nextHLC()
+                                },
+                                owner: key.owner_did,
+                                branchID,
+                                contentHLC: entry.contentHLC,
+                                target: tx,
+                                authority,
+                                grant: entry.grant
+                            });
+                        }
+                    });
+                    return {
+                        status: 'rotated',
+                        version: newVersion
+                    };
+                } finally{
+                    contentKey.fill(0);
+                }
+            } finally{
+                for (const entry of selected)entry.plaintext?.fill(0);
+            }
+        } finally{
+            for (const keyBytes of keys.values())keyBytes.fill(0);
+        }
+    }
+    return {
+        rotateKey,
+        repairFork
+    };
+}