@kubun/credential 0.17.3 → 0.18.0

package/lib/manager-keys.js

@@ -0,0 +1,413 @@
+import { normalizeDID } from '@kokuin/token';
+import { buildCredentialKey } from './builder.js';
+import { CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialRecipientRevoked, CredentialSecretRejected, InvalidCredentialFactors, NoAvailableFactor } from './errors.js';
+import { SECRET_FACTOR_KINDS } from './manager-context.js';
+import { getSuite, isSupportedSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
+import { wrappableDID } from './wrappable.js';
+export function createKeyMethods(ctx, internals) {
+    const { store, identity, runtime, authority, decrypting, cache, throttle, state, ensureFloored, nextHLC } = ctx;
+    const { putRecord, keyRecord, keyUnique, putWrappingRecord } = internals.records;
+    const { isSelfRevoked, satisfiableFactors, loadKey, openKey, rewrapOwn } = internals.open;
+    const { checkRemovalRecovery } = internals.removalRecovery;
+    const { rotateKey } = internals.rotate;
+    return {
+        availableFactors () {
+            // A passphrase or pin needs no key material, only someone to ask. They are
+            // available on every device, including one that cannot decrypt at all.
+            return decrypting == null ? [
+                ...SECRET_FACTOR_KINDS
+            ] : [
+                'did',
+                ...SECRET_FACTOR_KINDS
+            ];
+        },
+        async unlock (keyID, inputs) {
+            if (inputs?.pin == null) {
+                // Unlock only warms the cache; the returned clone is ours to zero.
+                ;
+                (await openKey(keyID, inputs)).contentKey.fill(0);
+                return;
+            }
+            // Refused BEFORE `openKey`, so a throttled attempt never reaches Argon2.
+            // Below the KDF the 340ms is paid either way and the counter buys the
+            // defender nothing it does not also cost.
+            const wait = throttle.retryAfter(keyID);
+            if (wait > 0) {
+                throw new CredentialPinRejected(keyID, {
+                    attemptsRemaining: throttle.attemptsRemaining(keyID),
+                    retryAfter: wait
+                });
+            }
+            try {
+                ;
+                (await openKey(keyID, inputs)).contentKey.fill(0);
+            } catch (error) {
+                // Only a rejected secret advances the counter. A key that is simply not
+                // addressed to this device, or whose suite is unknown, is not someone
+                // guessing — counting it would lock a user out over a fault.
+                if (error instanceof CredentialSecretRejected) {
+                    throttle.recordFailure(keyID);
+                    throw new CredentialPinRejected(keyID, {
+                        cause: error,
+                        attemptsRemaining: throttle.attemptsRemaining(keyID),
+                        retryAfter: throttle.retryAfter(keyID)
+                    });
+                }
+                throw error;
+            }
+            throttle.recordSuccess(keyID);
+        },
+        async addFactor (keyID, factor, params) {
+            await checkRemovalRecovery();
+            // Ownership, not possession of a wrapping. A rotation has to re-make every
+            // retained wrapping at the new version, and a secret factor cannot be
+            // re-made without its secret — so a recipient gating its own wrapping of
+            // someone else's key would make that key un-rotatable, and revocation is
+            // rotation.
+            //
+            // Asked for the verb rather than only for the secret kinds: a `did` added
+            // to a foreign wrapping re-makes unattended, but it is still a change to a
+            // key this identity does not administer, and the narrower rule buys the
+            // caller nothing it could use.
+            const key = await loadKey(keyID);
+            if (!await (params?.authority ?? authority).authorize('administer', {
+                key,
+                store
+            })) {
+                throw new CredentialNotAuthorized('administer', keyID);
+            }
+            await rewrapOwn({
+                keyID,
+                inputs: params?.inputs,
+                change: (factors)=>[
+                        ...factors,
+                        factor
+                    ],
+                methods: params?.methods,
+                authority: params?.authority ?? authority
+            });
+        },
+        async removeFactor (keyID, kind, params) {
+            await checkRemovalRecovery();
+            // Dropping a factor (a pin, say) weakens the key exactly as adding one
+            // strengthens it, so it is administration too — see `addFactor`.
+            const key = await loadKey(keyID);
+            if (!await (params?.authority ?? authority).authorize('administer', {
+                key,
+                store
+            })) {
+                throw new CredentialNotAuthorized('administer', keyID);
+            }
+            await rewrapOwn({
+                keyID,
+                inputs: params?.inputs,
+                change: (factors)=>{
+                    const remaining = factors.filter((factor)=>factor.kind !== kind);
+                    if (remaining.length === factors.length) {
+                        throw new CredentialNotFound(`Credential factor "${kind}" on this device's wrapping of`, keyID);
+                    }
+                    // Nothing here refuses a removal that would leave a pin without a did,
+                    // or nothing at all: `suite.wrap` validates the list it is given, so
+                    // the refusal happens once, where every path reaches it.
+                    return remaining;
+                },
+                methods: params?.methods,
+                authority: params?.authority ?? authority
+            });
+        },
+        lock (keyID) {
+            // Bump before evicting so an `openKey` already past its generation capture
+            // sees the change and skips its `cache.set`.
+            state.keyGeneration.set(keyID, (state.keyGeneration.get(keyID) ?? 0) + 1);
+            cache.evict(keyID);
+        },
+        lockAll () {
+            state.lockAllEpoch += 1;
+            cache.evictAll();
+        },
+        async status (keyID, version) {
+            const key = await store.getKey(keyID);
+            if (key == null) {
+                throw new CredentialNotFound('Credential key', keyID);
+            }
+            // Reported, not thrown. `loadKey` raises here, which would make the call
+            // that exists to say "this device cannot read that key" fail on exactly
+            // the key it was asked about.
+            if (!isSupportedSuite(key.suite)) {
+                return {
+                    state: 'unopenable',
+                    reason: 'unsupported-suite'
+                };
+            }
+            // Defaults to the key's current version; a caller checking a manifest
+            // target passes the expected version so a stale wrapping is never
+            // reported openable for a newer one, or vice versa.
+            const targetVersion = version ?? key.version;
+            if (await isSelfRevoked(keyID)) {
+                return {
+                    state: 'unopenable',
+                    reason: 'revoked'
+                };
+            }
+            if (cache.has(keyID, targetVersion)) {
+                return {
+                    state: 'unlocked'
+                };
+            }
+            const wrappings = await store.listWrappings(keyID, targetVersion);
+            if (wrappings.length === 0) {
+                return {
+                    state: 'unopenable',
+                    reason: 'no-wrapping'
+                };
+            }
+            const unlockOptions = [];
+            for (const wrapping of wrappings){
+                const satisfiable = satisfiableFactors(wrapping.factors);
+                if (satisfiable == null) {
+                    continue;
+                }
+                // Nothing to ask for: this one opens on the identity alone, so the key
+                // needs no interaction however many other wrappings do.
+                if (satisfiable.length === 0) {
+                    return {
+                        state: 'available'
+                    };
+                }
+                unlockOptions.push(satisfiable);
+            }
+            return unlockOptions.length > 0 ? {
+                state: 'locked',
+                unlockOptions
+            } : {
+                state: 'unopenable',
+                reason: 'not-addressed'
+            };
+        },
+        async createKey (createParams = {}) {
+            await checkRemovalRecovery();
+            const suiteID = createParams.suite ?? SUITE_KUBUN_CRED_1;
+            if (createParams.factors != null && createParams.wrappings != null) {
+                throw new InvalidCredentialFactors('pass either "factors" or "wrappings", not both');
+            }
+            // The headless default: one wrapping to this device's wrappable form. Taking
+            // it without a decrypting identity would mint a key whose only wrapping
+            // this device can never open, so it refuses here rather than at first read.
+            const explicit = createParams.wrappings ?? (createParams.factors && [
+                createParams.factors
+            ]);
+            const wrappings = explicit ?? [
+                [
+                    {
+                        kind: 'did',
+                        recipientDID: wrappableDID(identity)
+                    }
+                ]
+            ];
+            if (explicit == null && decrypting == null) {
+                throw new NoAvailableFactor('did');
+            }
+            const built = await buildCredentialKey({
+                runtime,
+                ownerDID: createParams.ownerDID ?? identity.id,
+                suite: suiteID,
+                wrappings,
+                methods: createParams.methods
+            });
+            // The wrappings already encapsulate the content key; createKey never reads
+            // `built.contentKey` again, so zero it rather than leave the generated
+            // secret live until collection.
+            built.contentKey.fill(0);
+            const keyParams = {
+                keyID: built.keyID,
+                ownerDID: built.ownerDID,
+                suite: built.suite,
+                version: built.version,
+                state: 'active'
+            };
+            await ensureFloored();
+            // The key-op opens the content-key branch every wrapping here joins, so
+            // its label is threaded onto them.
+            await store.transaction(async (tx)=>{
+                const { branchID, branchRecordID: branchIDRecord } = await keyRecord({
+                    key: keyParams,
+                    keyUnique: built.keyUnique,
+                    hlc: await nextHLC(),
+                    authority,
+                    target: tx
+                });
+                for (const wrapping of built.wrappings){
+                    await putWrappingRecord({
+                        wrapping,
+                        owner: built.ownerDID,
+                        branchID,
+                        branchRecordID: branchIDRecord,
+                        authority,
+                        target: tx
+                    });
+                }
+            });
+            return built.keyID;
+        },
+        async rotate (keyID, rotateParams) {
+            await checkRemovalRecovery();
+            return await rotateKey({
+                keyID,
+                rotateParams
+            });
+        },
+        async revoke (keyID, recipientDID, revokeParams) {
+            await checkRemovalRecovery();
+            const key = await loadKey(keyID);
+            const revocationAuthority = revokeParams?.authority ?? authority;
+            if (!await revocationAuthority.authorizeRevocation?.({
+                key,
+                store
+            }) && normalizeDID(key.owner_did) !== normalizeDID(identity.id)) {
+                throw new CredentialNotAuthorized('administer', keyID);
+            }
+            const revokedDID = normalizeDID(recipientDID);
+            if ((await store.listRevocations(keyID)).some((row)=>normalizeDID(row.recipient_did) === revokedDID)) {
+                return key.version;
+            }
+            const version = await rotateKey({
+                keyID,
+                rotateParams: revokeParams,
+                revokedDID
+            });
+            if (revokedDID === normalizeDID(identity.id)) cache.evict(keyID);
+            return version;
+        },
+        async grant (keyID, recipientWrappableDID, params) {
+            await checkRemovalRecovery();
+            await ensureFloored();
+            const key = await loadKey(keyID);
+            // Administration, and by a stronger argument than `rotate`'s: this hands
+            // the content key to a party that did not have it, which is the one change
+            // no later rotation can take back from whoever received it.
+            if (!await (params?.authority ?? authority).authorize('administer', {
+                key,
+                store
+            })) {
+                throw new CredentialNotAuthorized('administer', keyID);
+            }
+            // A repeat grant needs no key open or recipient resolution. Its answer is
+            // still taken under the same key lock as rotation.
+            const alreadyGranted = await store.transaction(async (tx)=>{
+                await tx.lockKeyRow(keyID);
+                const current = await tx.getKey(keyID);
+                if (current == null) throw new CredentialNotFound('Credential key', keyID);
+                if ((await tx.listRevocations(keyID)).some((row)=>normalizeDID(row.recipient_did) === normalizeDID(recipientWrappableDID))) {
+                    throw new CredentialRecipientRevoked(keyID, recipientWrappableDID);
+                }
+                const addressed = (await tx.listWrappings(keyID, current.version)).some((wrapping)=>wrapping.factors.some((descriptor)=>descriptor.kind === 'did' && typeof descriptor.params.recipient === 'string' && normalizeDID(descriptor.params.recipient) === normalizeDID(recipientWrappableDID)));
+                return addressed ? {
+                    version: current.version,
+                    created: false
+                } : null;
+            });
+            if (alreadyGranted != null) return alreadyGranted;
+            // The key open and recipient key resolution run outside the transaction.
+            // The locked read decides whether this speculative wrapping is still at
+            // the current version; if rotation committed meanwhile, prepare again.
+            for(;;){
+                const candidate = await loadKey(keyID);
+                const { contentKey, version, branchID } = await openKey(keyID);
+                const wrappingID = runtime.getRandomID();
+                let wrapped;
+                try {
+                    wrapped = await getSuite(candidate.suite).wrap({
+                        runtime,
+                        contentKey,
+                        factors: [
+                            {
+                                kind: 'did',
+                                recipientDID: recipientWrappableDID
+                            }
+                        ],
+                        wrappingID,
+                        keyID,
+                        keyVersion: version,
+                        methods: params?.methods
+                    });
+                } finally{
+                    contentKey.fill(0);
+                }
+                const result = await store.transaction(async (tx)=>{
+                    await tx.lockKeyRow(keyID);
+                    const current = await tx.getKey(keyID);
+                    if (current == null) throw new CredentialNotFound('Credential key', keyID);
+                    if ((await tx.listRevocations(keyID)).some((row)=>normalizeDID(row.recipient_did) === normalizeDID(recipientWrappableDID))) {
+                        throw new CredentialRecipientRevoked(keyID, recipientWrappableDID);
+                    }
+                    if (current.version !== version || current.suite !== candidate.suite) return null;
+                    const addressed = (await tx.listWrappings(keyID, version)).some((wrapping)=>wrapping.factors.some((descriptor)=>descriptor.kind === 'did' && typeof descriptor.params.recipient === 'string' && normalizeDID(descriptor.params.recipient) === normalizeDID(recipientWrappableDID)));
+                    if (addressed) return {
+                        version,
+                        created: false
+                    };
+                    await putWrappingRecord({
+                        wrapping: {
+                            wrappingID,
+                            keyID,
+                            keyVersion: version,
+                            factors: wrapped.descriptors,
+                            iv: wrapped.iv,
+                            wrappedKey: wrapped.wrappedKey,
+                            recipientDID: recipientWrappableDID
+                        },
+                        owner: current.owner_did,
+                        branchID,
+                        authority: params?.authority ?? authority,
+                        target: tx
+                    });
+                    return {
+                        version,
+                        created: true
+                    };
+                });
+                if (result != null) return result;
+            }
+        },
+        async listKeys () {
+            return (await store.listKeys(normalizeDID(identity.id))).map((key)=>key.key_id);
+        },
+        async countWrappings (keyID) {
+            const key = await store.getKey(keyID);
+            if (key == null) {
+                throw new CredentialNotFound('Credential key', keyID);
+            }
+            return (await store.listWrappings(keyID, key.version)).length;
+        },
+        async deleteKey (keyID) {
+            await checkRemovalRecovery();
+            for(;;){
+                const key = await store.getKey(keyID);
+                if (key == null) return;
+                const unique = await keyUnique(keyID);
+                const deletionHLC = await nextHLC();
+                const result = await store.transaction(async (tx)=>{
+                    await tx.lockKeyRow(keyID);
+                    const current = await tx.getKey(keyID);
+                    if (current == null) return 'done';
+                    if (current.version !== key.version) return 'retry';
+                    await putRecord({
+                        type: 'credential.key',
+                        id: keyID,
+                        owner: current.owner_did,
+                        hlc: deletionHLC,
+                        payload: null,
+                        meta: {
+                            keyID,
+                            keyUnique: unique,
+                            version: current.version
+                        },
+                        target: tx
+                    });
+                    return 'done';
+                });
+                if (result === 'done') return;
+            }
+        }
+    };
+}

package/lib/manager-open.d.ts

@@ -0,0 +1,45 @@
+import { type MethodRegistry } from '@kokuin/token';
+import type { CredentialFactorDescriptor, CredentialKey, CredentialWrappingWithBranch } from '@kubun/store-credential';
+import type { CredentialAuthority } from './authority.js';
+import { type ManagerContext, type ManagerInternals } from './manager-context.js';
+import { type FactorInput, type FactorInputs, type SecretFactorKind } from './suite.js';
+type RewrapOwnParams = {
+    keyID: string;
+    inputs?: FactorInputs;
+    change: (factors: Array<FactorInput>) => Array<FactorInput>;
+    methods?: MethodRegistry;
+    authority?: CredentialAuthority;
+};
+type DoOpenKeyParams = {
+    keyID: string;
+    inputs?: FactorInputs;
+    genAtStart: number;
+    epochAtStart: number;
+    atVersion?: number;
+};
+type OpenSpecificBranchParams = {
+    keyID: string;
+    version: number;
+    branchID: string;
+    suiteID: number;
+    inputs?: FactorInputs;
+};
+export type OpenFunctions = {
+    isSelfRevoked: (keyID: string) => Promise<boolean>;
+    satisfiableFactors: (descriptors: Array<CredentialFactorDescriptor>) => Array<SecretFactorKind> | null;
+    ownWrapping: (keyID: string, keyVersion: number) => Promise<CredentialWrappingWithBranch>;
+    factorsFromDescriptors: (descriptors: Array<CredentialFactorDescriptor>, inputs: FactorInputs | undefined) => Array<FactorInput>;
+    loadKey: (keyID: string, atVersion?: number) => Promise<CredentialKey>;
+    doOpenKey: (params: DoOpenKeyParams) => Promise<OpenedKey>;
+    openKey: (keyID: string, inputs?: FactorInputs, atVersion?: number) => Promise<OpenedKey>;
+    openSpecificBranch: (params: OpenSpecificBranchParams) => Promise<Uint8Array | null>;
+    rewrapOwn: (params: RewrapOwnParams) => Promise<void>;
+    hasSuppliedInputs: (inputs?: FactorInputs) => boolean;
+};
+export type OpenedKey = {
+    contentKey: Uint8Array;
+    version: number;
+    branchID: string;
+};
+export declare function createOpenFunctions(ctx: ManagerContext, internals: ManagerInternals): OpenFunctions;
+export {};