@kubun/credential 0.17.4 → 0.18.0

package/lib/manager-open.js

@@ -0,0 +1,421 @@
+import { normalizeDID } from '@kokuin/token';
+import { AmbiguousCredentialWrapping, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialNotFound, CredentialRepairPending, CredentialSecretRejected, CredentialTampered, CredentialUnopenable, NoAvailableFactor, UnsupportedCredentialSuite } from './errors.js';
+import { isSecretFactorKind } from './manager-context.js';
+import { getSuite, isSupportedSuite } from './suite.js';
+export function createOpenFunctions(ctx, internals) {
+    const { store, identity, runtime, authority, decrypting, cache, state, ensureFloored, nextHLC } = ctx;
+    const { winningBranch, putRecord, putWrappingRecord, suiteForVersion } = internals.records;
+    // Input-bearing opens (a supplied pin/passphrase) never dedup: their outcome
+    // and the PIN throttle are caller-specific, so one caller's attempt must not
+    // stand in for another's.
+    const hasSuppliedInputs = (inputs)=>inputs != null && Object.values(inputs).some((value)=>value != null);
+    async function isSelfRevoked(keyID) {
+        const self = normalizeDID(identity.id);
+        const revoked = (await store.listRevocations(keyID)).some((revocation)=>normalizeDID(revocation.recipient_did) === self);
+        if (revoked) cache.evict(keyID);
+        return revoked;
+    }
+    /**
+   * Whether this device could ever satisfy a wrapping, given the chance to
+   * prompt.
+   *
+   * This is what separates "locked" from "unopenable", and the two need opposite
+   * responses from a caller. `recipient` is normalized at the comparison and
+   * never at the write: it is a key-resolution input stored in peer:4 long form,
+   * and folding it would make the wrapping unopenable.
+   */ function satisfiableFactors(descriptors) {
+        const needed = [];
+        for (const descriptor of descriptors){
+            if (isSecretFactorKind(descriptor.kind)) {
+                needed.push(descriptor.kind);
+                continue;
+            }
+            if (descriptor.kind !== 'did') {
+                return null;
+            }
+            const recipient = descriptor.params.recipient;
+            if (decrypting == null || typeof recipient !== 'string') {
+                return null;
+            }
+            if (normalizeDID(recipient) !== normalizeDID(identity.id)) {
+                return null;
+            }
+        }
+        return needed;
+    }
+    /**
+   * The wrapping this device holds by its own `did`.
+   *
+   * Not found by `recipient_did`: that column is populated only for the
+   * single-`did` headless default, so a `[did, pin]` wrapping has it null. The
+   * descriptors are the authority. More than one match throws rather than
+   * picking — silently re-wrapping the wrong row would leave the other one
+   * un-gated and look like success.
+   */ async function ownWrapping(keyID, keyVersion) {
+        const wrappings = await store.listWrappings(keyID, keyVersion);
+        const mine = wrappings.filter((wrapping)=>satisfiableFactors(wrapping.factors) != null && wrapping.factors.some((descriptor)=>descriptor.kind === 'did' && typeof descriptor.params.recipient === 'string' && normalizeDID(descriptor.params.recipient) === normalizeDID(identity.id)));
+        if (mine.length === 0) {
+            throw new CredentialNotFound('Credential wrapping for this device on key', keyID);
+        }
+        if (mine.length > 1) {
+            throw new AmbiguousCredentialWrapping(keyID, mine.length);
+        }
+        return mine[0];
+    }
+    /**
+   * Rebuild wrap-time inputs from stored descriptors.
+   *
+   * A `did` descriptor carries its recipient, so it reconstructs itself. A
+   * secret one carries a salt and a cost but never the secret, so the caller has
+   * to supply it again — the new wrapping's key is derived from every surviving
+   * factor, not only the one being changed.
+   */ function factorsFromDescriptors(descriptors, inputs) {
+        return descriptors.map((descriptor)=>{
+            if (descriptor.kind === 'did') {
+                const recipient = descriptor.params.recipient;
+                if (typeof recipient !== 'string') {
+                    throw new CredentialTampered('did factor descriptor carries no recipient');
+                }
+                return {
+                    kind: 'did',
+                    recipientDID: recipient
+                };
+            }
+            if (!isSecretFactorKind(descriptor.kind)) {
+                throw new NoAvailableFactor(descriptor.kind);
+            }
+            const input = inputs?.[descriptor.kind];
+            if (input == null) {
+                throw new NoAvailableFactor(descriptor.kind);
+            }
+            const { m, t, p } = descriptor.params;
+            // The cost travels with the factor: re-wrapping is not the moment to
+            // silently reset a wrapping that was deliberately made expensive.
+            const cost = typeof m === 'number' && typeof t === 'number' && typeof p === 'number' ? {
+                m,
+                t,
+                p
+            } : undefined;
+            return {
+                kind: descriptor.kind,
+                input,
+                cost
+            };
+        });
+    }
+    /**
+   * Re-wrap this device's own wrapping under a new factor list.
+   *
+   * The new row and old tombstone commit together under the key lock. Their
+   * order also keeps the old wrapping available until the new one is stored.
+   */ async function rewrapOwn({ keyID, inputs, change, methods, authority: recordAuthority = authority }) {
+        await ensureFloored();
+        const key = await loadKey(keyID);
+        const existing = await ownWrapping(keyID, key.version);
+        const { contentKey, branchID } = await openKey(keyID, inputs);
+        const suite = getSuite(key.suite);
+        const wrappingID = runtime.getRandomID();
+        // `contentKey` is our own private clone from the cache; zero it once its use — this
+        // rewrap — is done, on success or throw. The `try` opens right after the
+        // acquisition so the caller-supplied `change` throwing also cannot leak it.
+        let wrapped;
+        try {
+            const factors = change(factorsFromDescriptors(existing.factors, inputs));
+            wrapped = await suite.wrap({
+                runtime,
+                contentKey,
+                factors,
+                wrappingID,
+                keyID,
+                keyVersion: key.version,
+                methods
+            });
+        } finally{
+            contentKey.fill(0);
+        }
+        const { descriptors, iv, wrappedKey } = wrapped;
+        const replacement = {
+            wrappingID,
+            keyID,
+            keyVersion: key.version,
+            factors: descriptors,
+            iv,
+            wrappedKey,
+            recipientDID: existing.recipient_did
+        };
+        const written = await store.transaction(async (tx)=>{
+            await tx.lockKeyRow(keyID);
+            const current = await tx.getKey(keyID);
+            if (current == null) throw new CredentialNotFound('Credential key', keyID);
+            const currentWrapping = (await tx.listWrappings(keyID, key.version)).find((wrapping)=>wrapping.wrapping_id === existing.wrapping_id);
+            if (current.version !== key.version || JSON.stringify(currentWrapping) !== JSON.stringify(existing)) {
+                return false;
+            }
+            await putWrappingRecord({
+                wrapping: replacement,
+                owner: key.owner_did,
+                branchID,
+                authority: recordAuthority,
+                target: tx
+            });
+            await putRecord({
+                type: 'credential.wrapping',
+                id: existing.wrapping_id,
+                owner: key.owner_did,
+                hlc: await nextHLC(),
+                payload: null,
+                meta: {
+                    keyID,
+                    keyVersion: existing.key_version,
+                    recipient: existing.recipient_did
+                },
+                target: tx,
+                authority: recordAuthority
+            });
+            return true;
+        });
+        if (!written) await rewrapOwn({
+            keyID,
+            inputs,
+            change,
+            methods,
+            authority: recordAuthority
+        });
+    }
+    async function loadKey(keyID, atVersion) {
+        const key = await store.getKey(keyID);
+        if (key == null) {
+            throw new CredentialNotFound('Credential key', keyID);
+        }
+        if (!isSupportedSuite(key.suite) && (atVersion === undefined || atVersion === key.version)) {
+            throw new UnsupportedCredentialSuite(key.suite);
+        }
+        return key;
+    }
+    /**
+   * Recover a key's content key by trying its wrappings.
+   *
+   * The wrappings are an OR: any one opening is enough. If none opens, which
+   * failure this is depends on whether any of them COULD have opened with input
+   * this device is able to ask for — locked and unopenable are the same event
+   * with opposite remedies.
+   */ /**
+   * Recover a key's content key. Wrapped by `openKey`, which adds the input-free
+   * dedup; this is the actual open. Captures the lock generation and epoch at
+   * entry so a `lock`/`lockAll` that lands before the terminal `cache.set` can
+   * suppress it — the key is still returned to this caller, but the cache is not
+   * re-warmed behind a lock.
+   */ async function doOpenKey({ keyID, inputs, genAtStart, epochAtStart, atVersion }) {
+        // `genAtStart`/`epochAtStart` are captured by `openKey` at the moment the
+        // caller entered — before any dedup wait — so a lock that lands while a
+        // waiter is queued still suppresses that waiter's eventual re-warm.
+        const lockedSince = ()=>(state.keyGeneration.get(keyID) ?? 0) !== genAtStart || state.lockAllEpoch !== epochAtStart;
+        const key = await loadKey(keyID, atVersion);
+        const version = atVersion ?? key.version;
+        if (version > key.version) {
+            throw new CredentialKeyVersionMismatch(keyID, version, key.version);
+        }
+        if (await isSelfRevoked(keyID)) {
+            throw new CredentialUnopenable(keyID, 'recipient revoked');
+        }
+        const branchRows = await store.listKeyBranches(keyID, version);
+        const proven = new Set(branchRows.map((branch)=>branch.branch_id));
+        const winner = proven.size >= 2 ? await winningBranch(branchRows) : null;
+        const cached = cache.get(keyID, version);
+        if (cached != null) {
+            if (winner == null || cached.branchID === winner) {
+                return {
+                    contentKey: cached.contentKey,
+                    version,
+                    branchID: cached.branchID
+                };
+            }
+            // A fork-losing hit: `cached.contentKey` is our private clone that
+            // we are about to discard for a re-unwrap, so zero it rather than orphan it.
+            cached.contentKey.fill(0);
+            cache.evictVersion(keyID, version);
+        }
+        const suite = getSuite(await suiteForVersion(keyID, version, key.suite));
+        const wrappings = await store.listWrappingsWithBranch(keyID, version);
+        if (wrappings.length === 0) {
+            throw new CredentialUnopenable(keyID, `no wrapping at version ${version}`);
+        }
+        // Concurrent rotations leave two content-key branches under one version. The
+        // labels a keyless party could already partition by resolve, here, which one
+        // this device opens — so every device converges on the same branch instead
+        // of the first-listed wrapping, which is order-dependent and diverges. An
+        // empty label is branch-agnostic (legacy/non-rotation state), not a branch of
+        // its own, so it never counts toward a fork.
+        // A label no key-op vouches for cannot be allowed to win or to open.
+        const eligible = wrappings.filter((wrapping)=>wrapping.branch_id === '' || proven.has(wrapping.branch_id));
+        // No fork: try every wrapping in listed order, unchanged. Fork: only the
+        // winner-labelled wrappings, with empty-label ones as a last-resort fallback
+        // — a loser-labelled wrapping opens the wrong content key and is skipped.
+        const toTry = winner == null ? eligible : [
+            ...eligible.filter((wrapping)=>wrapping.branch_id === winner),
+            ...eligible.filter((wrapping)=>wrapping.branch_id === '')
+        ];
+        const reasons = [];
+        const promptable = new Set();
+        let rejected = null;
+        for (const wrapping of toTry){
+            const satisfiable = satisfiableFactors(wrapping.factors);
+            if (satisfiable == null) {
+                reasons.push(`wrapping ${wrapping.wrapping_id}: not addressed to this device`);
+                continue;
+            }
+            try {
+                const contentKey = await suite.unwrap({
+                    identity: decrypting,
+                    descriptors: wrapping.factors,
+                    inputs,
+                    iv: new Uint8Array(wrapping.iv),
+                    wrappedKey: new Uint8Array(wrapping.wrapped_key),
+                    wrappingID: wrapping.wrapping_id,
+                    keyID,
+                    keyVersion: wrapping.key_version
+                });
+                // In a fork every device names the same winner keylessly, so caching the
+                // winner as the resolved branch converges post-fork writes even when an
+                // empty-label fallback wrapping is what actually opened.
+                const branchID = winner ?? wrapping.branch_id;
+                // Suppress the re-warm if a lock landed while we were unwrapping: the
+                // caller still gets its key, but the cache stays cleared.
+                if (!lockedSince()) {
+                    cache.set(keyID, contentKey, version, branchID);
+                }
+                return {
+                    contentKey,
+                    version,
+                    branchID
+                };
+            } catch (error) {
+                reasons.push(error instanceof Error ? error.message : String(error));
+                if (error instanceof CredentialSecretRejected) {
+                    rejected = error;
+                }
+                for (const kind of satisfiable){
+                    promptable.add(kind);
+                }
+            }
+        }
+        // A secret WAS given and was wrong. Distinct from the case below, and it has
+        // to survive: a caller retries on one and prompts on the other, and the PIN
+        // throttle only counts an attempt that was actually made.
+        if (rejected != null) {
+            throw rejected;
+        }
+        // A wrapping this device is addressed by, that failed only for want of a
+        // secret nobody was asked for, is a prompt — not a dead end.
+        if (promptable.size > 0) {
+            throw new CredentialKeyLocked(keyID, [
+                ...promptable
+            ]);
+        }
+        if (winner !== null && eligible.some((wrapping)=>wrapping.branch_id !== winner && satisfiableFactors(wrapping.factors) !== null)) {
+            throw new CredentialRepairPending(keyID);
+        }
+        throw new CredentialUnopenable(keyID, reasons.join('; '));
+    }
+    /**
+   * Open a key, collapsing concurrent input-free opens of the same key into one
+   * unwrap. A waiter shares only the fact that an open ran, then takes its own
+   * clone from the cache; on a miss — the leader hit a lock and skipped its set,
+   * or failed — it falls through to its own open. Input-bearing opens never join
+   * the herd (see `hasSuppliedInputs`).
+   */ async function openKey(keyID, inputs, atVersion) {
+        // Captured once, at entry, so a lock landing while this call is queued behind
+        // another open still counts against it (see `doOpenKey`).
+        const genAtStart = state.keyGeneration.get(keyID) ?? 0;
+        const epochAtStart = state.lockAllEpoch;
+        if (hasSuppliedInputs(inputs)) {
+            return doOpenKey({
+                keyID,
+                inputs,
+                genAtStart,
+                epochAtStart,
+                atVersion
+            });
+        }
+        const flightID = atVersion === undefined ? keyID : `${keyID}:v${atVersion}`;
+        // Join any open already in flight for this key; on a miss, re-contend for
+        // leadership rather than opening in parallel — so post-miss opens (a leader
+        // that failed or was lock-suppressed) serialize into one leader at a time
+        // instead of re-forming the herd.
+        while(true){
+            const pending = state.inFlight.get(flightID);
+            if (pending == null) {
+                break;
+            }
+            await pending;
+            if (await isSelfRevoked(keyID)) {
+                throw new CredentialUnopenable(keyID, 'recipient revoked');
+            }
+            const version = atVersion ?? (await loadKey(keyID)).version;
+            const hit = cache.get(keyID, version);
+            if (hit != null) {
+                return {
+                    contentKey: hit.contentKey,
+                    version,
+                    branchID: hit.branchID
+                };
+            }
+        }
+        const run = doOpenKey({
+            keyID,
+            inputs,
+            genAtStart,
+            epochAtStart,
+            atVersion
+        });
+        // A gate that never rejects, so a waiter's `await pending` cannot throw the
+        // leader's error into the wrong caller; the waiter re-derives its own result
+        // from the cache (or its own open) after the gate settles.
+        const gate = run.then(()=>undefined, ()=>undefined);
+        state.inFlight.set(flightID, gate);
+        try {
+            return await run;
+        } finally{
+            // Only clear our own entry — a later leader may already have replaced it.
+            if (state.inFlight.get(flightID) === gate) {
+                state.inFlight.delete(flightID);
+            }
+        }
+    }
+    async function openSpecificBranch({ keyID, version, branchID, suiteID, inputs }) {
+        const suite = getSuite(suiteID);
+        for (const wrapping of (await store.listWrappingsWithBranch(keyID, version))){
+            const needed = satisfiableFactors(wrapping.factors);
+            if (wrapping.branch_id !== branchID || needed === null || needed.some((kind)=>inputs?.[kind] == null)) {
+                continue;
+            }
+            try {
+                return await suite.unwrap({
+                    identity: decrypting,
+                    descriptors: wrapping.factors,
+                    inputs,
+                    iv: new Uint8Array(wrapping.iv),
+                    wrappedKey: new Uint8Array(wrapping.wrapped_key),
+                    wrappingID: wrapping.wrapping_id,
+                    keyID,
+                    keyVersion: version
+                });
+            } catch  {
+            // Another recipient's wrapping or corrupt local material cannot open this branch.
+            }
+        }
+        return null;
+    }
+    return {
+        isSelfRevoked,
+        satisfiableFactors,
+        ownWrapping,
+        factorsFromDescriptors,
+        loadKey,
+        doOpenKey,
+        openKey,
+        openSpecificBranch,
+        rewrapOwn,
+        hasSuppliedInputs
+    };
+}

package/lib/manager-records.d.ts

@@ -0,0 +1,94 @@
+import { type SignedRecord } from '@kubun/records';
+import type { CredentialFactorDescriptor, CredentialRecordPayloads, CredentialRecordType, CredentialStoreAPI, PutCredentialKeyParams } from '@kubun/store-credential';
+import type { CredentialAuthority } from './authority.js';
+import type { ManagerContext } from './manager-context.js';
+import type { GrantEntryParams } from './manager-types.js';
+type PutRecordParams<T extends CredentialRecordType> = {
+    type: T;
+    id: string;
+    owner: string;
+    hlc: string;
+    payload: CredentialRecordPayloads[T] | null;
+    meta: Record<string, unknown>;
+    target?: CredentialStoreAPI;
+    authority?: CredentialAuthority;
+};
+type PutKeyRecordParams = {
+    key: PutCredentialKeyParams;
+    keyUnique: string;
+    hlc: string;
+    authority?: CredentialAuthority;
+    target?: CredentialStoreAPI;
+    repairDigest?: string;
+};
+type BranchRecordIDParams = {
+    keyID: string;
+    version: number;
+    branchID: string;
+    target?: CredentialStoreAPI;
+};
+type PutWrappingRecordParams = {
+    wrapping: {
+        wrappingID: string;
+        keyID: string;
+        keyVersion: number;
+        factors: Array<CredentialFactorDescriptor>;
+        iv: Uint8Array;
+        wrappedKey: Uint8Array;
+        recipientDID?: string | null;
+    };
+    owner: string;
+    branchID: string;
+    branchRecordID?: string;
+    authority?: CredentialAuthority;
+    target?: CredentialStoreAPI;
+};
+type PutEntryRecordParams = {
+    entry: {
+        entryID: string;
+        keyID: string;
+        keyVersion: number;
+        iv: Uint8Array;
+        ciphertext: Uint8Array;
+        hlc: string;
+    };
+    owner: string;
+    branchID: string;
+    contentHLC?: string;
+    target?: CredentialStoreAPI;
+    authority?: CredentialAuthority;
+    grant?: GrantEntryParams;
+};
+type EntryGrantInfo = {
+    grantDeviceDID: string;
+    grantName: string;
+    grantOwnerDID: string | undefined;
+};
+export type RecordFunctions = {
+    storedKeyRecord: (keyID: string) => Promise<SignedRecord | null>;
+    entryRecord: (entryID: string, target?: CredentialStoreAPI, ownerDID?: string) => Promise<SignedRecord | null>;
+    winningBranch: (branches: ReadonlyArray<{
+        branch_id: string;
+        op_jwt: string;
+    }>) => Promise<string | null>;
+    putRecord: <T extends CredentialRecordType>(args: PutRecordParams<T>) => Promise<SignedRecord & {
+        type: T;
+    }>;
+    keyRecord: (args: PutKeyRecordParams) => Promise<{
+        branchID: string;
+        branchRecordID: string;
+    }>;
+    keyUnique: (keyID: string) => Promise<string>;
+    branchRecordID: (args: BranchRecordIDParams) => Promise<string>;
+    putWrappingRecord: (args: PutWrappingRecordParams) => Promise<void>;
+    putEntryRecord: (args: PutEntryRecordParams) => Promise<void>;
+    entryGrant: (entryID: string, target?: CredentialStoreAPI, ownerDID?: string) => Promise<EntryGrantInfo | undefined>;
+    writableGrant: (entryID: string, ownerDID?: string) => Promise<EntryGrantInfo | undefined>;
+    branchProofs: (keyID: string, version: number) => Promise<Map<string, {
+        suite: number;
+        repairDigest?: string;
+    }>>;
+    suiteForVersion: (keyID: string, version: number, currentSuite: number) => Promise<number>;
+};
+export declare function createRecordFunctions(ctx: ManagerContext): RecordFunctions;
+export {};