@kubun/credential 0.13.0 → 0.14.1

package/lib/api.d.ts

@@ -0,0 +1,69 @@
+import { type MethodRegistry } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { CredentialManager } from './manager.js';
+/**
+ * The credential seam: resolves its `(providerName, ownerDID) → entryID` pointer
+ * through the alias layer of the credential store, and its entries through a
+ * `CredentialManager`. Every `ownerDID` is normalized before it reaches the
+ * alias, so an un-normalized equality key cannot split one account across two
+ * rows: a credential invisible under one spelling and un-revokable under the
+ * other.
+ */
+export type CredentialAPI = {
+    getCredential: (providerName: string, ownerDID: string) => Promise<string | null>;
+    getCredentialProvenance: (providerName: string, ownerDID: string) => Promise<{
+        updatedAt: string | null;
+        writerDID: string | null;
+    } | null>;
+    /**
+     * Re-encrypt an existing credential. Refuses when none exists, because
+     * creating one is a different decision — see `createCredential`.
+     */
+    setCredential: (providerName: string, ownerDID: string, credential: string) => Promise<void>;
+    /**
+     * Mint the key, its two wrappings and the entry, and record the pointer.
+     *
+     * Split from `setCredential` so the headless refresh path cannot mint a key.
+     * A minted key fixes who will ever be able to read it, and a refresh running
+     * with no owner in hand would mint one wrapped to the server alone — locking
+     * the account owner out of their own credential with nothing failing.
+     */
+    createCredential: (params: {
+        providerName: string;
+        ownerDID: string;
+        ownerWrappableDID: string;
+        controllerWrappableDID?: string;
+        credential: string;
+    }) => Promise<void>;
+    deleteCredential: (providerName: string, ownerDID: string) => Promise<void>;
+    /**
+     * The controller resolvers for this API's (request-scoped) transaction
+     * provider — the exact `methods` the credential mint passes to `createKey`.
+     * Exposed so the OAuth pre-flight can ask `canWrapTo` with the same resolver
+     * the mint uses, rather than failing closed on a `did:kokuin:` owner whose
+     * agreement key is resolvable only through the controller resolver.
+     */
+    getControllerMethods: () => MethodRegistry;
+};
+export type CreateCredentialAPIParams = {
+    stores: StoreProvider;
+    logger: Logger;
+    /**
+     * Takes the `StoreProvider` rather than a manager, because during a mutation
+     * that provider is the transaction and a manager built over the base one
+     * would read outside it.
+     */
+    getCredentialManager: (stores: StoreProvider) => Promise<CredentialManager>;
+    /** The engine's own DID, in a form that can be encrypted to. */
+    serverWrappableDID: string;
+    /**
+     * Resolvers for wrapping recipients that carry no key material of their own
+     * (`did:kokuin:`), scoped to the request's transaction provider so a resolve
+     * reads the mutation's tx, never a second connection. A self-contained
+     * recipient resolves with an empty registry, so callers with no controller
+     * recipient in play still pass `() => []`.
+     */
+    getControllerMethods: (stores: StoreProvider) => MethodRegistry;
+};
+export declare function createCredentialAPI(params: CreateCredentialAPIParams): CredentialAPI;

package/lib/api.js

@@ -0,0 +1,124 @@
+import { normalizeDID } from '@kokuin/token';
+import { getCredentialStore } from '@kubun/store-credential';
+import { fromUTF, toUTF } from '@sozai/codec';
+import { CredentialSupersededBranch } from './errors.js';
+export function createCredentialAPI(params) {
+    const getAliasStore = ()=>getCredentialStore(params.stores);
+    const getCredentials = ()=>params.getCredentialManager(params.stores);
+    return {
+        async getCredential (providerName, ownerDID) {
+            const store = await getAliasStore();
+            const entryID = await store.getAliasEntryID(providerName, normalizeDID(ownerDID));
+            if (entryID == null) return null;
+            try {
+                return toUTF(await (await getCredentials()).readEntry(entryID));
+            } catch (error) {
+                if (error instanceof CredentialSupersededBranch) {
+                    params.logger.warn('Credential entry {entryID} for provider {providerName} belongs to a superseded branch', {
+                        providerName,
+                        entryID
+                    });
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async getCredentialProvenance (providerName, ownerDID) {
+            // Reflects the current pointer, not the winning branch — no superseded-branch guard
+            // (it never decrypts). Callers must gate on getCredential() != null so a loser-branch
+            // pointer's provenance is never surfaced.
+            const store = await getAliasStore();
+            const entryID = await store.getAliasEntryID(providerName, normalizeDID(ownerDID));
+            if (entryID == null) return null;
+            return (await getCredentials()).getEntryProvenance(entryID);
+        },
+        async setCredential (providerName, ownerDID, credential) {
+            const store = await getAliasStore();
+            const entryID = await store.getAliasEntryID(providerName, normalizeDID(ownerDID));
+            if (entryID == null) {
+                throw new Error(`No connector credential to update for provider "${providerName}"; create it through the authorization flow`);
+            }
+            // Opens the key through the server's own wrapping and rewrites the entry
+            // under it. No key is minted and no wrapping is touched, so a refresh
+            // cannot change who can read the credential.
+            await (await getCredentials()).updateEntry(entryID, fromUTF(credential));
+        },
+        async createCredential (input) {
+            const { providerName, ownerDID, ownerWrappableDID, credential } = input;
+            const store = await getAliasStore();
+            const credentials = await getCredentials();
+            // Wrapping to a DID needs only that DID's published key, so an engine that
+            // cannot decrypt would mint this key perfectly and then be unable to read
+            // it — a failure that surfaces at the first headless sync, far from here.
+            // This is where `cipher == null` used to fail closed, and it still does.
+            if (!credentials.availableFactors().includes('did')) {
+                throw new Error(`Cannot create a connector credential for "${providerName}": this engine's identity cannot decrypt, so it could never read back what it stored`);
+            }
+            // Two wrappings from the first write, not one plus a later grant: the
+            // server has to read this to run sync, and the owner has to be able to
+            // rotate and revoke it. Owner is authority, a different question from who
+            // can decrypt: when a controller is supplied it is the owner, so a device
+            // revoke goes through the controller's capability chain rather than the
+            // device self-authorizing; absent one the device owns its own key.
+            //
+            // The two spellings below are deliberately different questions about the
+            // same identity, and NOT interchangeable: `owner_did` is an equality key
+            // and so is normalized, while a recipient is encrypted to and must keep
+            // its wrappable form. `ownerWrappableDID` is therefore NOT normalized.
+            // Normalizing a `did:peer:4` recipient hands the short form to
+            // `deriveSharedSecret`, which resolves no document and no agreement key —
+            // do not fold these together.
+            const wrappings = [
+                [
+                    {
+                        kind: 'did',
+                        recipientDID: ownerWrappableDID
+                    }
+                ],
+                [
+                    {
+                        kind: 'did',
+                        recipientDID: params.serverWrappableDID
+                    }
+                ]
+            ];
+            // A recovery recipient (e.g. a controller / seed-holder), so the credential
+            // survives device loss. Opt-in: absent when the caller supplied none. Kept
+            // in its wrappable form for the same reason as the two above — it is
+            // encrypted to, not compared against.
+            if (input.controllerWrappableDID != null) {
+                wrappings.push([
+                    {
+                        kind: 'did',
+                        recipientDID: input.controllerWrappableDID
+                    }
+                ]);
+            }
+            // The controller owns the key when supplied (its canonical DID equals the
+            // normalized wrappable form); the account pointer below stays keyed on the
+            // device — ownership and account scoping are separate concerns.
+            const keyOwnerDID = input.controllerWrappableDID != null ? normalizeDID(input.controllerWrappableDID) : normalizeDID(ownerDID);
+            const keyID = await credentials.createKey({
+                ownerDID: keyOwnerDID,
+                wrappings,
+                methods: params.getControllerMethods(params.stores)
+            });
+            const entryID = await credentials.putEntry(keyID, fromUTF(credential));
+            await store.setAliasEntryID(providerName, normalizeDID(ownerDID), entryID);
+        },
+        async deleteCredential (providerName, ownerDID) {
+            const store = await getAliasStore();
+            const owner = normalizeDID(ownerDID);
+            const entryID = await store.getAliasEntryID(providerName, owner);
+            await store.deleteAliasEntryID(providerName, owner);
+            if (entryID != null) {
+                // The pointer and the entry go together. Leaving the entry would keep
+                // the token readable by anyone who kept its id after a disconnect.
+                await (await getCredentials()).deleteEntry(entryID);
+            }
+        },
+        getControllerMethods () {
+            return params.getControllerMethods(params.stores);
+        }
+    };
+}

package/lib/index.d.ts

@@ -1,3 +1,5 @@
+export type { CreateCredentialAPIParams, CredentialAPI } from './api.js';
+export { createCredentialAPI } from './api.js';
 export type { CredentialAuthority, CredentialAuthorityParams, CredentialAuthorization, } from './authority.js';
 export { createDeviceAuthority } from './authority.js';
 export type { BuildEntryParams, BuildKeyParams, BuiltEntry, BuiltKey, BuiltWrapping, CredentialKeyMaterial, } from './builder.js';
@@ -14,6 +16,8 @@ export type { PinThrottle, PinThrottleParams } from './pin-throttle.js';
 export { createPinThrottle, DEFAULT_BASE_DELAY, DEFAULT_FREE_ATTEMPTS, DEFAULT_MAX_DELAY, } from './pin-throttle.js';
 export type { CredentialEntryProvenance } from './provenance.js';
 export { entryProvenanceFields } from './provenance.js';
+export type { DBCredentialProviderParams } from './provider.js';
+export { DBCredentialProvider, deserializeCredential, serializeCredential } from './provider.js';
 export type { Argon2Cost, CredentialSuite, FactorInput, FactorInputs, SecretFactorKind, } from './suite.js';
 export { DEFAULT_ARGON2_COST, getSuite, isSupportedSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
 export { CREDENTIAL_ADMINISTER_ACTION, credentialUserResource } from './vocabulary.js';

package/lib/index.js

@@ -1,3 +1,4 @@
+export { createCredentialAPI } from './api.js';
 export { createDeviceAuthority } from './authority.js';
 export { buildCredentialEntry, buildCredentialKey } from './builder.js';
 export { credentialEntriesDigest, credentialEntryDigest, credentialKeyDigest, credentialWrappingDigest, digestParts } from './digest.js';
@@ -6,5 +7,6 @@ export { createCredentialManager } from './manager.js';
 export { compareBranchIDs, createCredentialOpSigner, credentialOpMatchesPut, credentialOpMatchesRow, credentialPutDigest, credentialRowDigest, selectWinningBranch, verifyCredentialOp } from './op.js';
 export { createPinThrottle, DEFAULT_BASE_DELAY, DEFAULT_FREE_ATTEMPTS, DEFAULT_MAX_DELAY } from './pin-throttle.js';
 export { entryProvenanceFields } from './provenance.js';
+export { DBCredentialProvider, deserializeCredential, serializeCredential } from './provider.js';
 export { DEFAULT_ARGON2_COST, getSuite, isSupportedSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
 export { CREDENTIAL_ADMINISTER_ACTION, credentialUserResource } from './vocabulary.js';

package/lib/key-cache.d.ts

@@ -27,6 +27,12 @@ export type KeyCache = {
         contentKey: Uint8Array;
         branchID: string;
     } | null;
+    /**
+     * Whether an unexpired, current-version key is cached, without materialising a
+     * copy of it. Presence-only callers (`status`) use this so a probe never mints
+     * a secret buffer it immediately discards.
+     */
+    has(keyID: string, keyVersion: number): boolean;
     set(keyID: string, contentKey: Uint8Array, keyVersion: number, branchID: string): void;
     evict(keyID: string): void;
     evictAll(): void;

package/lib/key-cache.js

@@ -8,8 +8,8 @@ export function createKeyCache(params = {}) {
    *
    * Dropping the entry alone leaves the bytes wherever they are until a
    * collector reaches them. Zeroing is the part that can be guaranteed;
-   * JavaScript cannot promise no interpreter-level copy survives, and the design
-   * spec records that limit rather than implying hygiene it cannot deliver.
+   * JavaScript cannot promise no interpreter-level copy survives, so this is
+   * best-effort hygiene, not a guarantee that no copy of the key remains.
    */ function evict(keyID) {
         const cached = entries.get(keyID);
         if (cached != null) {
@@ -17,27 +17,48 @@ export function createKeyCache(params = {}) {
             entries.delete(keyID);
         }
     }
+    /**
+   * The still-valid cached entry for this key/version, or null — evicting a
+   * stale one on the way. A rotation invalidates the cache as surely as time
+   * does: serving the pre-rotation key would decrypt entries the rotation was
+   * retiring. Shared by `get` and `has` so both apply identical validity and
+   * lazy-eviction rules; neither exposes the buffer.
+   */ function live(keyID, keyVersion) {
+        const cached = entries.get(keyID);
+        if (cached == null) {
+            return null;
+        }
+        if (now() - cached.unlockedAt >= ttl || cached.keyVersion !== keyVersion) {
+            evict(keyID);
+            return null;
+        }
+        return cached;
+    }
     return {
         get (keyID, keyVersion) {
-            const cached = entries.get(keyID);
+            const cached = live(keyID, keyVersion);
             if (cached == null) {
                 return null;
             }
-            // A rotation invalidates the cache as surely as time does: serving the
-            // pre-rotation key would decrypt entries the rotation was retiring.
-            if (now() - cached.unlockedAt >= ttl || cached.keyVersion !== keyVersion) {
-                evict(keyID);
-                return null;
-            }
+            // The caller receives a private copy, never the cache's own buffer: the
+            // cache reserves the right to zero what it holds (on evict, replacement,
+            // expiry or lock), and a returned alias would let that zeroing corrupt a
+            // consumer still holding the key across an await.
             return {
-                contentKey: cached.contentKey,
+                contentKey: cached.contentKey.slice(),
                 branchID: cached.branchID
             };
         },
+        has (keyID, keyVersion) {
+            return live(keyID, keyVersion) != null;
+        },
         set (keyID, contentKey, keyVersion, branchID) {
             evict(keyID);
+            // Store a private clone so the caller's buffer is never the cached buffer:
+            // the caller may zero its own copy after use without disturbing the cache,
+            // and the cache may zero its clone on evict without disturbing the caller.
             entries.set(keyID, {
-                contentKey,
+                contentKey: contentKey.slice(),
                 keyVersion,
                 branchID,
                 unlockedAt: now()

package/lib/manager.js

@@ -28,6 +28,21 @@ export function createCredentialManager(params) {
         ...params.pinThrottle,
         now: params.now
     });
+    // Concurrency guards for `openKey`:
+    // - `inFlight` collapses a thundering herd of input-free opens of one key into
+    //   a single unwrap; each waiter then takes its own clone from the cache.
+    // - `keyGeneration` (bumped by `lock`) and `lockAllEpoch` (bumped by `lockAll`)
+    //   let a lock landing mid-open suppress that open's `cache.set`, so an open
+    //   begun before the lock cannot re-warm the cache the lock just cleared. The
+    //   in-flight read still returns its key — it was already authorized; the lock
+    //   only means "do not stay warm."
+    const inFlight = new Map();
+    const keyGeneration = new Map();
+    let lockAllEpoch = 0;
+    // 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);
     let floorPromise;
     /**
    * Floor the shared clock to the greatest stored entry HLC, once per manager.
@@ -151,18 +166,27 @@ export function createCredentialManager(params) {
         const key = await loadKey(keyID);
         const existing = await ownWrapping(keyID, key.version);
         const { contentKey, branchID } = await openKey(keyID, inputs);
-        const factors = change(factorsFromDescriptors(existing.factors, inputs));
         const suite = getSuite(key.suite);
         const wrappingID = runtime.getRandomID();
-        const { descriptors, iv, wrappedKey } = await suite.wrap({
-            runtime,
-            contentKey,
-            factors,
-            wrappingID,
-            keyID,
-            keyVersion: key.version,
-            methods
-        });
+        // `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,
@@ -197,7 +221,17 @@ export function createCredentialManager(params) {
    * 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.
-   */ async function openKey(keyID, inputs) {
+   */ /**
+   * 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) {
+        // `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 = ()=>(keyGeneration.get(keyID) ?? 0) !== genAtStart || lockAllEpoch !== epochAtStart;
         const key = await loadKey(keyID);
         const proven = new Set((await store.listKeyBranches(keyID, key.version)).map((branch)=>branch.branch_id));
         const winner = proven.size >= 2 ? selectWinningBranch([
@@ -212,6 +246,9 @@ export function createCredentialManager(params) {
                     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.evict(keyID);
         }
         const suite = getSuite(key.suite);
@@ -258,7 +295,11 @@ export function createCredentialManager(params) {
                 // 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;
-                cache.set(keyID, contentKey, key.version, branchID);
+                // 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, key.version, branchID);
+                }
                 return {
                     contentKey,
                     version: key.version,
@@ -289,6 +330,55 @@ export function createCredentialManager(params) {
         }
         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) {
+        // Captured once, at entry, so a lock landing while this call is queued behind
+        // another open still counts against it (see `doOpenKey`).
+        const genAtStart = keyGeneration.get(keyID) ?? 0;
+        const epochAtStart = lockAllEpoch;
+        if (hasSuppliedInputs(inputs)) {
+            return doOpenKey(keyID, inputs, genAtStart, epochAtStart);
+        }
+        // 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 = inFlight.get(keyID);
+            if (pending == null) {
+                break;
+            }
+            await pending;
+            const key = await loadKey(keyID);
+            const hit = cache.get(keyID, key.version);
+            if (hit != null) {
+                return {
+                    contentKey: hit.contentKey,
+                    version: key.version,
+                    branchID: hit.branchID
+                };
+            }
+        }
+        const run = doOpenKey(keyID, inputs, genAtStart, epochAtStart);
+        // 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);
+        inFlight.set(keyID, gate);
+        try {
+            return await run;
+        } finally{
+            // Only clear our own entry — a later leader may already have replaced it.
+            if (inFlight.get(keyID) === gate) {
+                inFlight.delete(keyID);
+            }
+        }
+    }
     return {
         availableFactors () {
             // A passphrase or pin needs no key material, only someone to ask. They are
@@ -302,7 +392,9 @@ export function createCredentialManager(params) {
         },
         async unlock (keyID, inputs) {
             if (inputs?.pin == null) {
-                await openKey(keyID, inputs);
+                // 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.
@@ -316,7 +408,8 @@ export function createCredentialManager(params) {
                 });
             }
             try {
-                await openKey(keyID, inputs);
+                ;
+                (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
@@ -378,9 +471,13 @@ export function createCredentialManager(params) {
             }, params?.methods);
         },
         lock (keyID) {
+            // Bump before evicting so an `openKey` already past its generation capture
+            // sees the change and skips its `cache.set`.
+            keyGeneration.set(keyID, (keyGeneration.get(keyID) ?? 0) + 1);
             cache.evict(keyID);
         },
         lockAll () {
+            lockAllEpoch += 1;
             cache.evictAll();
         },
         async status (keyID) {
@@ -397,7 +494,7 @@ export function createCredentialManager(params) {
                     reason: 'unsupported-suite'
                 };
             }
-            if (cache.get(keyID, key.version) != null) {
+            if (cache.has(keyID, key.version)) {
                 return {
                     state: 'unlocked'
                 };
@@ -461,6 +558,10 @@ export function createCredentialManager(params) {
                 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,
@@ -508,121 +609,134 @@ export function createCredentialManager(params) {
             // read, has to fail while the store is still untouched — past the first
             // write there is nothing here that could put it back.
             const previousKey = (await openKey(keyID, rotateParams?.inputs)).contentKey;
-            const retained = (await store.listWrappings(keyID, key.version)).map((wrapping)=>({
-                    recipientDID: wrapping.recipient_did,
-                    factors: factorsFromDescriptors(wrapping.factors, rotateParams?.inputs)
-                }));
-            const plaintexts = (await store.listEntries(keyID)).map((entry)=>{
-                // An entry left behind by a rotation that did not finish. Carrying it
-                // forward is impossible — its ciphertext is under a content key nothing
-                // holds — and skipping it would quietly strand it one version further.
-                if (entry.key_version !== key.version) {
-                    throw new CredentialKeyVersionMismatch(entry.entry_id, entry.key_version, key.version);
-                }
-                return {
-                    entryID: entry.entry_id,
-                    plaintext: previousSuite.decryptEntry({
-                        contentKey: previousKey,
-                        iv: new Uint8Array(entry.iv),
-                        ciphertext: new Uint8Array(entry.ciphertext),
-                        keyID,
-                        keyVersion: entry.key_version,
-                        entryID: entry.entry_id
-                    })
-                };
-            });
-            const contentKey = suite.generateContentKey(runtime);
-            // Signed before the entries and wrappings it labels — its branch is what
-            // they join — but persisted last, so the version bump still lands after
-            // the rows a reader needs at it. Signing touches no store, so this only
-            // moves the key-op's stamp ahead of the batch, which is where the branch
-            // it introduces belongs.
-            const rotatedKey = {
-                keyID,
-                ownerDID: key.owner_did,
-                suite: suiteID,
-                version: newVersion,
-                state: key.state === 'retired' ? 'retired' : 'active'
-            };
-            const rotatedKeyOp = await ops.key(rotatedKey, await nextHLC());
-            const branchID = rotatedKeyOp.branchID;
-            await store.recordKeyBranch({
-                keyID,
-                keyVersion: newVersion,
-                authorDID: rotatedKeyOp.authorDID,
-                hlc: rotatedKeyOp.hlc,
-                opJWT: rotatedKeyOp.opJWT,
-                opHash: rotatedKeyOp.opHash,
-                branchID: rotatedKeyOp.branchID
-            });
-            for (const { entryID, plaintext } of plaintexts){
-                const { iv, ciphertext } = suite.encryptEntry({
-                    runtime,
-                    contentKey,
-                    plaintext,
-                    keyID,
-                    keyVersion: newVersion,
-                    entryID
+            // Both key buffers are our private clones. One try spans from here to the end so
+            // a throw anywhere in the rotation zeros them, not only the success path.
+            // `previousKey` is read only in the plaintext-recovery loop; the generated
+            // key through the last write. It is declared here so the `finally` can zero
+            // it whether or not generation was reached.
+            let generatedKey;
+            try {
+                const retained = (await store.listWrappings(keyID, key.version)).map((wrapping)=>({
+                        recipientDID: wrapping.recipient_did,
+                        factors: factorsFromDescriptors(wrapping.factors, rotateParams?.inputs)
+                    }));
+                const plaintexts = (await store.listEntries(keyID)).map((entry)=>{
+                    // An entry left behind by a rotation that did not finish. Carrying it
+                    // forward is impossible — its ciphertext is under a content key nothing
+                    // holds — and skipping it would quietly strand it one version further.
+                    if (entry.key_version !== key.version) {
+                        throw new CredentialKeyVersionMismatch(entry.entry_id, entry.key_version, key.version);
+                    }
+                    return {
+                        entryID: entry.entry_id,
+                        plaintext: previousSuite.decryptEntry({
+                            contentKey: previousKey,
+                            iv: new Uint8Array(entry.iv),
+                            ciphertext: new Uint8Array(entry.ciphertext),
+                            keyID,
+                            keyVersion: entry.key_version,
+                            entryID: entry.entry_id
+                        })
+                    };
                 });
-                const entryParams = {
-                    entryID,
+                const contentKey = suite.generateContentKey(runtime);
+                generatedKey = contentKey;
+                // Signed before the entries and wrappings it labels — its branch is what
+                // they join — but persisted last, so the version bump still lands after
+                // the rows a reader needs at it. Signing touches no store, so this only
+                // moves the key-op's stamp ahead of the batch, which is where the branch
+                // it introduces belongs.
+                const rotatedKey = {
                     keyID,
-                    keyVersion: newVersion,
-                    iv,
-                    ciphertext,
-                    hlc: await nextHLC()
+                    ownerDID: key.owner_did,
+                    suite: suiteID,
+                    version: newVersion,
+                    state: key.state === 'retired' ? 'retired' : 'active'
                 };
-                await store.putEntry(entryParams, await ops.entry(entryParams, branchID));
-            }
-            for (const { recipientDID, factors } of retained){
-                const wrappingID = runtime.getRandomID();
-                const { descriptors, iv, wrappedKey } = await suite.wrap({
-                    runtime,
-                    contentKey,
-                    factors,
-                    wrappingID,
+                const rotatedKeyOp = await ops.key(rotatedKey, await nextHLC());
+                const branchID = rotatedKeyOp.branchID;
+                await store.recordKeyBranch({
                     keyID,
                     keyVersion: newVersion,
-                    methods: rotateParams?.methods
+                    authorDID: rotatedKeyOp.authorDID,
+                    hlc: rotatedKeyOp.hlc,
+                    opJWT: rotatedKeyOp.opJWT,
+                    opHash: rotatedKeyOp.opHash,
+                    branchID: rotatedKeyOp.branchID
                 });
-                const wrappingParams = {
-                    wrappingID,
-                    keyID,
-                    keyVersion: newVersion,
-                    factors: descriptors,
-                    iv,
-                    wrappedKey,
-                    recipientDID
-                };
-                await store.putWrapping(wrappingParams, await ops.wrapping(wrappingParams, await nextHLC(), branchID));
-            }
-            // The version and the suite have to land together — an entry encrypted
-            // under one and read under the other fails its tag — and the op speaks for
-            // the whole row either way, so both branches sign the same shape. The op
-            // was signed above so its label could tag the rows; it persists here.
-            if (suiteID === key.suite) {
-                await store.setKeyVersion(keyID, newVersion, rotatedKeyOp);
-            } else {
-                await store.putKey(rotatedKey, rotatedKeyOp);
-            }
-            // Listed before the sweep so every removed row gets a tombstone: the delete
-            // predicate spans versions, and a row it takes with no tombstone comes back
-            // the first time a peer that still holds it ships it over.
-            const superseded = (await store.listWrappings(keyID)).filter((wrapping)=>wrapping.key_version < newVersion);
-            const tombstones = [];
-            for (const wrapping of superseded){
-                tombstones.push(await ops.wrappingTombstone({
-                    subjectKind: 'wrapping',
-                    subjectID: wrapping.wrapping_id,
-                    keyID,
-                    keyVersion: wrapping.key_version
-                }, await nextHLC()));
+                for (const { entryID, plaintext } of plaintexts){
+                    const { iv, ciphertext } = suite.encryptEntry({
+                        runtime,
+                        contentKey,
+                        plaintext,
+                        keyID,
+                        keyVersion: newVersion,
+                        entryID
+                    });
+                    const entryParams = {
+                        entryID,
+                        keyID,
+                        keyVersion: newVersion,
+                        iv,
+                        ciphertext,
+                        hlc: await nextHLC()
+                    };
+                    await store.putEntry(entryParams, await ops.entry(entryParams, branchID));
+                }
+                for (const { recipientDID, factors } of retained){
+                    const wrappingID = runtime.getRandomID();
+                    const { descriptors, iv, wrappedKey } = await suite.wrap({
+                        runtime,
+                        contentKey,
+                        factors,
+                        wrappingID,
+                        keyID,
+                        keyVersion: newVersion,
+                        methods: rotateParams?.methods
+                    });
+                    const wrappingParams = {
+                        wrappingID,
+                        keyID,
+                        keyVersion: newVersion,
+                        factors: descriptors,
+                        iv,
+                        wrappedKey,
+                        recipientDID
+                    };
+                    await store.putWrapping(wrappingParams, await ops.wrapping(wrappingParams, await nextHLC(), branchID));
+                }
+                // The version and the suite have to land together — an entry encrypted
+                // under one and read under the other fails its tag — and the op speaks
+                // for the whole row either way, so both branches sign the same shape. The
+                // op was signed above so its label could tag the rows; it persists here.
+                if (suiteID === key.suite) {
+                    await store.setKeyVersion(keyID, newVersion, rotatedKeyOp);
+                } else {
+                    await store.putKey(rotatedKey, rotatedKeyOp);
+                }
+                // Listed before the sweep so every removed row gets a tombstone: the
+                // delete predicate spans versions, and a row it takes with no tombstone
+                // comes back the first time a peer that still holds it ships it over.
+                const superseded = (await store.listWrappings(keyID)).filter((wrapping)=>wrapping.key_version < newVersion);
+                const tombstones = [];
+                for (const wrapping of superseded){
+                    tombstones.push(await ops.wrappingTombstone({
+                        subjectKind: 'wrapping',
+                        subjectID: wrapping.wrapping_id,
+                        keyID,
+                        keyVersion: wrapping.key_version
+                    }, await nextHLC()));
+                }
+                await store.deleteWrappingsBelowVersion(keyID, newVersion, tombstones);
+                // The rotation's own key-op labels the branch it just made. `cache.set`
+                // stores its own clone, so zeroing the local generated key in the
+                // `finally` does not disturb the cached one.
+                cache.set(keyID, contentKey, newVersion, branchID);
+                return newVersion;
+            } finally{
+                previousKey.fill(0);
+                generatedKey?.fill(0);
             }
-            await store.deleteWrappingsBelowVersion(keyID, newVersion, tombstones);
-            // Zeroes `previousKey` on the way in, which is why nothing above may read
-            // it afterwards. The rotation's own key-op labels the branch it just made.
-            cache.set(keyID, contentKey, newVersion, branchID);
-            return newVersion;
         },
         async grant (keyID, recipientWrappableDID, params) {
             const key = await loadKey(keyID);
@@ -654,20 +768,27 @@ export function createCredentialManager(params) {
             // leave a wrapping nobody can open.
             const { contentKey, branchID } = await openKey(keyID);
             const wrappingID = runtime.getRandomID();
-            const { descriptors, iv, wrappedKey } = await getSuite(key.suite).wrap({
-                runtime,
-                contentKey,
-                factors: [
-                    {
-                        kind: 'did',
-                        recipientDID: recipientWrappableDID
-                    }
-                ],
-                wrappingID,
-                keyID,
-                keyVersion: key.version,
-                methods: params?.methods
-            });
+            const suite = getSuite(key.suite);
+            let wrapped;
+            try {
+                wrapped = await suite.wrap({
+                    runtime,
+                    contentKey,
+                    factors: [
+                        {
+                            kind: 'did',
+                            recipientDID: recipientWrappableDID
+                        }
+                    ],
+                    wrappingID,
+                    keyID,
+                    keyVersion: key.version,
+                    methods: params?.methods
+                });
+            } finally{
+                contentKey.fill(0);
+            }
+            const { descriptors, iv, wrappedKey } = wrapped;
             const granted = {
                 wrappingID,
                 keyID,
@@ -712,20 +833,25 @@ export function createCredentialManager(params) {
         },
         async putEntry (keyID, plaintext) {
             const { contentKey, version, branchID } = await openKey(keyID);
-            const key = await store.getKey(keyID);
-            const entry = buildCredentialEntry({
-                runtime,
-                key: {
-                    keyID,
-                    // The key's owner, not this device: an entry under a viewer's key
-                    // belongs to that viewer even when a server wrote it.
-                    ownerDID: key?.owner_did ?? identity.id,
-                    suite: key?.suite ?? SUITE_KUBUN_CRED_1,
-                    version,
-                    contentKey
-                },
-                plaintext
-            });
+            let entry;
+            try {
+                const key = await store.getKey(keyID);
+                entry = buildCredentialEntry({
+                    runtime,
+                    key: {
+                        keyID,
+                        // The key's owner, not this device: an entry under a viewer's key
+                        // belongs to that viewer even when a server wrote it.
+                        ownerDID: key?.owner_did ?? identity.id,
+                        suite: key?.suite ?? SUITE_KUBUN_CRED_1,
+                        version,
+                        contentKey
+                    },
+                    plaintext
+                });
+            } finally{
+                contentKey.fill(0);
+            }
             const entryParams = {
                 ...entry,
                 hlc: await nextHLC()
@@ -739,18 +865,25 @@ export function createCredentialManager(params) {
                 throw new CredentialNotFound('Credential entry', entryID);
             }
             const { contentKey, version, branchID } = await openKey(existing.key_id);
-            const suite = getSuite((await store.getKey(existing.key_id))?.suite ?? SUITE_KUBUN_CRED_1);
             // Re-encrypted under the key's CURRENT version, not the version the entry
             // was written at: an update is a fresh write, and leaving it behind would
-            // keep a rotated-away version alive indefinitely.
-            const { iv, ciphertext } = suite.encryptEntry({
-                runtime,
-                contentKey,
-                plaintext,
-                keyID: existing.key_id,
-                keyVersion: version,
-                entryID
-            });
+            // keep a rotated-away version alive indefinitely. The suite lookup's store
+            // read is inside the `try` so a rejection cannot leak the key copy.
+            let encrypted;
+            try {
+                const suite = getSuite((await store.getKey(existing.key_id))?.suite ?? SUITE_KUBUN_CRED_1);
+                encrypted = suite.encryptEntry({
+                    runtime,
+                    contentKey,
+                    plaintext,
+                    keyID: existing.key_id,
+                    keyVersion: version,
+                    entryID
+                });
+            } finally{
+                contentKey.fill(0);
+            }
+            const { iv, ciphertext } = encrypted;
             const updated = {
                 entryID,
                 keyID: existing.key_id,
@@ -777,18 +910,24 @@ export function createCredentialManager(params) {
                 throw new CredentialKeyVersionMismatch(entryID, entry.key_version, key.version);
             }
             const { contentKey, branchID } = await openKey(entry.key_id);
-            const entryBranchID = (await store.getOp('entry', entryID))?.branch_id ?? '';
-            if (entryBranchID !== '' && branchID !== '' && entryBranchID !== branchID) {
-                throw new CredentialSupersededBranch(entryID, entryBranchID, branchID);
+            // Zero our private clone on every exit — the branch-mismatch throw
+            // and the decrypt alike.
+            try {
+                const entryBranchID = (await store.getOp('entry', entryID))?.branch_id ?? '';
+                if (entryBranchID !== '' && branchID !== '' && entryBranchID !== branchID) {
+                    throw new CredentialSupersededBranch(entryID, entryBranchID, branchID);
+                }
+                return getSuite(key.suite).decryptEntry({
+                    contentKey,
+                    iv: new Uint8Array(entry.iv),
+                    ciphertext: new Uint8Array(entry.ciphertext),
+                    keyID: entry.key_id,
+                    keyVersion: entry.key_version,
+                    entryID
+                });
+            } finally{
+                contentKey.fill(0);
             }
-            return getSuite(key.suite).decryptEntry({
-                contentKey,
-                iv: new Uint8Array(entry.iv),
-                ciphertext: new Uint8Array(entry.ciphertext),
-                keyID: entry.key_id,
-                keyVersion: entry.key_version,
-                entryID
-            });
         },
         async getEntryProvenance (entryID) {
             const entry = await store.getEntryWithProvenance(entryID);
@@ -848,25 +987,36 @@ export function createCredentialManager(params) {
             // A target this device cannot open has to fail while the entry is still
             // where it was.
             const { contentKey: fromContentKey } = await openKey(entry.key_id);
-            const plaintext = getSuite(fromKey.suite).decryptEntry({
-                contentKey: fromContentKey,
-                iv: new Uint8Array(entry.iv),
-                ciphertext: new Uint8Array(entry.ciphertext),
-                keyID: entry.key_id,
-                keyVersion: entry.key_version,
-                entryID
-            });
+            let plaintext;
+            try {
+                plaintext = getSuite(fromKey.suite).decryptEntry({
+                    contentKey: fromContentKey,
+                    iv: new Uint8Array(entry.iv),
+                    ciphertext: new Uint8Array(entry.ciphertext),
+                    keyID: entry.key_id,
+                    keyVersion: entry.key_version,
+                    entryID
+                });
+            } finally{
+                fromContentKey.fill(0);
+            }
             const { contentKey: toContentKey, version, branchID } = await openKey(toKeyID);
             // The target's CURRENT version, as an update is: landing on an older one
             // would strand the entry the moment the key rotates.
-            const { iv, ciphertext } = getSuite(toKey.suite).encryptEntry({
-                runtime,
-                contentKey: toContentKey,
-                plaintext,
-                keyID: toKeyID,
-                keyVersion: version,
-                entryID
-            });
+            let reEncrypted;
+            try {
+                reEncrypted = getSuite(toKey.suite).encryptEntry({
+                    runtime,
+                    contentKey: toContentKey,
+                    plaintext,
+                    keyID: toKeyID,
+                    keyVersion: version,
+                    entryID
+                });
+            } finally{
+                toContentKey.fill(0);
+            }
+            const { iv, ciphertext } = reEncrypted;
             const moved = {
                 entryID,
                 keyID: toKeyID,

package/lib/provider.d.ts

@@ -0,0 +1,24 @@
+import type { Credential, CredentialProvider, OAuthProviderDefinition } from '@kubun/credential-types';
+import type { Runtime } from '@sozai/runtime';
+import type { CredentialAPI } from './api.js';
+export declare function serializeCredential(credential: Credential): string;
+export declare function deserializeCredential(raw: string | Record<string, unknown>): Credential;
+export type DBCredentialProviderParams = {
+    api: CredentialAPI;
+    runtime: Runtime;
+    providers: Array<OAuthProviderDefinition>;
+    bufferSeconds?: number;
+};
+export declare class DBCredentialProvider implements CredentialProvider {
+    #private;
+    constructor(params: DBCredentialProviderParams);
+    get(providerName: string, ownerDID: string): Promise<Credential | null>;
+    set(params: {
+        providerName: string;
+        ownerDID: string;
+        credential: Credential;
+        ownerWrappableDID?: string;
+        controllerWrappableDID?: string;
+    }): Promise<void>;
+    delete(providerName: string, ownerDID: string): Promise<void>;
+}

package/lib/provider.js

@@ -0,0 +1,129 @@
+const DEFAULT_BUFFER_SECONDS = 300;
+export function serializeCredential(credential) {
+    const serialized = {
+        accessToken: credential.accessToken,
+        scopes: credential.scopes
+    };
+    if (credential.refreshToken != null) {
+        serialized.refreshToken = credential.refreshToken;
+    }
+    if (credential.expiresAt != null) {
+        serialized.expiresAt = credential.expiresAt.toISOString();
+    }
+    if (credential.accountLabel != null) {
+        serialized.accountLabel = credential.accountLabel;
+    }
+    if (credential.metadata != null) {
+        serialized.metadata = credential.metadata;
+    }
+    return JSON.stringify(serialized);
+}
+export function deserializeCredential(raw) {
+    // ParseJSONResultsPlugin may have already parsed the JSON string
+    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    const credential = {
+        accessToken: parsed.accessToken,
+        scopes: parsed.scopes
+    };
+    if (parsed.refreshToken != null) {
+        credential.refreshToken = parsed.refreshToken;
+    }
+    if (parsed.expiresAt != null) {
+        credential.expiresAt = new Date(parsed.expiresAt);
+    }
+    if (parsed.accountLabel != null) {
+        credential.accountLabel = parsed.accountLabel;
+    }
+    if (parsed.metadata != null) {
+        credential.metadata = parsed.metadata;
+    }
+    return credential;
+}
+export class DBCredentialProvider {
+    #api;
+    #runtime;
+    #providers;
+    #bufferMs;
+    constructor(params){
+        this.#api = params.api;
+        this.#runtime = params.runtime;
+        this.#providers = params.providers;
+        this.#bufferMs = (params.bufferSeconds ?? DEFAULT_BUFFER_SECONDS) * 1000;
+    }
+    async get(providerName, ownerDID) {
+        const raw = await this.#api.getCredential(providerName, ownerDID);
+        if (raw == null) return null;
+        const credential = deserializeCredential(raw);
+        if (this.#isExpiringSoon(credential) && credential.refreshToken != null) {
+            const refreshed = await this.#refresh(providerName, ownerDID, credential, credential.refreshToken);
+            return refreshed ?? credential;
+        }
+        return credential;
+    }
+    async set(params) {
+        const { providerName, ownerDID, credential, ownerWrappableDID, controllerWrappableDID } = params;
+        const serialized = serializeCredential(credential);
+        // Update when one exists, mint only when it does not. Dispatching on
+        // presence rather than on the caller keeps the refresh path unable to mint
+        // even when it does hold a wrappable DID.
+        if (await this.#api.getCredential(providerName, ownerDID) != null) {
+            await this.#api.setCredential(providerName, ownerDID, serialized);
+            return;
+        }
+        if (ownerWrappableDID == null) {
+            throw new Error(`Cannot create a connector credential for "${providerName}" without the owner's wrappable DID`);
+        }
+        await this.#api.createCredential({
+            providerName,
+            ownerDID,
+            ownerWrappableDID,
+            controllerWrappableDID,
+            credential: serialized
+        });
+    }
+    async delete(providerName, ownerDID) {
+        await this.#api.deleteCredential(providerName, ownerDID);
+    }
+    #isExpiringSoon(credential) {
+        if (credential.expiresAt == null) return false;
+        return credential.expiresAt.getTime() - Date.now() < this.#bufferMs;
+    }
+    async #refresh(providerName, ownerDID, credential, refreshToken) {
+        const provider = this.#providers.find((p)=>p.name === providerName);
+        if (provider == null || provider.clientID == null || provider.clientSecret == null) {
+            return null;
+        }
+        try {
+            const response = await this.#runtime.fetch(provider.tokenEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                },
+                body: new URLSearchParams({
+                    grant_type: 'refresh_token',
+                    refresh_token: refreshToken,
+                    client_id: provider.clientID,
+                    client_secret: provider.clientSecret
+                })
+            });
+            if (!response.ok) return null;
+            const tokenData = await response.json();
+            const refreshed = {
+                accessToken: tokenData.access_token,
+                refreshToken: tokenData.refresh_token ?? credential.refreshToken,
+                expiresAt: tokenData.expires_in != null ? new Date(Date.now() + tokenData.expires_in * 1000) : undefined,
+                scopes: tokenData.scope?.split(' ') ?? credential.scopes,
+                accountLabel: credential.accountLabel,
+                metadata: credential.metadata
+            };
+            await this.set({
+                providerName,
+                ownerDID,
+                credential: refreshed
+            });
+            return refreshed;
+        } catch  {
+            return null;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/credential",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -17,17 +17,19 @@
   "dependencies": {
     "@kokuin/jwe": "^0.1.0",
     "@kokuin/token": "^0.5.0",
-    "@noble/ciphers": "^2.3.0",
-    "@noble/hashes": "^2.3.0",
+    "@kubun/credential-types": "^0.14.0",
+    "@kubun/db": "^0.14.0",
+    "@kubun/hlc": "^0.14.0",
+    "@kubun/id": "^0.14.0",
+    "@kubun/logger": "^0.14.0",
+    "@kubun/store-credential": "^0.14.0",
+    "@noble/ciphers": "^2.4.0",
+    "@noble/hashes": "^2.4.0",
     "@sozai/codec": "^0.4.0",
-    "@sozai/runtime": "^0.1.0",
-    "@kubun/hlc": "^0.13.0",
-    "@kubun/store-credential": "^0.13.0",
-    "@kubun/id": "^0.13.0"
+    "@sozai/runtime": "^0.1.0"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.13.0",
-    "@kubun/db": "^0.13.0"
+    "@kubun/db-better-sqlite": "^0.14.0"
   },
   "publishConfig": {
     "access": "public"