@kubun/credential 0.13.0 → 0.14.0

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/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.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -17,17 +17,19 @@
   "dependencies": {
     "@kokuin/jwe": "^0.1.0",
     "@kokuin/token": "^0.5.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.3.0",
     "@noble/hashes": "^2.3.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"