@kokuin/store-vault 0.0.0-stage → 0.1.0

package/lib/coordinator-rotate.js

@@ -0,0 +1,436 @@
+import { compareRecordDecisionHLC } from '@kokuin/records';
+import { decodeVaultRecord, factorsFromDescriptors, getSuite, NoAvailableFactor, vaultRevocationRecordID } from '@kokuin/vault';
+import { VaultKeyLocked, VaultNotFound, VaultRepairPending } from './coordinator-context.js';
+import { settleAll } from './settle.js';
+export function createRotateFunctions(ctx, open, records) {
+    const { params } = ctx;
+    function excluded(row, recipients) {
+        const denied = new Set(recipients.map((did)=>vaultRevocationRecordID(row.keyID, did)));
+        return [
+            row.recipientDID,
+            ...row.descriptors.filter((d)=>d.kind === 'did').map((d)=>d.params.recipient)
+        ].some((did)=>typeof did === 'string' && denied.has(vaultRevocationRecordID(row.keyID, did)));
+    }
+    async function currentEntries(key, store) {
+        const rows = await store.listEntries(key);
+        const infos = await records.entryInfos(rows, store);
+        return rows.map((row, index)=>{
+            const info = infos[index];
+            if (info === undefined) throw new VaultNotFound();
+            return {
+                entryID: row.entryID,
+                row,
+                ...info,
+                opHash: '',
+                keyVersion: row.keyVersion,
+                branchID: row.provenance
+            };
+        });
+    }
+    async function candidate(key, record) {
+        const op = await ctx.verified(record);
+        const meta = op.claim.meta;
+        if (op.claim.owner !== key.ownerDID || meta.keyID !== key.keyID || typeof meta.contentHLC !== 'string' || typeof meta.keyVersion !== 'number') throw new VaultRepairPending();
+        let row;
+        if (!op.claim.deleted) {
+            const decoded = decodeVaultRecord(record, meta);
+            if (decoded.type !== 'vault.entry' || decoded.meta.kind === undefined || decoded.meta.label === undefined || decoded.meta.attributes === undefined || decoded.meta.branchID === undefined) throw new VaultRepairPending();
+            row = {
+                ownerDID: key.ownerDID,
+                keyID: key.keyID,
+                entryID: record.id,
+                keyVersion: meta.keyVersion,
+                hlc: record.hlc,
+                provenance: decoded.meta.branchID,
+                kind: decoded.meta.kind,
+                label: decoded.meta.label,
+                attributes: decoded.meta.attributes,
+                ...decoded.payload
+            };
+        }
+        return {
+            entryID: record.id,
+            row,
+            contentHLC: meta.contentHLC,
+            consumer: meta.consumer,
+            opHash: record.opHash,
+            keyVersion: meta.keyVersion,
+            branchID: typeof meta.branchID === 'string' ? meta.branchID : ''
+        };
+    }
+    async function candidates(key, store) {
+        const api = ctx.recordsFor(store);
+        const [current, prior] = await settleAll([
+            api.listEntryCandidates({
+                ...key,
+                keyVersion: key.version
+            }),
+            api.listPriorEntryTombstones({
+                ...key,
+                beforeVersion: key.version
+            })
+        ]);
+        // Checks run together; the first failure in record order still wins.
+        const values = await settleAll([
+            ...current,
+            ...prior
+        ].map((record)=>candidate(key, record)));
+        const grouped = new Map();
+        for (const value of values){
+            const list = grouped.get(value.entryID) ?? [];
+            list.push(value);
+            grouped.set(value.entryID, list);
+        }
+        return grouped;
+    }
+    const compare = (a, b)=>{
+        return compareRecordDecisionHLC(a.contentHLC, b.contentHLC) || a.keyVersion - b.keyVersion || (a.opHash < b.opHash ? -1 : a.opHash > b.opHash ? 1 : 0);
+    };
+    async function rotateLocked(request, store, repair) {
+        if (!Array.isArray(request.excludedRecipients) || !Array.isArray(request.reissue)) throw new TypeError('Explicit exclusions and entry reissue instructions are required');
+        const key = await ctx.key(request, store);
+        const branches = await ctx.branches(key, key.version, store);
+        if (repair && branches.length < 2) return null;
+        const wrappingsRead = async ()=>{
+            const existing = await store.listWrappings(key);
+            const current = existing.filter((w)=>w.keyVersion === key.version);
+            return {
+                existing,
+                current,
+                evidence: await ctx.wrappingEvidences(current, store)
+            };
+        };
+        // Ordered settling keeps the original precedence: branch, then wrapping, then entry failures.
+        const [winner, wrappingState, currentSelections] = await settleAll([
+            ctx.branch(key, key.version, store),
+            wrappingsRead(),
+            currentEntries(key, store)
+        ]);
+        const expectedBranches = branches.map((b)=>b.branchID);
+        const existingWrappings = wrappingState.existing;
+        const evidence = new Map(wrappingState.evidence.map((item)=>[
+                item.record.id,
+                item
+            ]));
+        let retained = wrappingState.current.filter((w)=>!excluded(w, request.excludedRecipients));
+        let selections = currentSelections;
+        const keys = new Map();
+        const pending = [];
+        const plaintexts = [];
+        let pinGate = Promise.resolve();
+        let generated;
+        try {
+            const openSource = (row)=>{
+                const run = async ()=>{
+                    const opened = await open.open({
+                        ...request,
+                        atVersion: row.keyVersion
+                    }, store, params.mode === 'replicated' ? row.provenance : undefined);
+                    return {
+                        contentKey: opened.contentKey,
+                        suite: opened.suite
+                    };
+                };
+                if (request.inputs?.pin === undefined) return run();
+                // PIN opens stay one at a time: a rejected PIN stops later attempts, spending one try.
+                const gated = pinGate.then(run);
+                pinGate = gated;
+                return gated;
+            };
+            const decrypt = (selection)=>{
+                const task = (async ()=>{
+                    if (selection.row === undefined) return null;
+                    const row = selection.row;
+                    const identity = JSON.stringify([
+                        row.keyVersion,
+                        row.provenance
+                    ]);
+                    let source = keys.get(identity);
+                    // Cache the promise, not the key: concurrent decrypts must share one open.
+                    if (source === undefined) {
+                        source = openSource(row);
+                        keys.set(identity, source);
+                    }
+                    const { contentKey, suite } = await source;
+                    const plaintext = getSuite(suite).decryptEntry({
+                        ...row,
+                        contentKey
+                    });
+                    plaintexts.push(plaintext);
+                    return plaintext;
+                })();
+                pending.push(task);
+                return task;
+            };
+            if (repair) {
+                const grouped = await candidates(key, store);
+                const selected = [];
+                let addsEntry = false;
+                const comparisons = [];
+                for (const list of grouped.values()){
+                    list.sort(compare);
+                    const chosen = list.at(-1);
+                    if (chosen === undefined) continue;
+                    selected.push(chosen);
+                    if (chosen.branchID === winner.branchID) continue;
+                    const winning = list.filter((s)=>s.branchID === winner.branchID).sort(compare).at(-1);
+                    if (winning === undefined || chosen.contentHLC !== winning.contentHLC) {
+                        addsEntry = true;
+                        continue;
+                    }
+                    comparisons.push([
+                        chosen,
+                        winning
+                    ]);
+                }
+                // Plaintext comparisons are independent. Decrypts run together; the first failure in
+                // group order wins.
+                const compared = await settleAll(comparisons.map(([chosen, winning])=>settleAll([
+                        decrypt(chosen),
+                        decrypt(winning)
+                    ])));
+                for (const [a, b] of compared)if (a === null !== (b === null) || a !== null && b !== null && (a.length !== b.length || !a.every((v, i)=>v === b[i]))) addsEntry = true;
+                const signature = (w)=>{
+                    return JSON.stringify({
+                        recipient: w.recipientDID,
+                        factors: factorsFromDescriptors(w.descriptors, request.inputs)
+                    });
+                };
+                const winnerRecipients = new Set(retained.filter((w)=>w.provenance === winner.branchID).map(signature));
+                const addsRecipient = retained.some((w)=>!winnerRecipients.has(signature(w)));
+                let unreadableProjection = false;
+                const versionBranches = new Map();
+                for (const selection of selections){
+                    if (selection.row === undefined) continue;
+                    // Selections share few key versions. Read each version's branch once.
+                    let branch = versionBranches.get(selection.keyVersion);
+                    if (branch === undefined) {
+                        branch = ctx.branch(key, selection.keyVersion, store);
+                        versionBranches.set(selection.keyVersion, branch);
+                    }
+                    if (selection.branchID !== (await branch).branchID) {
+                        unreadableProjection = true;
+                        break;
+                    }
+                }
+                if (!addsEntry && !addsRecipient && !unreadableProjection && request.reissue.length === 0 && request.excludedRecipients.length === 0) return null;
+                const unique = new Map();
+                for (const wrapping of [
+                    ...retained.filter((w)=>w.provenance === winner.branchID),
+                    ...retained
+                ]){
+                    const id = signature(wrapping);
+                    if (!unique.has(id)) unique.set(id, wrapping);
+                }
+                retained = [
+                    ...unique.values()
+                ];
+                selections = selected;
+            }
+            const instructions = new Map(request.reissue.map((instruction)=>[
+                    instruction.entryID,
+                    instruction
+                ]));
+            if (instructions.size !== request.reissue.length || [
+                ...instructions.keys()
+            ].some((id)=>!selections.some((s)=>s.entryID === id))) throw new TypeError('Reissue instructions must name distinct existing entries');
+            const suite = getSuite(request.suite ?? key.suite);
+            const next = {
+                ...key,
+                version: key.version + 1,
+                suite: suite.id
+            };
+            const contentKey = suite.generateContentKey(params.runtime);
+            generated = contentKey;
+            // Key records and wraps are independent. Wrapping IDs are drawn in retained order.
+            const [chain, wrapped] = await settleAll([
+                params.mode === 'replicated' ? ctx.keyRecords(next, store) : Promise.resolve({
+                    records: [],
+                    branchID: '',
+                    branchRecordID: ''
+                }),
+                settleAll(retained.map(async (previous)=>{
+                    const wrappingID = params.runtime.getRandomID();
+                    const result = await suite.wrap({
+                        runtime: params.runtime,
+                        contentKey,
+                        factors: factorsFromDescriptors(previous.descriptors, request.inputs),
+                        wrappingID,
+                        keyID: key.keyID,
+                        keyVersion: next.version,
+                        methods: params.methods
+                    });
+                    return {
+                        previous,
+                        wrappingID,
+                        result
+                    };
+                }))
+            ]);
+            // Signing stays sequential, so a failed signature stops the rest and a prompting signer is
+            // asked nothing after it. HLC allocation and output follow the order: wrappings, entries,
+            // then revocations.
+            const output = [
+                ...chain.records
+            ];
+            const sign = async (task)=>{
+                output.push(await task);
+            };
+            const wrappings = [];
+            for (const { previous, wrappingID, result } of wrapped){
+                const row = {
+                    ...next,
+                    wrappingID,
+                    keyVersion: next.version,
+                    recipientDID: previous.recipientDID,
+                    provenance: chain.branchID,
+                    ...result
+                };
+                wrappings.push(row);
+                if (params.mode === 'replicated') {
+                    const prior = evidence.get(previous.wrappingID);
+                    if (prior === undefined) throw new VaultNotFound();
+                    await sign(records.wrapping(row, chain, prior.op.claim.meta.consumer, await params.nextHLC()));
+                }
+            }
+            const entries = [];
+            const deletions = [];
+            const reissued = selections.map((selected)=>{
+                const instruction = instructions.get(selected.entryID);
+                const deleting = instruction?.action === 'delete' || selected.row === undefined && instruction?.action !== 'replace';
+                const decrypting = instruction?.action === 'skip' || deleting || instruction?.action === 'replace' ? undefined : decrypt(selected);
+                // Awaited in selection order below. An earlier failure must not surface as unhandled.
+                decrypting?.catch(()=>{});
+                return {
+                    selected,
+                    instruction,
+                    deleting,
+                    decrypting
+                };
+            });
+            for (const { selected, instruction, deleting, decrypting } of reissued){
+                if (instruction?.action === 'skip') continue;
+                const contentHLC = instruction?.contentHLC ?? selected.contentHLC;
+                const consumer = instruction !== undefined && Object.hasOwn(instruction, 'consumer') ? instruction.consumer : selected.consumer;
+                const hlc = await params.nextHLC();
+                if (deleting) {
+                    deletions.push(selected.entryID);
+                    if (params.mode === 'replicated') await sign(ctx.signed('vault.entry', {
+                        ownerDID: key.ownerDID,
+                        id: selected.entryID
+                    }, null, {
+                        keyID: key.keyID,
+                        keyVersion: next.version,
+                        branchID: chain.branchID,
+                        branchRecordID: chain.branchRecordID,
+                        contentHLC,
+                        consumer
+                    }, hlc));
+                    continue;
+                }
+                const plaintext = instruction?.action === 'replace' ? instruction.plaintext : await decrypting;
+                if (plaintext === null || selected.row === undefined) throw new VaultRepairPending();
+                const encrypted = suite.encryptEntry({
+                    runtime: params.runtime,
+                    contentKey,
+                    plaintext,
+                    keyID: key.keyID,
+                    keyVersion: next.version,
+                    entryID: selected.entryID
+                });
+                const row = {
+                    ...selected.row,
+                    keyVersion: next.version,
+                    ...encrypted,
+                    hlc,
+                    provenance: chain.branchID
+                };
+                entries.push(row);
+                if (params.mode === 'replicated') await sign(records.entry(row, chain, contentHLC, consumer));
+            }
+            if (params.mode === 'replicated') {
+                for (const did of new Set(request.excludedRecipients)){
+                    const id = vaultRevocationRecordID(key.keyID, did);
+                    const revokedDID = id.slice(id.indexOf('/') + 1);
+                    await sign(ctx.signed('vault.revocation', {
+                        ownerDID: key.ownerDID,
+                        id
+                    }, {}, {
+                        keyID: key.keyID,
+                        revokedDID,
+                        consumer: null
+                    }, await params.nextHLC()));
+                }
+                await ctx.write(store, output, {
+                    key: {
+                        ...key,
+                        expectedVersion: key.version,
+                        expectedBranches
+                    }
+                }, request);
+            } else {
+                await store.putKey(next);
+                // Each set names distinct rows, so the batched writes run together. The first failure in
+                // the old order wins.
+                await settleAll([
+                    store.putWrappings(wrappings),
+                    store.putEntries(entries),
+                    store.deleteEntries(deletions.map((entryID)=>({
+                            ownerDID: key.ownerDID,
+                            entryID
+                        }))),
+                    store.deleteWrappings(existingWrappings.filter((w)=>excluded(w, request.excludedRecipients)))
+                ]);
+            }
+            return next.version;
+        } finally{
+            // Let every started decrypt settle first, so no key or plaintext arrives after zeroing.
+            await Promise.allSettled(pending);
+            for (const source of (await Promise.allSettled(keys.values())))if (source.status === 'fulfilled') source.value.contentKey.fill(0);
+            for (const plaintext of plaintexts)plaintext.fill(0);
+            generated?.fill(0);
+        }
+    }
+    async function rotate(request) {
+        await ctx.authorize('rotate', 'administer', request);
+        const version = await ctx.locked([
+            request
+        ], (tx)=>rotateLocked(request, tx, false));
+        if (version === null) throw new VaultNotFound();
+        ctx.evict(request);
+        return version;
+    }
+    async function repairFork(request) {
+        await ctx.authorize('repairFork', 'administer', request);
+        if (params.mode === 'local') return {
+            status: 'not-needed'
+        };
+        try {
+            const version = await ctx.locked([
+                request
+            ], async (tx)=>{
+                // A projection naming the wrong record refuses every branch read as pending. Rebuild it
+                // from the signed records first, so repair sees the key's real branches.
+                await ctx.recordsFor(tx).rebuildKeyBranches(request);
+                return rotateLocked(request, tx, true);
+            });
+            if (version === null) return {
+                status: 'not-needed'
+            };
+            ctx.evict(request);
+            return {
+                status: 'rotated',
+                version
+            };
+        } catch (error) {
+            if (error instanceof VaultRepairPending || error instanceof VaultKeyLocked || error instanceof NoAvailableFactor) return {
+                status: 'pending'
+            };
+            throw error;
+        }
+    }
+    return {
+        rotate,
+        repairFork
+    };
+}

package/lib/coordinator-types.d.ts

@@ -0,0 +1,139 @@
+import type { SignedRecord } from '@kokuin/records';
+import type { SigningIdentity } from '@kokuin/token';
+import type { FactorInput, FactorInputs, KeyCacheParams, PinThrottleParams, CredentialAuthorityRequest as RecordAuthorityRequest, SecretFactorKind, UnwrapParams, WrapParams } from '@kokuin/vault';
+import type { VaultRecords, VaultRecordsParams } from './records.js';
+import type { EntryAddress, EntryFilter, EntryRow, KeyAddress, KeyRow, UpdateEntryResult, VaultStoreAPI } from './types.js';
+/** Unsigned operation requests never fabricate record signatures, including replicated reads. */
+export type CredentialAuthorityRequest = RecordAuthorityRequest | {
+    source: 'local';
+    mode: 'local' | 'replicated';
+    operation: string;
+    owner: string;
+    issuer: string;
+    verb: 'read' | 'administer';
+    keyID?: string;
+    entryID?: string;
+    transportContext: unknown;
+    request: unknown;
+    store: Pick<VaultStoreAPI, 'getKey' | 'getEntry' | 'listKeys' | 'listWrappings' | 'listEntries'>;
+};
+export type CredentialAuthority = {
+    authorize(request: CredentialAuthorityRequest): Promise<boolean>;
+};
+export type CoordinatorCall = {
+    transportContext?: unknown;
+};
+export type OpenKeyParams = KeyAddress & CoordinatorCall & {
+    inputs?: FactorInputs;
+    atVersion?: number;
+};
+export type OpenedKey = {
+    contentKey: Uint8Array;
+    version: number;
+    branchID: string;
+    suite: number;
+};
+export type CreateKeyParams = CoordinatorCall & {
+    ownerDID: string;
+    wrappings?: Array<Array<FactorInput>>;
+    suite?: number;
+    consumer?: unknown;
+};
+export type EntryWriteParams = KeyAddress & EntryAddress & CoordinatorCall & Pick<EntryRow, 'kind' | 'label' | 'attributes'> & {
+    plaintext: Uint8Array;
+    inputs?: FactorInputs;
+    consumer?: unknown;
+};
+export type EntryUpdateParams = EntryAddress & CoordinatorCall & {
+    plaintext: Uint8Array;
+    inputs?: FactorInputs;
+};
+export type EntryReissue = {
+    entryID: string;
+    contentHLC?: string;
+    consumer?: unknown;
+} & ({
+    action: 'preserve' | 'skip' | 'delete';
+} | {
+    action: 'replace';
+    plaintext: Uint8Array;
+});
+export type RotateKeyParams = OpenKeyParams & {
+    excludedRecipients: ReadonlyArray<string>;
+    reissue: ReadonlyArray<EntryReissue>;
+    suite?: number;
+};
+export type ForkRepairResult = {
+    status: 'rotated';
+    version: number;
+} | {
+    status: 'not-needed' | 'pending';
+};
+export type KeyStatus = {
+    state: 'unlocked' | 'available' | 'unopenable';
+} | {
+    state: 'locked';
+    unlockOptions: Array<Array<SecretFactorKind>>;
+};
+type CommonParams = {
+    store: VaultStoreAPI;
+    principal: string;
+    identity: UnwrapParams['identity'];
+    runtime: WrapParams['runtime'];
+    authority: CredentialAuthority;
+    nextHLC(): Promise<string>;
+    methods?: WrapParams['methods'];
+    cache?: KeyCacheParams;
+    pinThrottle?: PinThrottleParams;
+};
+export type VaultCoordinatorParams = CommonParams & ({
+    mode: 'local';
+} | {
+    mode: 'replicated';
+    signer: SigningIdentity;
+    records: Omit<VaultRecordsParams, 'store' | 'authority'>;
+});
+export type VaultCoordinator = {
+    /** Replicated mode only. Receipt remains subject to the records authority callback. */
+    get records(): VaultRecords;
+    createKey(params: CreateKeyParams): Promise<KeyAddress>;
+    openKey(params: OpenKeyParams): Promise<OpenedKey>;
+    unlock(params: OpenKeyParams): Promise<void>;
+    lock(address: KeyAddress & CoordinatorCall): Promise<void>;
+    lockAll(ownerDID: string, call?: CoordinatorCall): Promise<void>;
+    status(params: OpenKeyParams): Promise<KeyStatus>;
+    listKeys(ownerDID: string, call?: CoordinatorCall): Promise<Array<KeyRow>>;
+    setKeyState(params: KeyAddress & CoordinatorCall & Pick<KeyRow, 'state'>): Promise<void>;
+    deleteKey(params: KeyAddress & CoordinatorCall): Promise<void>;
+    grant(params: OpenKeyParams & {
+        recipientDID: string;
+    }): Promise<void>;
+    addFactor(params: OpenKeyParams & {
+        factor: FactorInput;
+    }): Promise<void>;
+    removeFactor(params: OpenKeyParams & {
+        kind: string;
+    }): Promise<void>;
+    rotate(params: RotateKeyParams): Promise<number>;
+    repairFork(params: RotateKeyParams): Promise<ForkRepairResult>;
+    putEntry(params: EntryWriteParams): Promise<EntryAddress>;
+    updateEntry(params: EntryUpdateParams): Promise<void>;
+    updateEntryIfPresent(params: EntryUpdateParams): Promise<'updated' | 'absent'>;
+    updateEntryIfUnchanged(params: EntryUpdateParams & {
+        expectedHLC: string;
+    }): Promise<UpdateEntryResult>;
+    readEntry(params: EntryAddress & CoordinatorCall & {
+        inputs?: FactorInputs;
+    }): Promise<Uint8Array>;
+    getEntry(params: EntryAddress & CoordinatorCall): Promise<EntryRow | undefined>;
+    listEntries(params: EntryFilter & CoordinatorCall): Promise<Array<EntryRow>>;
+    deleteEntry(params: EntryAddress & CoordinatorCall): Promise<void>;
+    reKeyEntry(params: EntryAddress & CoordinatorCall & {
+        toKeyID: string;
+        inputs?: FactorInputs;
+    }): Promise<void>;
+    reendorse(params: KeyAddress & CoordinatorCall & {
+        records: ReadonlyArray<SignedRecord>;
+    }): Promise<void>;
+};
+export {};

package/lib/coordinator-types.js

@@ -0,0 +1 @@
+export { };

package/lib/coordinator.d.ts

@@ -0,0 +1,2 @@
+import type { VaultCoordinator, VaultCoordinatorParams } from './coordinator-types.js';
+export declare function createVaultCoordinator(params: VaultCoordinatorParams): VaultCoordinator;