@honua/react 0.0.20-alpha.0 → 0.1.1-beta.0

package/core/auth/credential-store.js

@@ -0,0 +1,82 @@
+/**
+ * {@link CredentialStore} implementations.
+ *
+ * - {@link InMemoryCredentialStore} — the default. Tokens live only in the JS
+ *   heap and vanish on reload; nothing else on the origin can read them.
+ * - {@link sessionStorageCredentialStore} / {@link localStorageCredentialStore}
+ *   — explicit opt-in Web Storage adapters. Web Storage is readable by **any**
+ *   script executing on the origin, so a single XSS bug can exfiltrate every
+ *   stored token. Only enable them when you understand and accept that risk
+ *   (see `docs/auth.md` → "Storage & security"). `localStorage` additionally
+ *   persists across tabs/restarts, widening the exposure window.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Default credential store. Holds credentials in a process-local `Map` — never
+ * serialized, never shared across origins, cleared on reload.
+ */
+export class InMemoryCredentialStore {
+    entries = new Map();
+    get(key) {
+        return this.entries.get(key);
+    }
+    set(key, value) {
+        this.entries.set(key, value);
+    }
+    delete(key) {
+        this.entries.delete(key);
+    }
+}
+class WebStorageCredentialStore {
+    namespace;
+    resolveStorage;
+    constructor(kind, options) {
+        this.namespace = options.namespace ?? "honua.auth";
+        this.resolveStorage = () => {
+            if (options.storage) {
+                return options.storage;
+            }
+            const storage = kind === "session" ? globalThis.sessionStorage : globalThis.localStorage;
+            if (!storage) {
+                throw new Error(`${kind}Storage is unavailable in this environment. Pass an explicit \`storage\` adapter or use the in-memory store.`);
+            }
+            return storage;
+        };
+    }
+    storageKey(key) {
+        return `${this.namespace}:${key}`;
+    }
+    get(key) {
+        const raw = this.resolveStorage().getItem(this.storageKey(key));
+        if (!raw) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    set(key, value) {
+        this.resolveStorage().setItem(this.storageKey(key), JSON.stringify(value));
+    }
+    delete(key) {
+        this.resolveStorage().removeItem(this.storageKey(key));
+    }
+}
+/**
+ * `sessionStorage`-backed credential store (per-tab, cleared when the tab
+ * closes). Opt-in: see the module-level security note before using it.
+ */
+export function sessionStorageCredentialStore(options = {}) {
+    return new WebStorageCredentialStore("session", options);
+}
+/**
+ * `localStorage`-backed credential store (persists across tabs and restarts).
+ * Highest-risk option — opt-in only. See the module-level security note.
+ */
+export function localStorageCredentialStore(options = {}) {
+    return new WebStorageCredentialStore("local", options);
+}

package/core/auth/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@honua/sdk-js/auth` — pluggable {@link HonuaAuthProvider} built-ins and the
+ * {@link CredentialStore} abstraction.
+ *
+ * These providers plug into `new HonuaClient({ auth })` and are therefore
+ * attached and refreshed transparently across **all** transports the client
+ * drives — every REST fetch path and every gRPC-web call (the client's auth
+ * interceptor re-resolves credentials per attempt), plus the 401/403
+ * force-refresh retry.
+ *
+ * This module is a dedicated subpath so a `HonuaClient`-only consumer never
+ * pays the PKCE/token-exchange code size unless they opt in.
+ *
+ * @packageDocumentation
+ */
+export { oauth2, OAuth2Provider } from "./oauth2-provider.js";
+export { clientCredentials, ClientCredentialsProvider } from "./client-credentials-provider.js";
+export { apiKeyAuth, bearerTokenAuth } from "./static-providers.js";
+export { InMemoryCredentialStore, sessionStorageCredentialStore, localStorageCredentialStore, } from "./credential-store.js";
+export { createPkcePair, createStateToken } from "./pkce.js";
+export type { PkcePair } from "./pkce.js";
+export type { ClientCredentialsConfig, CredentialStore, HonuaAuthEvent, HonuaAuthEventHandle, HonuaAuthEventListener, OAuth2Config, OAuth2SignInMode, OAuth2TokenResponse, StoredCredential, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/core/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAChG,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7D,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EACV,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/core/auth/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@honua/sdk-js/auth` — pluggable {@link HonuaAuthProvider} built-ins and the
+ * {@link CredentialStore} abstraction.
+ *
+ * These providers plug into `new HonuaClient({ auth })` and are therefore
+ * attached and refreshed transparently across **all** transports the client
+ * drives — every REST fetch path and every gRPC-web call (the client's auth
+ * interceptor re-resolves credentials per attempt), plus the 401/403
+ * force-refresh retry.
+ *
+ * This module is a dedicated subpath so a `HonuaClient`-only consumer never
+ * pays the PKCE/token-exchange code size unless they opt in.
+ *
+ * @packageDocumentation
+ */
+export { oauth2, OAuth2Provider } from "./oauth2-provider.js";
+export { clientCredentials, ClientCredentialsProvider } from "./client-credentials-provider.js";
+export { apiKeyAuth, bearerTokenAuth } from "./static-providers.js";
+export { InMemoryCredentialStore, sessionStorageCredentialStore, localStorageCredentialStore, } from "./credential-store.js";
+export { createPkcePair, createStateToken } from "./pkce.js";

package/core/auth/oauth2-provider.d.ts

@@ -0,0 +1,114 @@
+/**
+ * OAuth2 authorization-code + PKCE provider.
+ *
+ * Implements {@link HonuaAuthProvider} (so it drops straight into
+ * `new HonuaClient({ auth })` and is attached/refreshed on every fetch and
+ * gRPC-web call) *and* exposes the interactive surface a browser app drives:
+ * `signIn()` (redirect or popup), `handleRedirectCallback()`, `signOut()`.
+ *
+ * Design highlights:
+ * - S256 PKCE + unguessable `state` (CSRF), validated on the redirect.
+ * - Silent refresh via `refresh_token` with a documented fallback
+ *   (`interaction_required`) when no refresh token is available.
+ * - Clock-skew-tolerant expiry so a refresh happens *before* requests 401.
+ * - **Single-flight refresh**: N concurrent `getCredentials()` calls that all
+ *   observe an expiring token share exactly one token-endpoint round-trip.
+ *
+ * @packageDocumentation
+ */
+import type { HonuaAuthCredentials, HonuaAuthProviderContext, HonuaAuthRevocationContext } from "../types.js";
+import type { HonuaAuthEventHandle, HonuaAuthEventListener, OAuth2Config, StoredCredential } from "./types.js";
+/**
+ * OAuth2 authorization-code + PKCE provider. Construct via {@link oauth2}.
+ */
+export declare class OAuth2Provider {
+    private readonly config;
+    private readonly store;
+    private readonly serviceKey;
+    private readonly clockSkewMs;
+    private readonly mode;
+    private readonly fetchFn;
+    private readonly listeners;
+    /** Single-flight guard: one in-flight refresh shared by all callers. */
+    private refreshInFlight;
+    /** In-memory transaction fallback when no Web Storage is available. */
+    private memoryTransaction;
+    constructor(config: OAuth2Config);
+    /**
+     * Resolve credentials for an outgoing request. Returns the current access
+     * token, silently refreshing it first when it is expiring (or when
+     * `context.forceRefresh` is set, e.g. after a 401). Throws
+     * {@link HonuaAuthError} `interaction_required` when there is no token and no
+     * refresh token — the app must call {@link OAuth2Provider.signIn}.
+     */
+    getCredentials(context?: HonuaAuthProviderContext): Promise<HonuaAuthCredentials | undefined>;
+    /** {@link HonuaAuthProvider.revokeCredentials} — clears + optionally revokes. */
+    revokeCredentials(_credentials: HonuaAuthCredentials, _context: HonuaAuthRevocationContext): Promise<void>;
+    /**
+     * Start interactive sign-in. In `redirect` mode this navigates the current
+     * window to the authorization endpoint and returns a promise that never
+     * resolves (the page unloads); complete the flow by calling
+     * {@link OAuth2Provider.handleRedirectCallback} when the app reloads at the
+     * redirect URI. In `popup` mode it opens a popup, waits for the redirect back,
+     * exchanges the code, and resolves with the stored credential.
+     */
+    signIn(): Promise<StoredCredential | undefined>;
+    /**
+     * Whether `url` (or the current window location) looks like an OAuth2 redirect
+     * callback (carries `code`+`state` or an `error`). Call this on app load to
+     * decide whether to invoke {@link OAuth2Provider.handleRedirectCallback}.
+     */
+    isRedirectCallback(url?: string): boolean;
+    /**
+     * Complete the redirect leg: validate `state`, exchange the authorization
+     * `code` (+ PKCE verifier) for tokens, persist them, and emit `signed-in`.
+     */
+    handleRedirectCallback(url?: string): Promise<StoredCredential>;
+    /** Whether a (non-expired) credential is currently stored. */
+    isSignedIn(): Promise<boolean>;
+    /** Read the raw stored credential, if any. */
+    getStoredCredential(): StoredCredential | undefined | Promise<StoredCredential | undefined>;
+    /** Clear stored credentials, optionally revoke them, and emit `signed-out`. */
+    signOut(): Promise<void>;
+    /** Register an auth lifecycle listener. */
+    on(listener: HonuaAuthEventListener): HonuaAuthEventHandle;
+    private refreshSingleFlight;
+    private doRefresh;
+    private exchangeCode;
+    private revokeAtEndpoint;
+    private buildAuthorizeUrl;
+    private signInPopup;
+    private parseUrl;
+    private getWindow;
+    private requireWindow;
+    private transactionKey;
+    private sessionStorage;
+    private saveTransaction;
+    private loadTransaction;
+    private clearTransaction;
+    private emit;
+}
+/**
+ * Create an OAuth2 authorization-code + PKCE {@link HonuaAuthProvider}.
+ *
+ * @example
+ * ```ts
+ * import { HonuaClient } from "@honua/sdk-js/honua";
+ * import { oauth2 } from "@honua/sdk-js/auth";
+ *
+ * const auth = oauth2({
+ *   authorizationEndpoint: "https://idp.example/authorize",
+ *   tokenEndpoint: "https://idp.example/token",
+ *   clientId: "my-app",
+ *   redirectUri: `${location.origin}/callback`,
+ *   scopes: ["openid", "profile"],
+ * });
+ * const client = new HonuaClient({ baseUrl: "https://api.example", auth });
+ *
+ * // On the callback page:
+ * if (auth.isRedirectCallback()) await auth.handleRedirectCallback();
+ * else if (!(await auth.isSignedIn())) await auth.signIn();
+ * ```
+ */
+export declare function oauth2(config: OAuth2Config): OAuth2Provider;
+//# sourceMappingURL=oauth2-provider.d.ts.map

package/core/auth/oauth2-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-provider.d.ts","sourceRoot":"","sources":["../../../../src/core/auth/oauth2-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAU9G,OAAO,KAAK,EAGV,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EAEZ,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAWpB;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,wEAAwE;IACxE,OAAO,CAAC,eAAe,CAAwC;IAC/D,uEAAuE;IACvE,OAAO,CAAC,iBAAiB,CAA8B;gBAEpC,MAAM,EAAE,YAAY;IAcvC;;;;;;OAMG;IACU,cAAc,CACzB,OAAO,GAAE,wBAAoE,GAC5E,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC;IAkB5C,iFAAiF;IACpE,iBAAiB,CAC5B,YAAY,EAAE,oBAAoB,EAClC,QAAQ,EAAE,0BAA0B,GACnC,OAAO,CAAC,IAAI,CAAC;IAMhB;;;;;;;OAOG;IACU,MAAM,IAAI,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAsB5D;;;;OAIG;IACI,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO;IAQhD;;;OAGG;IACU,sBAAsB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsC5E,8DAA8D;IACjD,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAK3C,8CAA8C;IACvC,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAIlG,+EAA+E;IAClE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAarC,2CAA2C;IACpC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,GAAG,oBAAoB;IAWjE,OAAO,CAAC,mBAAmB;YAab,SAAS;YAmCT,YAAY;YAeZ,gBAAgB;IAa9B,OAAO,CAAC,iBAAiB;YAkBX,WAAW;IA6CzB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,IAAI;CASb;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAE3D"}

package/core/auth/oauth2-provider.js

@@ -0,0 +1,408 @@
+/**
+ * OAuth2 authorization-code + PKCE provider.
+ *
+ * Implements {@link HonuaAuthProvider} (so it drops straight into
+ * `new HonuaClient({ auth })` and is attached/refreshed on every fetch and
+ * gRPC-web call) *and* exposes the interactive surface a browser app drives:
+ * `signIn()` (redirect or popup), `handleRedirectCallback()`, `signOut()`.
+ *
+ * Design highlights:
+ * - S256 PKCE + unguessable `state` (CSRF), validated on the redirect.
+ * - Silent refresh via `refresh_token` with a documented fallback
+ *   (`interaction_required`) when no refresh token is available.
+ * - Clock-skew-tolerant expiry so a refresh happens *before* requests 401.
+ * - **Single-flight refresh**: N concurrent `getCredentials()` calls that all
+ *   observe an expiring token share exactly one token-endpoint round-trip.
+ *
+ * @packageDocumentation
+ */
+import { HonuaAuthError } from "../errors.js";
+import { InMemoryCredentialStore } from "./credential-store.js";
+import { createPkcePair, createStateToken } from "./pkce.js";
+import { DEFAULT_CLOCK_SKEW_MS, isCredentialExpiring, requestToken, resolveServiceKey, toHonuaCredentials, } from "./token-endpoint.js";
+const TRANSACTION_NAMESPACE = "honua.auth.txn";
+/**
+ * OAuth2 authorization-code + PKCE provider. Construct via {@link oauth2}.
+ */
+export class OAuth2Provider {
+    config;
+    store;
+    serviceKey;
+    clockSkewMs;
+    mode;
+    fetchFn;
+    listeners = new Set();
+    /** Single-flight guard: one in-flight refresh shared by all callers. */
+    refreshInFlight;
+    /** In-memory transaction fallback when no Web Storage is available. */
+    memoryTransaction;
+    constructor(config) {
+        this.config = config;
+        this.store = config.store ?? new InMemoryCredentialStore();
+        this.serviceKey = resolveServiceKey(config.serviceKey, config.clientId, config.tokenEndpoint);
+        this.clockSkewMs = config.clockSkewMs ?? DEFAULT_CLOCK_SKEW_MS;
+        this.mode = config.mode ?? "redirect";
+        this.fetchFn = (config.fetchFn ?? fetch).bind(globalThis);
+        if (config.onEvent) {
+            this.listeners.add(config.onEvent);
+        }
+    }
+    // ── HonuaAuthProvider surface ────────────────────────────────
+    /**
+     * Resolve credentials for an outgoing request. Returns the current access
+     * token, silently refreshing it first when it is expiring (or when
+     * `context.forceRefresh` is set, e.g. after a 401). Throws
+     * {@link HonuaAuthError} `interaction_required` when there is no token and no
+     * refresh token — the app must call {@link OAuth2Provider.signIn}.
+     */
+    async getCredentials(context = { reason: "manual", forceRefresh: false }) {
+        const current = await this.store.get(this.serviceKey);
+        const needsRefresh = context.forceRefresh || isCredentialExpiring(current, this.clockSkewMs);
+        if (!needsRefresh && current) {
+            return toHonuaCredentials(current);
+        }
+        if (current?.refreshToken) {
+            const refreshed = await this.refreshSingleFlight(current);
+            return toHonuaCredentials(refreshed);
+        }
+        throw new HonuaAuthError("interaction_required", current
+            ? "Access token expired and no refresh token is available; call signIn() to re-authenticate."
+            : "No credential available; call signIn() to start the OAuth2 authorization-code flow.");
+    }
+    /** {@link HonuaAuthProvider.revokeCredentials} — clears + optionally revokes. */
+    async revokeCredentials(_credentials, _context) {
+        await this.signOut();
+    }
+    // ── Interactive flow ─────────────────────────────────────────
+    /**
+     * Start interactive sign-in. In `redirect` mode this navigates the current
+     * window to the authorization endpoint and returns a promise that never
+     * resolves (the page unloads); complete the flow by calling
+     * {@link OAuth2Provider.handleRedirectCallback} when the app reloads at the
+     * redirect URI. In `popup` mode it opens a popup, waits for the redirect back,
+     * exchanges the code, and resolves with the stored credential.
+     */
+    async signIn() {
+        const pkce = await createPkcePair();
+        const state = createStateToken();
+        const transaction = {
+            codeVerifier: pkce.codeVerifier,
+            state,
+            redirectUri: this.config.redirectUri,
+            createdAt: Date.now(),
+        };
+        const authorizeUrl = this.buildAuthorizeUrl(pkce, state);
+        if (this.mode === "popup") {
+            return this.signInPopup(authorizeUrl, transaction);
+        }
+        this.saveTransaction(transaction);
+        const win = this.requireWindow();
+        win.location.assign(authorizeUrl);
+        // The redirect unloads the page; never resolves.
+        return new Promise(() => { });
+    }
+    /**
+     * Whether `url` (or the current window location) looks like an OAuth2 redirect
+     * callback (carries `code`+`state` or an `error`). Call this on app load to
+     * decide whether to invoke {@link OAuth2Provider.handleRedirectCallback}.
+     */
+    isRedirectCallback(url) {
+        const target = this.parseUrl(url);
+        if (!target) {
+            return false;
+        }
+        return target.searchParams.has("error") || (target.searchParams.has("code") && target.searchParams.has("state"));
+    }
+    /**
+     * Complete the redirect leg: validate `state`, exchange the authorization
+     * `code` (+ PKCE verifier) for tokens, persist them, and emit `signed-in`.
+     */
+    async handleRedirectCallback(url) {
+        const target = this.parseUrl(url);
+        if (!target) {
+            throw new HonuaAuthError("interaction_required", "No redirect callback URL is available to process.");
+        }
+        const params = target.searchParams;
+        const authError = params.get("error");
+        if (authError) {
+            const description = params.get("error_description");
+            this.clearTransaction();
+            throw new HonuaAuthError("invalid_grant", `Authorization server returned an error: ${authError}${description ? ` (${description})` : ""}`);
+        }
+        const code = params.get("code");
+        const state = params.get("state");
+        if (!code) {
+            throw new HonuaAuthError("interaction_required", "Redirect callback is missing the authorization code.");
+        }
+        const transaction = this.loadTransaction();
+        if (!transaction) {
+            throw new HonuaAuthError("interaction_required", "No PKCE transaction is in progress; start sign-in with signIn() first.");
+        }
+        if (!state || state !== transaction.state) {
+            this.clearTransaction();
+            throw new HonuaAuthError("invalid_grant", "OAuth2 state mismatch on redirect callback (possible CSRF).");
+        }
+        const credential = await this.exchangeCode(code, transaction);
+        await this.store.set(this.serviceKey, credential);
+        this.clearTransaction();
+        this.emit({ type: "signed-in", credential });
+        return credential;
+    }
+    /** Whether a (non-expired) credential is currently stored. */
+    async isSignedIn() {
+        const current = await this.store.get(this.serviceKey);
+        return current !== undefined && !isCredentialExpiring(current, 0);
+    }
+    /** Read the raw stored credential, if any. */
+    getStoredCredential() {
+        return this.store.get(this.serviceKey);
+    }
+    /** Clear stored credentials, optionally revoke them, and emit `signed-out`. */
+    async signOut() {
+        const current = await this.store.get(this.serviceKey);
+        await this.store.delete(this.serviceKey);
+        this.clearTransaction();
+        this.refreshInFlight = undefined;
+        if (current && this.config.revocationEndpoint) {
+            await this.revokeAtEndpoint(current).catch(() => {
+                // Best-effort revocation; local sign-out already succeeded.
+            });
+        }
+        this.emit({ type: "signed-out" });
+    }
+    /** Register an auth lifecycle listener. */
+    on(listener) {
+        this.listeners.add(listener);
+        return {
+            remove: () => {
+                this.listeners.delete(listener);
+            },
+        };
+    }
+    // ── internals ────────────────────────────────────────────────
+    refreshSingleFlight(current) {
+        if (this.refreshInFlight) {
+            return this.refreshInFlight;
+        }
+        const inFlight = this.doRefresh(current).finally(() => {
+            if (this.refreshInFlight === inFlight) {
+                this.refreshInFlight = undefined;
+            }
+        });
+        this.refreshInFlight = inFlight;
+        return inFlight;
+    }
+    async doRefresh(current) {
+        const refreshToken = current.refreshToken;
+        if (!refreshToken) {
+            throw new HonuaAuthError("interaction_required", "No refresh token is available; call signIn().");
+        }
+        try {
+            const refreshed = await requestToken({
+                fetchFn: this.fetchFn,
+                tokenEndpoint: this.config.tokenEndpoint,
+                params: {
+                    grant_type: "refresh_token",
+                    refresh_token: refreshToken,
+                    client_id: this.config.clientId,
+                    ...(this.config.scopes && this.config.scopes.length > 0 ? { scope: this.config.scopes.join(" ") } : {}),
+                    ...this.config.extraTokenParams,
+                },
+                previous: current,
+            });
+            await this.store.set(this.serviceKey, refreshed);
+            this.emit({ type: "token-refreshed", credential: refreshed });
+            return refreshed;
+        }
+        catch (error) {
+            if (error instanceof HonuaAuthError) {
+                this.emit({ type: "refresh-failed", error });
+                if (error.code === "invalid_grant") {
+                    // The refresh token is dead; drop it so the next call surfaces
+                    // interaction_required instead of looping on a doomed refresh.
+                    await this.store.delete(this.serviceKey);
+                    this.emit({ type: "signed-out" });
+                }
+            }
+            throw error;
+        }
+    }
+    async exchangeCode(code, transaction) {
+        return requestToken({
+            fetchFn: this.fetchFn,
+            tokenEndpoint: this.config.tokenEndpoint,
+            params: {
+                grant_type: "authorization_code",
+                code,
+                redirect_uri: transaction.redirectUri,
+                client_id: this.config.clientId,
+                code_verifier: transaction.codeVerifier,
+                ...this.config.extraTokenParams,
+            },
+        });
+    }
+    async revokeAtEndpoint(credential) {
+        const endpoint = this.config.revocationEndpoint;
+        if (!endpoint) {
+            return;
+        }
+        const token = credential.refreshToken ?? credential.accessToken;
+        await this.fetchFn(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({ token, client_id: this.config.clientId }).toString(),
+        });
+    }
+    buildAuthorizeUrl(pkce, state) {
+        const url = new URL(this.config.authorizationEndpoint);
+        const params = url.searchParams;
+        params.set("response_type", "code");
+        params.set("client_id", this.config.clientId);
+        params.set("redirect_uri", this.config.redirectUri);
+        params.set("state", state);
+        params.set("code_challenge", pkce.codeChallenge);
+        params.set("code_challenge_method", pkce.codeChallengeMethod);
+        if (this.config.scopes && this.config.scopes.length > 0) {
+            params.set("scope", this.config.scopes.join(" "));
+        }
+        for (const [key, value] of Object.entries(this.config.extraAuthorizationParams ?? {})) {
+            params.set(key, value);
+        }
+        return url.toString();
+    }
+    async signInPopup(authorizeUrl, transaction) {
+        const win = this.requireWindow();
+        const popup = win.open(authorizeUrl, "honua-oauth", this.config.popupFeatures ?? "width=480,height=680");
+        if (!popup) {
+            throw new HonuaAuthError("interaction_required", "The sign-in popup was blocked by the browser.");
+        }
+        const redirectOrigin = new URL(transaction.redirectUri, win.location?.href ?? transaction.redirectUri).origin;
+        const callback = await new Promise((resolve, reject) => {
+            const timer = setInterval(() => {
+                try {
+                    if (popup.closed) {
+                        clearInterval(timer);
+                        reject(new HonuaAuthError("interaction_required", "The sign-in popup was closed before completing sign-in."));
+                        return;
+                    }
+                    let popupUrl;
+                    try {
+                        popupUrl = new URL(popup.location.href);
+                    }
+                    catch {
+                        // Cross-origin while on the authorization server — not readable yet.
+                        return;
+                    }
+                    if (popupUrl.origin === redirectOrigin && popupUrl.searchParams.has("code")) {
+                        clearInterval(timer);
+                        const code = popupUrl.searchParams.get("code") ?? "";
+                        const state = popupUrl.searchParams.get("state") ?? "";
+                        popup.close();
+                        resolve({ code, state });
+                    }
+                }
+                catch {
+                    // Ignore transient cross-origin access errors during the auth leg.
+                }
+            }, 200);
+        });
+        if (!callback.state || callback.state !== transaction.state) {
+            throw new HonuaAuthError("invalid_grant", "OAuth2 state mismatch on popup callback (possible CSRF).");
+        }
+        const credential = await this.exchangeCode(callback.code, transaction);
+        await this.store.set(this.serviceKey, credential);
+        this.emit({ type: "signed-in", credential });
+        return credential;
+    }
+    parseUrl(url) {
+        const href = url ?? this.getWindow()?.location?.href;
+        if (!href) {
+            return undefined;
+        }
+        try {
+            return new URL(href);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    getWindow() {
+        return this.config.windowRef ?? globalThis.window;
+    }
+    requireWindow() {
+        const win = this.getWindow();
+        if (!win) {
+            throw new HonuaAuthError("interaction_required", "Interactive OAuth2 sign-in requires a browser window; none is available in this environment.");
+        }
+        return win;
+    }
+    transactionKey() {
+        return `${TRANSACTION_NAMESPACE}:${this.serviceKey}`;
+    }
+    sessionStorage() {
+        return this.getWindow()?.sessionStorage;
+    }
+    saveTransaction(transaction) {
+        const storage = this.sessionStorage();
+        if (storage) {
+            storage.setItem(this.transactionKey(), JSON.stringify(transaction));
+            return;
+        }
+        this.memoryTransaction = transaction;
+    }
+    loadTransaction() {
+        const storage = this.sessionStorage();
+        if (storage) {
+            const raw = storage.getItem(this.transactionKey());
+            if (!raw) {
+                return undefined;
+            }
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return this.memoryTransaction;
+    }
+    clearTransaction() {
+        this.sessionStorage()?.removeItem(this.transactionKey());
+        this.memoryTransaction = undefined;
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listener errors must not break the auth flow.
+            }
+        }
+    }
+}
+/**
+ * Create an OAuth2 authorization-code + PKCE {@link HonuaAuthProvider}.
+ *
+ * @example
+ * ```ts
+ * import { HonuaClient } from "@honua/sdk-js/honua";
+ * import { oauth2 } from "@honua/sdk-js/auth";
+ *
+ * const auth = oauth2({
+ *   authorizationEndpoint: "https://idp.example/authorize",
+ *   tokenEndpoint: "https://idp.example/token",
+ *   clientId: "my-app",
+ *   redirectUri: `${location.origin}/callback`,
+ *   scopes: ["openid", "profile"],
+ * });
+ * const client = new HonuaClient({ baseUrl: "https://api.example", auth });
+ *
+ * // On the callback page:
+ * if (auth.isRedirectCallback()) await auth.handleRedirectCallback();
+ * else if (!(await auth.isSignedIn())) await auth.signIn();
+ * ```
+ */
+export function oauth2(config) {
+    return new OAuth2Provider(config);
+}