@kubun/credential 0.17.4 → 0.18.0

package/lib/manager-records.js

@@ -0,0 +1,291 @@
+import { normalizeDID } from '@kokuin/token';
+import { recordClaimDigest, recordPayloadDigest, signRecordOp, verifyRecordOp, verifySignedRecord } from '@kubun/records';
+import { credentialRecordAdapter, decodeCredentialRecord, encodeCredentialRecordPayload } from '@kubun/store-credential';
+import { CredentialNotAuthorized, CredentialNotFound } from './errors.js';
+export function createRecordFunctions(ctx) {
+    const { params, store, identity, authority, nextHLC } = ctx;
+    const records = ()=>credentialRecordAdapter(store);
+    const selectedCopy = (decision)=>decision?.copies[0] ?? null;
+    async function storedKeyRecord(keyID) {
+        const key = await store.getKey(keyID);
+        if (key === undefined) return null;
+        return selectedCopy(await records().get({
+            type: 'credential.key',
+            owner: key.owner_did,
+            id: keyID
+        }));
+    }
+    async function entryRecord(entryID, target = store, ownerDID) {
+        const entry = await target.getEntry(entryID, ownerDID);
+        const key = entry === undefined ? undefined : await target.getKey(entry.key_id, entry.owner_did);
+        if (key === undefined) return null;
+        return selectedCopy(await credentialRecordAdapter(target).get({
+            type: 'credential.entry',
+            owner: key.owner_did,
+            id: entryID
+        }));
+    }
+    async function winningBranch(branches) {
+        let winner = null;
+        const verified = await Promise.all(branches.map(async (branch)=>({
+                branch,
+                op: await verifyRecordOp(branch.op_jwt)
+            })));
+        for (const { branch, op } of verified){
+            if (op === null || branch.branch_id !== `${op.claim.hlc}:${op.opHash}`) continue;
+            const candidate = {
+                branchID: branch.branch_id,
+                digest: recordClaimDigest(op.claim),
+                opHash: op.opHash
+            };
+            if (winner === null || candidate.digest > winner.digest || candidate.digest === winner.digest && candidate.opHash > winner.opHash) {
+                winner = candidate;
+            }
+        }
+        return winner?.branchID ?? null;
+    }
+    async function putRecord(args) {
+        const { type, id, owner, hlc, payload, meta } = args;
+        const target = args.target ?? store;
+        const recordAuthority = args.authority ?? authority;
+        if (params.removalRecovery === undefined && normalizeDID(owner).startsWith('did:kokuin:')) {
+            throw new CredentialNotAuthorized('administer', id);
+        }
+        const bytes = payload === null ? null : encodeCredentialRecordPayload(type, payload);
+        const { opJWT, opHash } = await signRecordOp(identity, {
+            type,
+            id,
+            owner: normalizeDID(owner),
+            hlc,
+            payloadDigest: recordPayloadDigest(bytes),
+            deleted: bytes === null,
+            meta: recordAuthority.delegationTokens?.length ? {
+                ...meta,
+                delegationTokens: [
+                    ...recordAuthority.delegationTokens
+                ]
+            } : meta
+        });
+        const record = {
+            type,
+            id,
+            owner: normalizeDID(owner),
+            hlc,
+            payload: bytes,
+            opJWT,
+            opHash
+        };
+        await target.putRecord(record);
+        return record;
+    }
+    async function keyRecord(args) {
+        const { key, keyUnique, hlc, repairDigest } = args;
+        const recordAuthority = args.authority ?? authority;
+        const target = args.target ?? store;
+        const record = await putRecord({
+            type: 'credential.key',
+            id: key.keyID,
+            owner: key.ownerDID,
+            hlc,
+            payload: {
+                suite: key.suite,
+                state: key.state
+            },
+            meta: {
+                keyID: key.keyID,
+                keyUnique,
+                version: key.version,
+                state: key.state
+            },
+            target,
+            authority: recordAuthority
+        });
+        const branchID = `${record.hlc}:${record.opHash}`;
+        const payload = {
+            authorDID: normalizeDID(identity.id),
+            hlc: record.hlc,
+            opJWT: record.opJWT,
+            opHash: record.opHash,
+            suite: key.suite
+        };
+        const branchIDRecord = recordPayloadDigest(encodeCredentialRecordPayload('credential.key-branch', payload));
+        if (branchIDRecord === null) throw new Error('Key branch payload has no digest');
+        await putRecord({
+            type: 'credential.key-branch',
+            id: branchIDRecord,
+            owner: key.ownerDID,
+            hlc,
+            payload,
+            meta: {
+                keyID: key.keyID,
+                keyVersion: key.version,
+                branchID,
+                ...repairDigest === undefined ? {} : {
+                    repairDigest
+                }
+            },
+            target,
+            authority: recordAuthority
+        });
+        return {
+            branchID,
+            branchRecordID: branchIDRecord
+        };
+    }
+    async function keyUnique(keyID) {
+        const stored = await storedKeyRecord(keyID);
+        const op = stored === null ? null : await verifySignedRecord(stored);
+        const unique = op?.claim.meta.keyUnique;
+        if (typeof unique !== 'string') throw new CredentialNotFound('Credential key record', keyID);
+        return unique;
+    }
+    async function branchRecordID(args) {
+        const { keyID, version, branchID } = args;
+        const target = args.target ?? store;
+        const branches = await credentialRecordAdapter(target).list([
+            'credential.key-branch'
+        ]);
+        for (const decision of branches){
+            const branch = decision.copies[0];
+            if (branch === undefined) continue;
+            const op = await verifySignedRecord(branch);
+            if (op?.claim.meta.keyID === keyID && op.claim.meta.keyVersion === version && op.claim.meta.branchID === branchID) return branch.id;
+        }
+        throw new CredentialNotFound('Credential key branch record', branchID);
+    }
+    async function putWrappingRecord(args) {
+        const { wrapping, owner, branchID } = args;
+        const recordAuthority = args.authority ?? authority;
+        const target = args.target ?? store;
+        await putRecord({
+            type: 'credential.wrapping',
+            id: wrapping.wrappingID,
+            owner,
+            hlc: await nextHLC(),
+            payload: {
+                factors: wrapping.factors,
+                iv: wrapping.iv,
+                wrappedKey: wrapping.wrappedKey
+            },
+            meta: {
+                keyID: wrapping.keyID,
+                keyVersion: wrapping.keyVersion,
+                branchID,
+                branchRecordID: args.branchRecordID ?? await branchRecordID({
+                    keyID: wrapping.keyID,
+                    version: wrapping.keyVersion,
+                    branchID,
+                    target
+                }),
+                recipient: wrapping.recipientDID ?? null
+            },
+            target,
+            authority: recordAuthority
+        });
+    }
+    async function putEntryRecord(args) {
+        const { entry, owner, branchID, grant } = args;
+        const contentHLC = args.contentHLC ?? entry.hlc;
+        const target = args.target ?? store;
+        const recordAuthority = args.authority ?? authority;
+        const branchIDRecord = await branchRecordID({
+            keyID: entry.keyID,
+            version: entry.keyVersion,
+            branchID,
+            target
+        });
+        await putRecord({
+            type: 'credential.entry',
+            id: entry.entryID,
+            owner,
+            hlc: entry.hlc,
+            payload: {
+                iv: entry.iv,
+                ciphertext: entry.ciphertext
+            },
+            meta: {
+                keyID: entry.keyID,
+                keyVersion: entry.keyVersion,
+                contentHLC,
+                branchID,
+                branchRecordID: branchIDRecord,
+                ...grant === undefined ? {} : {
+                    grantDeviceDID: normalizeDID(grant.grantDeviceDID),
+                    grantName: grant.grantName,
+                    grantOwnerDID: normalizeDID(grant.grantOwnerDID ?? owner)
+                }
+            },
+            target,
+            authority: recordAuthority
+        });
+    }
+    async function entryGrant(entryID, target = store, ownerDID) {
+        const record = await entryRecord(entryID, target, ownerDID);
+        const op = record === null ? null : await verifySignedRecord(record);
+        const device = op?.claim.meta.grantDeviceDID;
+        const name = op?.claim.meta.grantName;
+        const accountOwner = op?.claim.meta.grantOwnerDID;
+        return typeof device === 'string' && typeof name === 'string' ? {
+            grantDeviceDID: device,
+            grantName: name,
+            grantOwnerDID: typeof accountOwner === 'string' ? accountOwner : op?.claim.owner
+        } : undefined;
+    }
+    async function writableGrant(entryID, ownerDID) {
+        const grant = await entryGrant(entryID, store, ownerDID);
+        if (grant !== undefined && normalizeDID(grant.grantDeviceDID) !== normalizeDID(identity.id)) {
+            throw new CredentialNotAuthorized('administer', entryID);
+        }
+        return grant;
+    }
+    async function suiteForVersion(keyID, version, currentSuite) {
+        const current = await store.getKey(keyID);
+        if (current?.version === version) return currentSuite;
+        const branches = await store.listKeyBranches(keyID, version);
+        const winner = await winningBranch(branches);
+        for (const decision of (await records().list([
+            'credential.key-branch'
+        ]))){
+            const record = decision.copies[0];
+            if (record === undefined) continue;
+            const op = await verifySignedRecord(record);
+            if (op?.claim.meta.keyID !== keyID || op.claim.meta.keyVersion !== version || op.claim.meta.branchID !== winner) continue;
+            const decoded = decodeCredentialRecord(record, op.claim.meta);
+            if (decoded.type === 'credential.key-branch') return decoded.payload.suite;
+        }
+        throw new CredentialNotFound('Historical credential suite', `${keyID}@${version}`);
+    }
+    async function branchProofs(keyID, version) {
+        const proofs = new Map();
+        for (const decision of (await records().list([
+            'credential.key-branch'
+        ]))){
+            const record = decision.copies[0];
+            if (record === undefined) continue;
+            const op = await verifySignedRecord(record);
+            if (op?.claim.meta.keyID !== keyID || op.claim.meta.keyVersion !== version) continue;
+            const decoded = decodeCredentialRecord(record, op.claim.meta);
+            if (decoded.type !== 'credential.key-branch') continue;
+            proofs.set(op.claim.meta.branchID, {
+                suite: decoded.payload.suite,
+                repairDigest: op.claim.meta.repairDigest
+            });
+        }
+        return proofs;
+    }
+    return {
+        storedKeyRecord,
+        entryRecord,
+        winningBranch,
+        putRecord,
+        keyRecord,
+        keyUnique,
+        branchRecordID,
+        putWrappingRecord,
+        putEntryRecord,
+        entryGrant,
+        writableGrant,
+        branchProofs,
+        suiteForVersion
+    };
+}

package/lib/manager-removal-recovery.d.ts

@@ -0,0 +1,7 @@
+import { type ManagerContext, type ManagerInternals } from './manager-context.js';
+import type { RecoverRemovedDevicesParams } from './manager-types.js';
+export type RemovalRecoveryFunctions = {
+    recoverRemovedDevices: (options: RecoverRemovedDevicesParams) => Promise<number>;
+    checkRemovalRecovery: () => Promise<void>;
+};
+export declare function createRemovalRecoveryFunctions(ctx: ManagerContext, internals: ManagerInternals): RemovalRecoveryFunctions;

package/lib/manager-removal-recovery.js

@@ -0,0 +1,211 @@
+import { normalizeDID } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import { recordPayloadDigest, signRecordOp, verifySignedRecord } from '@kubun/records';
+import { credentialRecordAdapter, decodeCredentialRecord } from '@kubun/store-credential';
+import { CredentialKeyVersionMismatch, CredentialNotFound } from './errors.js';
+import { wrappingNamesRemovedDevice } from './manager-context.js';
+import { getSuite } from './suite.js';
+export function createRemovalRecoveryFunctions(ctx, internals) {
+    const { store, identity, runtime, hlc, nextHLC, params, state } = ctx;
+    const { storedKeyRecord, winningBranch, branchRecordID, putEntryRecord, suiteForVersion } = internals.records;
+    const { openKey } = internals.open;
+    const records = ()=>credentialRecordAdapter(store);
+    async function recoverRemovedDevices(options) {
+        if (params.removalRecovery === undefined) {
+            // The explicit call supplied the missing recovery context. Keep that context scoped
+            // to this recovery, rather than letting unrelated writes bypass the constructor guard.
+            return internals.createManager({
+                ...params,
+                removalRecovery: {
+                    ...options,
+                    headVersion: async (ownerDID)=>JSON.stringify([
+                            ...await options.removedDevices?.(ownerDID) ?? new Set()
+                        ].sort())
+                }
+            }).recoverRemovedDevices(options);
+        }
+        const controller = await options.resolveController(identity.id);
+        if (controller === null) return 0;
+        const owner = normalizeDID(controller);
+        const self = normalizeDID(identity.id);
+        const recordTypes = [
+            'credential.key',
+            'credential.wrapping',
+            'credential.entry',
+            'credential.revocation'
+        ];
+        const removed = new Set();
+        for (const decision of (await records().list(recordTypes))){
+            if (decision.key.owner !== owner) continue;
+            for (const record of decision.copies){
+                const op = await verifySignedRecord(record, options.methods);
+                if (op === null || op.issuer === owner || op.issuer === self) continue;
+                if (await options.resolveController(op.issuer) !== owner) removed.add(op.issuer);
+            }
+        }
+        if (removed.size === 0) return 0;
+        for (const did of await options.removedDevices?.(owner) ?? []){
+            removed.add(normalizeDID(did));
+        }
+        let written = 0;
+        for (const key of (await store.listKeys(owner))){
+            const record = await storedKeyRecord(key.key_id);
+            const op = record === null ? null : await verifySignedRecord(record, options.methods);
+            if (op === null || !removed.has(op.issuer) || op.claim.deleted) continue;
+            try {
+                await internals.rotate.rotateKey({
+                    keyID: key.key_id,
+                    rotateParams: {
+                        methods: options.methods
+                    },
+                    excludedRecipients: removed
+                });
+                written += 1;
+            } catch (error) {
+                // A second local recovery may have rotated the same key after our scan.
+                // Its transaction committed the complete rotation; reissue below still
+                // picks up any former-device records it left behind.
+                if (!(error instanceof CredentialKeyVersionMismatch) || ((await store.getKey(key.key_id))?.version ?? 0) <= key.version) {
+                    throw error;
+                }
+            }
+        }
+        // Re-read after rotation: it may already have replaced some former-device entries.
+        for (const decision of (await records().list(recordTypes))){
+            if (decision.key.owner !== owner || decision.key.type === 'credential.key') continue;
+            let record;
+            let op = null;
+            for (const copy of decision.copies){
+                const verified = await verifySignedRecord(copy, options.methods);
+                if (verified !== null && removed.has(verified.issuer)) {
+                    record = copy;
+                    op = verified;
+                    break;
+                }
+            }
+            if (record === undefined || op === null) continue;
+            if (record.type === 'credential.entry') {
+                const grantDevice = op.claim.meta.grantDeviceDID;
+                if (typeof grantDevice === 'string' && removed.has(normalizeDID(grantDevice))) continue;
+            }
+            if (record.type === 'credential.wrapping') {
+                if (record.payload !== null) {
+                    const decoded = decodeCredentialRecord(record, op.claim.meta);
+                    if (decoded.type === 'credential.wrapping' && wrappingNamesRemovedDevice({
+                        recipient_did: op.claim.meta.recipient ?? null,
+                        factors: decoded.payload.factors
+                    }, removed)) continue;
+                }
+            }
+            const oldStamp = HLC.tryParse(record.hlc);
+            if (oldStamp !== null) hlc.receive(oldStamp);
+            const stamp = await nextHLC();
+            let meta = op.claim.meta;
+            if (record.type === 'credential.entry') {
+                const keyID = op.claim.meta.keyID;
+                const oldVersion = op.claim.meta.keyVersion;
+                if (typeof keyID !== 'string' || typeof oldVersion !== 'number') continue;
+                const key = await store.getKey(keyID);
+                if (key === undefined) continue;
+                meta = {
+                    ...meta,
+                    contentHLC: stamp,
+                    keyVersion: key.version
+                };
+                if (record.payload === null && oldVersion !== key.version) {
+                    const branches = await store.listKeyBranches(keyID, key.version);
+                    if (branches.length === 0) {
+                        delete meta.branchID;
+                        delete meta.branchRecordID;
+                    } else {
+                        const currentBranchID = await winningBranch(branches);
+                        if (currentBranchID === null) throw new CredentialNotFound('Credential key branch', keyID);
+                        meta.branchID = currentBranchID;
+                        meta.branchRecordID = await branchRecordID({
+                            keyID,
+                            version: key.version,
+                            branchID: currentBranchID
+                        });
+                    }
+                }
+                if (record.payload !== null && oldVersion !== key.version) {
+                    const entry = await store.getEntry(record.id, record.owner);
+                    if (entry === undefined) continue;
+                    const source = await openKey(keyID, undefined, oldVersion);
+                    let target;
+                    let plaintext;
+                    try {
+                        target = await openKey(keyID);
+                        const sourceSuite = getSuite(await suiteForVersion(keyID, oldVersion, key.suite));
+                        plaintext = sourceSuite.decryptEntry({
+                            contentKey: source.contentKey,
+                            iv: new Uint8Array(entry.iv),
+                            ciphertext: new Uint8Array(entry.ciphertext),
+                            keyID,
+                            keyVersion: oldVersion,
+                            entryID: record.id
+                        });
+                        const encrypted = getSuite(key.suite).encryptEntry({
+                            runtime,
+                            contentKey: target.contentKey,
+                            plaintext,
+                            keyID,
+                            keyVersion: key.version,
+                            entryID: record.id
+                        });
+                        await putEntryRecord({
+                            entry: {
+                                entryID: record.id,
+                                keyID,
+                                keyVersion: key.version,
+                                ...encrypted,
+                                hlc: stamp
+                            },
+                            owner: record.owner,
+                            branchID: target.branchID,
+                            contentHLC: stamp
+                        });
+                    } finally{
+                        plaintext?.fill(0);
+                        source.contentKey.fill(0);
+                        target?.contentKey.fill(0);
+                    }
+                    written += 1;
+                    continue;
+                }
+            }
+            const { opJWT, opHash } = await signRecordOp(identity, {
+                type: record.type,
+                id: record.id,
+                owner: record.owner,
+                hlc: stamp,
+                payloadDigest: recordPayloadDigest(record.payload),
+                deleted: record.payload === null,
+                meta
+            });
+            await store.putRecord({
+                ...record,
+                hlc: stamp,
+                opJWT,
+                opHash
+            }, options.methods);
+            written += 1;
+        }
+        return written;
+    }
+    async function checkRemovalRecovery() {
+        const recovery = params.removalRecovery;
+        if (recovery === undefined) return;
+        if ('ensure' in recovery) return await recovery.ensure();
+        const controller = await recovery.resolveController(identity.id);
+        if (controller === null) return;
+        const version = await recovery.headVersion(normalizeDID(controller));
+        if (version === state.completedRecoveryHead) return;
+        await recoverRemovedDevices(recovery);
+        state.completedRecoveryHead = version;
+    }
+    return {
+        recoverRemovedDevices,
+        checkRemovalRecovery
+    };
+}

package/lib/manager-rotate.d.ts

@@ -0,0 +1,15 @@
+import type { ForkRepairResult } from './fork-repair.js';
+import { type ManagerContext, type ManagerInternals } from './manager-context.js';
+import type { RotateKeyParams } from './manager-types.js';
+import { type FactorInputs } from './suite.js';
+export type RotateKeyRunParams = {
+    keyID: string;
+    rotateParams?: RotateKeyParams;
+    revokedDID?: string;
+    excludedRecipients?: ReadonlySet<string>;
+};
+export type RotateFunctions = {
+    rotateKey: (params: RotateKeyRunParams) => Promise<number>;
+    repairFork: (keyID: string, inputs?: FactorInputs) => Promise<ForkRepairResult>;
+};
+export declare function createRotateFunctions(ctx: ManagerContext, internals: ManagerInternals): RotateFunctions;