@kokuin/store-vault 0.0.0-stage → 0.1.0

package/lib/coordinator-open.js

@@ -0,0 +1,141 @@
+import { createPinThrottle, getSuite, NoAvailableFactor, satisfiableFactors, VaultPinRejected, VaultSecretRejected, VaultTampered, vaultRevocationRecordID } from '@kokuin/vault';
+import { VaultKeyLocked, VaultNotFound, VaultRepairPending, VaultSupersededBranch } from './coordinator-context.js';
+import { settledValue } from './settle.js';
+export function createOpenFunctions(ctx) {
+    const { params, cache, cacheID } = ctx;
+    const throttle = createPinThrottle(params.pinThrottle);
+    const inFlight = new Map();
+    async function revoked(address, store) {
+        if (params.mode !== 'replicated') return false;
+        const denied = await ctx.recordsFor(store).listRevocations(address);
+        const own = vaultRevocationRecordID(address.keyID, params.principal);
+        return denied.some((did)=>vaultRevocationRecordID(address.keyID, did) === own);
+    }
+    async function doOpen(address, store, generation, specific) {
+        // Both reads run together. Their results are checked in the old order: key, version, revocation.
+        const [keyRead, revokedRead] = await Promise.allSettled([
+            ctx.key(address, store),
+            revoked(address, store)
+        ]);
+        const key = settledValue(keyRead);
+        const version = address.atVersion ?? key.version;
+        if (version > key.version || version < 1) throw new VaultNotFound();
+        if (settledValue(revokedRead)) {
+            ctx.evict(address);
+            throw new VaultNotFound();
+        }
+        const branch = await ctx.branch(address, version, store, specific);
+        const supplied = Object.values(address.inputs ?? {}).some((input)=>input !== undefined);
+        if (!supplied) {
+            const hit = cache.get(cacheID(address), version);
+            if (hit !== null) {
+                if (hit.branchID === branch.branchID) return {
+                    ...hit,
+                    version,
+                    suite: branch.suite
+                };
+                hit.contentKey.fill(0);
+                cache.evictVersion(cacheID(address), version);
+            }
+        }
+        const wrappings = await store.listWrappings({
+            ...address,
+            keyVersion: version
+        });
+        let rejected;
+        let locked = false;
+        for (const row of wrappings){
+            if (params.mode === 'replicated' && row.provenance !== branch.branchID) continue;
+            const needed = satisfiableFactors(row.descriptors, params.identity);
+            if (needed === null) continue;
+            const evidence = await ctx.wrappingEvidence(row, store);
+            const expectedDescriptorDigest = evidence?.expectedDescriptorDigest;
+            try {
+                const contentKey = await getSuite(branch.suite).unwrap({
+                    ...row,
+                    identity: params.identity,
+                    inputs: address.inputs,
+                    expectedDescriptorDigest
+                });
+                if (ctx.generation(address) === generation && specific === undefined) cache.set(cacheID(address), contentKey, version, branch.branchID);
+                return {
+                    contentKey,
+                    version,
+                    suite: branch.suite,
+                    branchID: branch.branchID
+                };
+            } catch (error) {
+                if (error instanceof VaultTampered) throw error;
+                if (error instanceof VaultSecretRejected) rejected = error;
+                else if (error instanceof NoAvailableFactor && needed.length > 0) locked = true;
+                else throw error;
+            }
+        }
+        if (rejected !== undefined) throw rejected;
+        if (locked) throw new VaultKeyLocked();
+        if (params.mode === 'replicated' && wrappings.some((w)=>{
+            return w.provenance !== branch.branchID && satisfiableFactors(w.descriptors, params.identity) !== null;
+        })) throw new VaultRepairPending();
+        throw new VaultNotFound();
+    }
+    async function open(address, store = params.store, specific) {
+        const generation = ctx.generation(address);
+        if (address.inputs?.pin !== undefined) {
+            const id = cacheID(address);
+            const rejected = (cause)=>{
+                return new VaultPinRejected(address.keyID, {
+                    cause,
+                    attemptsRemaining: throttle.attemptsRemaining(id),
+                    retryAfter: throttle.retryAfter(id)
+                });
+            };
+            if (throttle.retryAfter(id) > 0) throw rejected();
+            try {
+                const opened = await doOpen(address, store, generation, specific);
+                throttle.recordSuccess(id);
+                return opened;
+            } catch (error) {
+                if (error instanceof VaultSecretRejected) {
+                    throttle.recordFailure(id);
+                    throw rejected(error);
+                }
+                throw error;
+            }
+        }
+        if (specific !== undefined || Object.values(address.inputs ?? {}).some((input)=>input !== undefined) || store !== params.store) return doOpen(address, store, generation, specific);
+        const flightID = JSON.stringify([
+            cacheID(address),
+            address.atVersion
+        ]);
+        while(inFlight.has(flightID))await inFlight.get(flightID);
+        const run = doOpen(address, store, generation);
+        const gate = run.then(()=>{}, ()=>{});
+        inFlight.set(flightID, gate);
+        try {
+            return await run;
+        } finally{
+            if (inFlight.get(flightID) === gate) inFlight.delete(flightID);
+        }
+    }
+    async function decrypt(row, address, store = params.store, specific = false) {
+        if (row === undefined) throw new VaultNotFound();
+        const opened = await open({
+            ...address,
+            atVersion: row.keyVersion
+        }, store, specific ? row.provenance : undefined);
+        try {
+            if (params.mode === 'replicated' && row.provenance !== opened.branchID) throw new VaultSupersededBranch();
+            return getSuite(opened.suite).decryptEntry({
+                ...row,
+                contentKey: opened.contentKey
+            });
+        } finally{
+            opened.contentKey.fill(0);
+        }
+    }
+    return {
+        open,
+        decrypt,
+        revoked
+    };
+}

package/lib/coordinator-records.d.ts

@@ -0,0 +1,27 @@
+import type { SignedRecord } from '@kokuin/records';
+import type { CoordinatorContext } from './coordinator-context.js';
+import type { CoordinatorCall } from './coordinator-types.js';
+import type { EntryRow, VaultStoreAPI, WrappingRow } from './types.js';
+type Branch = {
+    branchID: string;
+    branchRecordID: string;
+};
+export type EntryInfo = {
+    contentHLC: string;
+    consumer: unknown;
+};
+export type RecordFunctions = {
+    /** Signs at `hlc` when given, or at a newly allocated one. */
+    wrapping(row: WrappingRow, branch: Branch, consumer?: unknown, hlc?: string): Promise<SignedRecord>;
+    entry(row: EntryRow, branch: Branch, contentHLC: string, consumer?: unknown, deleted?: boolean): Promise<SignedRecord>;
+    entryInfo(row: EntryRow, store: VaultStoreAPI): Promise<EntryInfo>;
+    /** Batched {@link entryInfo}: one record read, results and the first failure in row order. */
+    entryInfos(rows: ReadonlyArray<EntryRow>, store: VaultStoreAPI): Promise<Array<EntryInfo>>;
+    reendorse(request: {
+        ownerDID: string;
+        keyID: string;
+        records: ReadonlyArray<SignedRecord>;
+    } & CoordinatorCall): Promise<void>;
+};
+export declare function createRecordFunctions(ctx: CoordinatorContext): RecordFunctions;
+export {};

package/lib/coordinator-records.js

@@ -0,0 +1,132 @@
+import { getRecordDecisions, recordKeyText, recordPayloadDigest, signRecordOp } from '@kokuin/records';
+import { encodeVaultRecordPayload, VaultTampered } from '@kokuin/vault';
+import { VaultNotFound } from './coordinator-context.js';
+import { settleAll, settledValue } from './settle.js';
+export function createRecordFunctions(ctx) {
+    async function wrapping(row, branch, consumer = null, hlc) {
+        return ctx.signed('vault.wrapping', {
+            ownerDID: row.ownerDID,
+            id: row.wrappingID
+        }, row, {
+            keyID: row.keyID,
+            keyVersion: row.keyVersion,
+            branchID: branch.branchID,
+            branchRecordID: branch.branchRecordID,
+            recipient: row.recipientDID,
+            consumer
+        }, hlc);
+    }
+    async function entry(row, branch, contentHLC, consumer = null, deleted = false) {
+        return ctx.signed('vault.entry', {
+            ownerDID: row.ownerDID,
+            id: row.entryID
+        }, deleted ? null : row, {
+            keyID: row.keyID,
+            keyVersion: row.keyVersion,
+            branchID: branch.branchID,
+            branchRecordID: branch.branchRecordID,
+            contentHLC,
+            consumer,
+            ...deleted ? {} : {
+                kind: row.kind,
+                label: row.label,
+                attributes: row.attributes
+            }
+        }, row.hlc);
+    }
+    function checkEntry(row, op) {
+        const meta = op.claim.meta;
+        const attributes = meta.attributes;
+        if (op.claim.deleted || op.claim.hlc !== row.hlc || meta.keyID !== row.keyID || meta.keyVersion !== row.keyVersion || meta.branchID !== row.provenance || meta.kind !== row.kind || meta.label !== row.label || attributes === null || typeof attributes !== 'object' || Array.isArray(attributes) || Object.keys(attributes).length !== Object.keys(row.attributes).length || Object.entries(attributes).some(([name, value])=>row.attributes[name] !== value) || recordPayloadDigest(encodeVaultRecordPayload('vault.entry', row)) !== op.claim.payloadDigest) throw new VaultTampered('Entry projection disagrees with authenticated content');
+        const contentHLC = op.claim.meta.contentHLC;
+        if (typeof contentHLC !== 'string') throw new VaultNotFound();
+        return {
+            contentHLC,
+            consumer: op.claim.meta.consumer
+        };
+    }
+    async function entryInfo(row, store) {
+        if (ctx.params.mode === 'local') return {
+            contentHLC: row.hlc,
+            consumer: null
+        };
+        const { op } = await ctx.stored({
+            type: 'vault.entry',
+            owner: row.ownerDID,
+            id: row.entryID
+        }, store);
+        return checkEntry(row, op);
+    }
+    async function entryInfos(rows, store) {
+        if (ctx.params.mode === 'local') return rows.map((row)=>({
+                contentHLC: row.hlc,
+                consumer: null
+            }));
+        const evidence = await ctx.storedMany(rows.map((row)=>({
+                type: 'vault.entry',
+                owner: row.ownerDID,
+                id: row.entryID
+            })), store);
+        return rows.map((row, index)=>{
+            const item = evidence[index];
+            if (item === undefined) throw new VaultNotFound();
+            return checkEntry(row, item.op);
+        });
+    }
+    async function reendorse(request) {
+        await ctx.authorize('reendorse', 'administer', request);
+        if (ctx.params.mode !== 'replicated') throw new TypeError('Re-endorsement requires replicated mode');
+        const params = ctx.params;
+        await ctx.locked([
+            request
+        ], async (tx)=>{
+            const decisionsRead = getRecordDecisions(ctx.recordsFor(tx).adapter, request.records);
+            // A task that fails before reading the decisions must not leave this rejection unhandled.
+            decisionsRead.catch(()=>{});
+            const keyRead = tx.getKey(request);
+            const branchesRead = keyRead.then((key)=>ctx.branches(request, key?.version ?? 0, tx));
+            // All reads run together. Results are checked in the old order: key, then each record,
+            // then, after signing, the branches.
+            const [keyResult, opsResult, branchesResult] = await Promise.allSettled([
+                keyRead,
+                settleAll(request.records.map(async (record)=>{
+                    const op = await ctx.verified(record);
+                    if (op.claim.owner !== request.ownerDID || op.claim.meta.keyID !== request.keyID) throw new TypeError('Re-endorsement is confined to the explicitly named key');
+                    const decision = (await decisionsRead).get(recordKeyText(record));
+                    if (!decision?.copies.some((copy)=>copy.opHash === record.opHash)) throw new VaultNotFound();
+                    return op;
+                })),
+                branchesRead
+            ]);
+            const key = settledValue(keyResult);
+            const ops = settledValue(opsResult);
+            const output = [];
+            // Signing stays sequential: signer calls follow the caller's record order, and a failure
+            // stops the rest.
+            for (const [index, record] of request.records.entries()){
+                const op = ops[index];
+                if (op === undefined) throw new VaultNotFound();
+                // Re-sign the entire original claim. Consumer evidence and content intent stay authenticated.
+                output.push({
+                    ...record,
+                    ...await signRecordOp(params.signer, op.claim, params.records.opKind)
+                });
+            }
+            const branches = settledValue(branchesResult);
+            await ctx.write(tx, output, {
+                key: {
+                    ...request,
+                    expectedVersion: key?.version ?? null,
+                    expectedBranches: branches.map((b)=>b.branchID)
+                }
+            }, request);
+        });
+    }
+    return {
+        wrapping,
+        entry,
+        entryInfo,
+        entryInfos,
+        reendorse
+    };
+}

package/lib/coordinator-rotate.d.ts

@@ -0,0 +1,9 @@
+import type { CoordinatorContext } from './coordinator-context.js';
+import type { OpenFunctions } from './coordinator-open.js';
+import type { RecordFunctions } from './coordinator-records.js';
+import type { ForkRepairResult, RotateKeyParams } from './coordinator-types.js';
+export type RotateFunctions = {
+    rotate(request: RotateKeyParams): Promise<number>;
+    repairFork(request: RotateKeyParams): Promise<ForkRepairResult>;
+};
+export declare function createRotateFunctions(ctx: CoordinatorContext, open: OpenFunctions, records: RecordFunctions): RotateFunctions;