@kubun/credential 0.14.1 → 0.14.2

package/lib/index.d.ts

@@ -18,6 +18,8 @@ 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 { RefreshEvents, RefreshedEvent, RefreshFailedEvent, RefreshFailureCategory, RefreshingCredentialProviderParams, RefreshOutcome, } from './refreshing-credential-provider.js';
+export { RefreshingCredentialProvider } from './refreshing-credential-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

@@ -8,5 +8,6 @@ export { compareBranchIDs, createCredentialOpSigner, credentialOpMatchesPut, cre
 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 { RefreshingCredentialProvider } from './refreshing-credential-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

@@ -1,13 +1,9 @@
-import type { Credential, CredentialProvider, OAuthProviderDefinition } from '@kubun/credential-types';
-import type { Runtime } from '@sozai/runtime';
+import type { Credential, CredentialProvider } from '@kubun/credential-types';
 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;

package/lib/provider.js

@@ -1,4 +1,3 @@
-const DEFAULT_BUFFER_SECONDS = 300;
 export function serializeCredential(credential) {
     const serialized = {
         accessToken: credential.accessToken,
@@ -41,24 +40,13 @@ export function deserializeCredential(raw) {
 }
 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;
+        return deserializeCredential(raw);
     }
     async set(params) {
         const { providerName, ownerDID, credential, ownerWrappableDID, controllerWrappableDID } = params;
@@ -84,46 +72,4 @@ export class DBCredentialProvider {
     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/lib/refreshing-credential-provider.d.ts

@@ -0,0 +1,50 @@
+import type { Credential, CredentialProvider, OAuthProviderDefinition } from '@kubun/credential-types';
+import type { Logger } from '@kubun/logger';
+import { EventEmitter } from '@sozai/event';
+import type { Runtime } from '@sozai/runtime';
+export type RefreshFailureCategory = 'invalid_grant' | 'transient' | 'configuration' | 'persistence';
+export type RefreshedEvent = {
+    providerName: string;
+    ownerDID: string;
+    scopes: Array<string>;
+    expiresAt: Date | undefined;
+};
+export type RefreshFailedEvent = {
+    providerName: string;
+    ownerDID: string;
+    category: RefreshFailureCategory;
+};
+export type RefreshEvents = {
+    refreshed: RefreshedEvent;
+    refreshFailed: RefreshFailedEvent;
+};
+export type RefreshOutcome = {
+    ok: true;
+    credential: Credential;
+} | {
+    ok: false;
+    category: RefreshFailureCategory;
+};
+export type RefreshingCredentialProviderParams = {
+    inner: CredentialProvider;
+    runtime: Runtime;
+    providers: Array<OAuthProviderDefinition>;
+    bufferSeconds?: number;
+    logger?: Logger;
+    refreshInFlight?: Map<string, Promise<RefreshOutcome>>;
+};
+export declare class RefreshingCredentialProvider implements CredentialProvider {
+    #private;
+    constructor(params: RefreshingCredentialProviderParams);
+    get refreshEvents(): EventEmitter<RefreshEvents>;
+    peek(providerName: string, ownerDID: string): Promise<Credential | null>;
+    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/refreshing-credential-provider.js

@@ -0,0 +1,185 @@
+import { normalizeDID } from '@kokuin/token';
+import { EventEmitter } from '@sozai/event';
+const DEFAULT_BUFFER_SECONDS = 300;
+// Wraps a storage-only `CredentialProvider` and adds transparent OAuth refresh on
+// read: a credential inside the expiry buffer with a refresh token is exchanged
+// for a fresh one and written back through the inner provider. A failed exchange
+// falls back to the stored (stale) credential rather than throwing, and reports
+// the failure category through the `refreshEvents` emitter.
+export class RefreshingCredentialProvider {
+    #inner;
+    #runtime;
+    #providers;
+    #bufferMs;
+    #events;
+    #refreshInFlight;
+    constructor(params){
+        this.#inner = params.inner;
+        this.#runtime = params.runtime;
+        this.#providers = params.providers;
+        this.#bufferMs = (params.bufferSeconds ?? DEFAULT_BUFFER_SECONDS) * 1000;
+        this.#events = new EventEmitter({
+            logger: params.logger
+        });
+        this.#refreshInFlight = params.refreshInFlight ?? new Map();
+    }
+    // Read-only view onto the refresh-outcome emitter. Consumers subscribe to
+    // `refreshed`/`refreshFailed`; emission is owned here.
+    get refreshEvents() {
+        return this.#events;
+    }
+    // Non-refreshing existence read: returns the stored credential straight from the
+    // inner storage provider, skipping the expiry check, token exchange and outcome
+    // emit that `get` performs. A caller testing presence before deletion uses this
+    // so a disconnect never triggers a spurious refresh (and a stray refresh outcome)
+    // immediately before it removes the credential.
+    peek(providerName, ownerDID) {
+        return this.#inner.get(providerName, ownerDID);
+    }
+    async get(providerName, ownerDID) {
+        const credential = await this.#inner.get(providerName, ownerDID);
+        if (credential == null) return null;
+        if (this.#isExpiringSoon(credential) && credential.refreshToken != null) {
+            const refreshed = await this.#refresh(providerName, ownerDID, credential, credential.refreshToken);
+            return refreshed ?? credential;
+        }
+        return credential;
+    }
+    set(params) {
+        return this.#inner.set(params);
+    }
+    delete(providerName, ownerDID) {
+        return this.#inner.delete(providerName, ownerDID);
+    }
+    #isExpiringSoon(credential) {
+        if (credential.expiresAt == null) return false;
+        return credential.expiresAt.getTime() - Date.now() < this.#bufferMs;
+    }
+    // The single point where a refresh outcome is produced. A `null` return is the
+    // stale-fallback signal `get` honours on every failure category.
+    //
+    // Concurrent refreshes of the same provider+owner are collapsed by the shared
+    // single-flight map. The first caller to find no in-flight promise is the
+    // coordinator: it runs the one `#exchange`, stores its promise so overlapping
+    // callers await the same round-trip, and — alone — emits the outcome through
+    // `fire` (never awaited, never rethrown, so no subscriber can break refresh or
+    // `get`). Followers await the coordinator's promise and reuse its outcome for
+    // their own stale-fallback decision without emitting a second event. The key is
+    // normalized so the two `did:peer:4` spellings of one owner share an entry.
+    async #refresh(providerName, ownerDID, credential, refreshToken) {
+        const key = `${providerName}:${normalizeDID(ownerDID)}`;
+        const inFlight = this.#refreshInFlight.get(key);
+        if (inFlight != null) {
+            const outcome = await inFlight;
+            return outcome.ok ? outcome.credential : null;
+        }
+        const exchange = this.#exchange(providerName, ownerDID, credential, refreshToken);
+        this.#refreshInFlight.set(key, exchange);
+        let outcome;
+        try {
+            outcome = await exchange;
+        } finally{
+            this.#refreshInFlight.delete(key);
+        }
+        if (outcome.ok) {
+            this.#events.fire('refreshed', {
+                providerName,
+                ownerDID,
+                scopes: outcome.credential.scopes,
+                expiresAt: outcome.credential.expiresAt
+            });
+            return outcome.credential;
+        }
+        this.#events.fire('refreshFailed', {
+            providerName,
+            ownerDID,
+            category: outcome.category
+        });
+        return null;
+    }
+    // Performs the token exchange and classifies the result. Concurrent callers for
+    // one provider+owner never reach here twice: `#refresh` shares a single pending
+    // `#exchange` promise through the single-flight map. Returns a discriminated
+    // outcome and does not emit or fall back itself.
+    async #exchange(providerName, ownerDID, credential, refreshToken) {
+        const provider = this.#providers.find((p)=>p.name === providerName);
+        if (provider == null || provider.clientID == null || provider.clientSecret == null) {
+            return {
+                ok: false,
+                category: 'configuration'
+            };
+        }
+        let response;
+        try {
+            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
+                })
+            });
+        } catch  {
+            return {
+                ok: false,
+                category: 'transient'
+            };
+        }
+        if (!response.ok) {
+            return {
+                ok: false,
+                category: await this.#classifyErrorResponse(response)
+            };
+        }
+        let tokenData;
+        try {
+            tokenData = await response.json();
+        } catch  {
+            return {
+                ok: false,
+                category: 'transient'
+            };
+        }
+        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
+        };
+        try {
+            await this.#inner.set({
+                providerName,
+                ownerDID,
+                credential: refreshed
+            });
+        } catch  {
+            return {
+                ok: false,
+                category: 'persistence'
+            };
+        }
+        return {
+            ok: true,
+            credential: refreshed
+        };
+    }
+    // Distinguishes a confirmed OAuth invalidation from a generic non-OK status.
+    // The standard OAuth2 error response is `{ "error": "invalid_grant", ... }` in
+    // the JSON body of a 400; anything else — including an empty or non-JSON body —
+    // is treated as transient so a stale-but-valid token is never abandoned.
+    async #classifyErrorResponse(response) {
+        try {
+            const body = await response.json();
+            if (body?.error === 'invalid_grant') return 'invalid_grant';
+        } catch  {
+        // Empty or non-JSON error body: cannot confirm invalidation.
+        }
+        return 'transient';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/credential",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -26,6 +26,7 @@
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
     "@sozai/codec": "^0.4.0",
+    "@sozai/event": "^0.1.3",
     "@sozai/runtime": "^0.1.0"
   },
   "devDependencies": {