@deque/axe-auth 1.1.0-next.6ad261c8 → 1.1.0-next.759bd5c5

package/dist/oauth/errors.d.ts

@@ -1,3 +1,4 @@
+/** Error codes raised by the loopback callback server. */
 export type OAuthCallbackErrorCode = 
 /** No callback arrived within `timeoutMs`; a retry is reasonable. */
 "TIMEOUT"
@@ -11,12 +12,64 @@ export type OAuthCallbackErrorCode =
  | "BIND_FAILED"
 /** Caller's `AbortSignal` fired. Expected; no user-facing message. */
  | "ABORTED";
-export type OAuthCallbackErrorOptions = {
+/** Options for `OAuthCallbackError`. */
+export interface OAuthCallbackErrorOptions {
+    /** Structured metadata for callers that want to surface specific fields. */
     details?: Record<string, string>;
+    /** Underlying error that triggered this failure. */
     cause?: unknown;
-};
+}
+/**
+ * Error raised by the loopback callback server when the authorization
+ * response cannot be consumed (timeout, state mismatch, provider error,
+ * malformed response, bind failure, or caller abort).
+ */
 export declare class OAuthCallbackError extends Error {
+    /** Discriminator for programmatic handling. */
     readonly code: OAuthCallbackErrorCode;
+    /** Structured metadata carried alongside the error, if any. */
     readonly details?: Record<string, string>;
     constructor(code: OAuthCallbackErrorCode, message: string, options?: OAuthCallbackErrorOptions);
 }
+/** Error codes raised by the OAuth flow orchestrator and its helpers. */
+export type OAuthFlowErrorCode = 
+/** OIDC discovery could not reach or parse the authorization server. No browser was opened. */
+"DISCOVERY_FAILED"
+/** Could not launch the system browser. User should be told to open the URL manually. */
+ | "BROWSER_LAUNCH_FAILED"
+/** Authorization code → token exchange was rejected by the authorization server. */
+ | "TOKEN_EXCHANGE_FAILED"
+/** System keychain is unavailable (e.g. no D-Bus secret service on Linux). */
+ | "KEYRING_UNAVAILABLE"
+/** Authorization endpoint returned by discovery cannot be used (e.g. already carries an OAuth-required param). Server misconfiguration. */
+ | "INVALID_AUTHORIZATION_ENDPOINT"
+/** No usable stored credentials; the user needs to run `login` to re-authenticate. Covers empty / corrupt / version-mismatched store and refresh tokens the authorization server has revoked. */
+ | "NOT_AUTHENTICATED";
+/** Options for `OAuthFlowError`. */
+export interface OAuthFlowErrorOptions {
+    /** Structured metadata for callers that want to surface specific fields. */
+    details?: Record<string, string>;
+    /** Underlying error that triggered this failure. */
+    cause?: unknown;
+}
+/**
+ * Error raised by anything in the OAuth flow outside the callback
+ * server itself: OIDC discovery, browser launch, token exchange, or
+ * keychain access.
+ *
+ * **Logging note.** For code `TOKEN_EXCHANGE_FAILED`, `message` may
+ * include the authorization server's `error_description`, which is
+ * free-form text the server controls and could plausibly contain
+ * user-identifying or otherwise sensitive information. Prefer
+ * structured logging via the discriminated `code` and the explicit
+ * `details` fields; avoid echoing the raw `message` (or the result
+ * of `console.error(err)`, which includes it) into shared log sinks
+ * without a redaction step.
+ */
+export declare class OAuthFlowError extends Error {
+    /** Discriminator for programmatic handling. */
+    readonly code: OAuthFlowErrorCode;
+    /** Structured metadata carried alongside the error, if any. */
+    readonly details?: Record<string, string>;
+    constructor(code: OAuthFlowErrorCode, message: string, options?: OAuthFlowErrorOptions);
+}

package/dist/oauth/errors.js

@@ -1,8 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OAuthCallbackError = void 0;
+exports.OAuthFlowError = exports.OAuthCallbackError = void 0;
+/**
+ * Error raised by the loopback callback server when the authorization
+ * response cannot be consumed (timeout, state mismatch, provider error,
+ * malformed response, bind failure, or caller abort).
+ */
 class OAuthCallbackError extends Error {
+    /** Discriminator for programmatic handling. */
     code;
+    /** Structured metadata carried alongside the error, if any. */
     details;
     constructor(code, message, options = {}) {
         super(message, { cause: options.cause });
@@ -12,3 +19,30 @@ class OAuthCallbackError extends Error {
     }
 }
 exports.OAuthCallbackError = OAuthCallbackError;
+/**
+ * Error raised by anything in the OAuth flow outside the callback
+ * server itself: OIDC discovery, browser launch, token exchange, or
+ * keychain access.
+ *
+ * **Logging note.** For code `TOKEN_EXCHANGE_FAILED`, `message` may
+ * include the authorization server's `error_description`, which is
+ * free-form text the server controls and could plausibly contain
+ * user-identifying or otherwise sensitive information. Prefer
+ * structured logging via the discriminated `code` and the explicit
+ * `details` fields; avoid echoing the raw `message` (or the result
+ * of `console.error(err)`, which includes it) into shared log sinks
+ * without a redaction step.
+ */
+class OAuthFlowError extends Error {
+    /** Discriminator for programmatic handling. */
+    code;
+    /** Structured metadata carried alongside the error, if any. */
+    details;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = "OAuthFlowError";
+        this.code = code;
+        this.details = options.details;
+    }
+}
+exports.OAuthFlowError = OAuthFlowError;

package/dist/oauth/getValidAccessToken.d.ts

@@ -0,0 +1,89 @@
+import { type LoadResult, type TokenStore } from "./tokenStore";
+/** Options for `getValidAccessToken`. */
+export interface GetValidAccessTokenOptions {
+    /**
+     * OIDC issuer URL (same value passed to `authorize`). Must match
+     * the stored entry's `issuerURL`; mismatch throws
+     * `OAuthFlowError("NOT_AUTHENTICATED", ...)` rather than refreshing
+     * the wrong issuer's tokens at the requested endpoint.
+     */
+    issuerURL: string;
+    /**
+     * OAuth client identifier. Must match the stored entry's
+     * `clientId`; see the note on `issuerURL` for the mismatch
+     * behavior.
+     */
+    clientId: string;
+    /**
+     * How close to expiry we start preemptively refreshing, in
+     * milliseconds. Defaults to 60_000 (60s). The buffer gives headroom
+     * between our "still fresh enough" check and the server's view of
+     * expiry (which may differ by a few seconds of clock skew) and
+     * prevents a token from expiring mid-request after we hand it out.
+     *
+     * Assumes the access-token TTL is much larger than the buffer. With
+     * TTLs ≤ `expiryBufferMs`, every call will trigger a refresh.
+     */
+    expiryBufferMs?: number;
+    /**
+     * Override for the token store. Defaults to a fresh
+     * `KeyringTokenStore()` (single keychain entry per machine).
+     */
+    tokenStore?: TokenStore;
+    /**
+     * Pre-loaded result of `tokenStore.load()`. When provided, the
+     * function skips its own keychain read and uses this value
+     * instead — lets a caller that already loaded the entry (the CLI
+     * dispatcher does, to derive `parseCommonArgs` defaults) avoid a
+     * redundant second read on the hot path. The same `tokenStore` is
+     * still used for the post-refresh `save()` and the
+     * `invalid_grant` `clear()`.
+     */
+    loadedEntry?: LoadResult;
+    /** Aborts discovery + the refresh POST when fired. */
+    signal?: AbortSignal;
+    /**
+     * Forwarded to discovery. Loopback issuers are always permitted
+     * over http; this flag is the opt-in for non-loopback http.
+     */
+    allowInsecureIssuer?: boolean;
+    /**
+     * Called for soft warnings that are not errors but warrant user
+     * attention (e.g. a fresh `TokenSet` could not be written to the
+     * keychain, stranding the rotated refresh token — see the hazard
+     * note in the body of `getValidAccessToken`). The default prints
+     * to stderr only when stderr is a TTY. Pass a custom handler to
+     * route warnings through your own UI, or `() => {}` to suppress.
+     */
+    onWarning?: (message: string) => void;
+    /** Source of `now`. Defaults to `Date.now`. Injected for test determinism. */
+    now?: () => number;
+}
+/**
+ * Returns a currently-valid access token string for the given issuer,
+ * refreshing via the stored refresh token if the cached access token
+ * is within `expiryBufferMs` of expiring (or already expired).
+ *
+ * Throws `OAuthFlowError("NOT_AUTHENTICATED", ...)` when the user
+ * must re-run `axe-auth login` — covers an empty / corrupt /
+ * version-mismatched store, an expired access token with no refresh
+ * token to rotate with, and a refresh attempt rejected with
+ * `invalid_grant` (which also clears the stored tokens).
+ *
+ * Throws `OAuthFlowError("TOKEN_EXCHANGE_FAILED", ...)` for transient
+ * failures during refresh (network errors, 5xx, malformed responses)
+ * and leaves the stored tokens intact so a retry is possible.
+ *
+ * Throws `OAuthFlowError("DISCOVERY_FAILED", ...)` when the issuer
+ * URL cannot be reached or parsed at refresh time.
+ *
+ * **Concurrency note.** Not safe against parallel invocations for
+ * the same issuer. Keycloak rotates refresh tokens by default; if
+ * two parallel calls both land on the refresh path, only one
+ * winner's rotated refresh token will be persisted and the loser's
+ * rotated token is stranded. The intended consumer is the
+ * `axe-auth token` CLI (a one-shot), so this is fine in context;
+ * per-request callers should wrap in an in-flight-Promise singleton
+ * keyed by issuer.
+ */
+export declare function getValidAccessToken(options: GetValidAccessTokenOptions): Promise<string>;

package/dist/oauth/getValidAccessToken.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValidAccessToken = getValidAccessToken;
+const discoverOIDC_1 = require("./discoverOIDC");
+const errors_1 = require("./errors");
+const refreshTokens_1 = require("./refreshTokens");
+const tokenStore_1 = require("./tokenStore");
+const DEFAULT_EXPIRY_BUFFER_MS = 60_000;
+function defaultOnWarning(message) {
+    if (process.stderr.isTTY) {
+        console.error(`axe-auth: ${message}`);
+    }
+}
+function isInvalidGrant(err) {
+    return (err instanceof errors_1.OAuthFlowError &&
+        err.code === "TOKEN_EXCHANGE_FAILED" &&
+        err.details?.error === "invalid_grant");
+}
+function notAuthenticated(message, cause) {
+    return new errors_1.OAuthFlowError("NOT_AUTHENTICATED", message, cause === undefined ? undefined : { cause });
+}
+/**
+ * Returns a currently-valid access token string for the given issuer,
+ * refreshing via the stored refresh token if the cached access token
+ * is within `expiryBufferMs` of expiring (or already expired).
+ *
+ * Throws `OAuthFlowError("NOT_AUTHENTICATED", ...)` when the user
+ * must re-run `axe-auth login` — covers an empty / corrupt /
+ * version-mismatched store, an expired access token with no refresh
+ * token to rotate with, and a refresh attempt rejected with
+ * `invalid_grant` (which also clears the stored tokens).
+ *
+ * Throws `OAuthFlowError("TOKEN_EXCHANGE_FAILED", ...)` for transient
+ * failures during refresh (network errors, 5xx, malformed responses)
+ * and leaves the stored tokens intact so a retry is possible.
+ *
+ * Throws `OAuthFlowError("DISCOVERY_FAILED", ...)` when the issuer
+ * URL cannot be reached or parsed at refresh time.
+ *
+ * **Concurrency note.** Not safe against parallel invocations for
+ * the same issuer. Keycloak rotates refresh tokens by default; if
+ * two parallel calls both land on the refresh path, only one
+ * winner's rotated refresh token will be persisted and the loser's
+ * rotated token is stranded. The intended consumer is the
+ * `axe-auth token` CLI (a one-shot), so this is fine in context;
+ * per-request callers should wrap in an in-flight-Promise singleton
+ * keyed by issuer.
+ */
+async function getValidAccessToken(options) {
+    const { issuerURL, clientId, expiryBufferMs = DEFAULT_EXPIRY_BUFFER_MS, tokenStore = new tokenStore_1.KeyringTokenStore(), loadedEntry, signal, allowInsecureIssuer, onWarning = defaultOnWarning, now = Date.now, } = options;
+    const loaded = loadedEntry ?? (await tokenStore.load());
+    if (!loaded.ok) {
+        switch (loaded.reason) {
+            case "empty":
+                throw notAuthenticated("No stored credentials. Run `axe-auth login` first.");
+            case "corrupt":
+                throw notAuthenticated("Stored credentials are unreadable. Run `axe-auth login` to re-authenticate.");
+            case "version-mismatch":
+                throw notAuthenticated(`Stored credentials are from an unsupported schema version (v:${loaded.storedVersion}). Run \`axe-auth login\` to re-authenticate.`);
+        }
+    }
+    // Guard against a mismatch between the requested issuer/client and
+    // the stored entry's. Under single-entry storage, the keychain
+    // holds one set of tokens minted against one (issuer, client)
+    // pair. Refreshing those tokens against a different
+    // discovery/token endpoint would land an unrelated refresh token
+    // at the wrong server and leak it. Refuse rather than silently
+    // proceed so direct library callers (the CLI's verbs warn + route
+    // before getting here) get a clear signal.
+    if (loaded.entry.issuerURL !== issuerURL ||
+        loaded.entry.clientId !== clientId) {
+        throw notAuthenticated(`Stored credentials are for issuer ${loaded.entry.issuerURL} (client ${loaded.entry.clientId}), but the requested issuer is ${issuerURL} (client ${clientId}). Run \`axe-auth login\` to re-authenticate.`);
+    }
+    const tokens = loaded.entry.tokens;
+    if (now() + expiryBufferMs < tokens.expiresAt) {
+        // Still fresh — no network call, no store write.
+        return tokens.accessToken;
+    }
+    if (!tokens.refreshToken) {
+        throw notAuthenticated("Access token has expired and no refresh token is available. Run `axe-auth login` to re-authenticate.");
+    }
+    const config = await (0, discoverOIDC_1.discoverOIDC)(issuerURL, {
+        signal,
+        allowInsecureIssuer,
+    });
+    let fresh;
+    try {
+        fresh = await (0, refreshTokens_1.refreshTokens)({
+            tokenEndpoint: config.tokenEndpoint,
+            clientId,
+            refreshToken: tokens.refreshToken,
+            now,
+            signal,
+        });
+    }
+    catch (err) {
+        if (isInvalidGrant(err)) {
+            // Refresh token revoked / expired server-side. Best-effort
+            // clear of the stored tokens so the next run starts clean —
+            // but if the clear itself fails (e.g. KEYRING_UNAVAILABLE),
+            // prefer surfacing NOT_AUTHENTICATED so the user still gets
+            // the actionable "please run login" signal. Note the clear
+            // failure via onWarning; the next run will see the stale
+            // tokens, try to refresh, and land back here.
+            try {
+                await tokenStore.clear();
+            }
+            catch (clearErr) {
+                onWarning(`Failed to clear stored tokens after refresh rejection: ${clearErr instanceof Error ? clearErr.message : String(clearErr)}. Next run may need to clear manually.`);
+            }
+            throw notAuthenticated("Your session has expired. Run `axe-auth login` to re-authenticate.", err);
+        }
+        // Transient failure — leave the store alone so the user can
+        // retry without re-logging-in.
+        throw err;
+    }
+    // HAZARD: Keycloak (and most rotating-refresh-token providers) have
+    // already consumed the old refresh token server-side by the time
+    // `refreshTokens` returns. If persisting the rotated set fails
+    // here, we hold a valid access token in memory but the stored
+    // refresh token is now stale — the next invocation will POST it,
+    // get `invalid_grant`, and prompt re-authentication.
+    //
+    // We still return the fresh access token so the current call is
+    // useful, and warn the caller so "why does the next run need me to
+    // log in again?" has a breadcrumb.
+    try {
+        await tokenStore.save({
+            tokens: fresh,
+            issuerURL: loaded.entry.issuerURL,
+            clientId: loaded.entry.clientId,
+            allowInsecureIssuer: loaded.entry.allowInsecureIssuer,
+        });
+    }
+    catch (err) {
+        onWarning(`Refreshed tokens could not be saved: ${err instanceof Error ? err.message : String(err)}. The current call will succeed, but the next invocation will require re-authentication.`);
+    }
+    return fresh.accessToken;
+}

package/dist/oauth/index.d.ts

@@ -1,4 +1,16 @@
 export { startCallbackServer } from "./callbackServer";
 export type { CallbackServerOptions, CallbackServerHandle, CallbackResult, } from "./callbackServer";
-export { OAuthCallbackError } from "./errors";
-export type { OAuthCallbackErrorCode, OAuthCallbackErrorOptions, } from "./errors";
+export { OAuthCallbackError, OAuthFlowError } from "./errors";
+export type { OAuthCallbackErrorCode, OAuthCallbackErrorOptions, OAuthFlowErrorCode, OAuthFlowErrorOptions, } from "./errors";
+export { authorize } from "./authorize";
+export type { AuthorizeOptions } from "./authorize";
+export { getValidAccessToken } from "./getValidAccessToken";
+export type { GetValidAccessTokenOptions } from "./getValidAccessToken";
+export { refreshTokens } from "./refreshTokens";
+export type { RefreshTokensOptions } from "./refreshTokens";
+export type { TokenSet } from "./tokenResponse";
+export { KeyringTokenStore, STORED_BLOB_VERSION } from "./tokenStore";
+export type { LoadResult, StoredEntry, TokenStore } from "./tokenStore";
+export type { KeyringEntry, KeyringEntryFactory } from "./keyringBinding";
+export { discoverOIDC } from "./discoverOIDC";
+export type { OIDCConfiguration, DiscoverOIDCOptions } from "./discoverOIDC";

package/dist/oauth/index.js

@@ -1,7 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OAuthCallbackError = exports.startCallbackServer = void 0;
+exports.discoverOIDC = exports.STORED_BLOB_VERSION = exports.KeyringTokenStore = exports.refreshTokens = exports.getValidAccessToken = exports.authorize = exports.OAuthFlowError = exports.OAuthCallbackError = exports.startCallbackServer = void 0;
 var callbackServer_1 = require("./callbackServer");
 Object.defineProperty(exports, "startCallbackServer", { enumerable: true, get: function () { return callbackServer_1.startCallbackServer; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "OAuthCallbackError", { enumerable: true, get: function () { return errors_1.OAuthCallbackError; } });
+Object.defineProperty(exports, "OAuthFlowError", { enumerable: true, get: function () { return errors_1.OAuthFlowError; } });
+var authorize_1 = require("./authorize");
+Object.defineProperty(exports, "authorize", { enumerable: true, get: function () { return authorize_1.authorize; } });
+var getValidAccessToken_1 = require("./getValidAccessToken");
+Object.defineProperty(exports, "getValidAccessToken", { enumerable: true, get: function () { return getValidAccessToken_1.getValidAccessToken; } });
+var refreshTokens_1 = require("./refreshTokens");
+Object.defineProperty(exports, "refreshTokens", { enumerable: true, get: function () { return refreshTokens_1.refreshTokens; } });
+var tokenStore_1 = require("./tokenStore");
+Object.defineProperty(exports, "KeyringTokenStore", { enumerable: true, get: function () { return tokenStore_1.KeyringTokenStore; } });
+Object.defineProperty(exports, "STORED_BLOB_VERSION", { enumerable: true, get: function () { return tokenStore_1.STORED_BLOB_VERSION; } });
+var discoverOIDC_1 = require("./discoverOIDC");
+Object.defineProperty(exports, "discoverOIDC", { enumerable: true, get: function () { return discoverOIDC_1.discoverOIDC; } });

package/dist/oauth/issuerURL.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Canonicalizes an OIDC issuer URL for equivalence comparison. Two URLs
+ * that normalize to the same string refer to the same issuer, which is
+ * what `discoverOIDC` uses to build discovery URLs and what
+ * `KeyringTokenStore` uses to key keychain entries.
+ *
+ * Rules (per RFC 3986 §6.2 URI comparison):
+ * - Trailing slashes stripped from the path.
+ * - Scheme and authority (host + optional port) lowercased — both are
+ *   case-insensitive per the RFC.
+ * - Default ports (80 for http, 443 for https) collapsed via `URL.host`.
+ * - Path preserved case-sensitively.
+ * - Query string and fragment dropped: OIDC issuers are defined by
+ *   scheme + authority + path, and carrying them through would break
+ *   downstream path concatenation (e.g. appending
+ *   `/.well-known/openid-configuration`).
+ *
+ * If the input is not a parseable URL, the function trims trailing
+ * slashes and returns — discovery will surface a clearer error than
+ * this function could.
+ */
+export declare function normalizeIssuerURL(url: string): string;

package/dist/oauth/issuerURL.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeIssuerURL = normalizeIssuerURL;
+/**
+ * Canonicalizes an OIDC issuer URL for equivalence comparison. Two URLs
+ * that normalize to the same string refer to the same issuer, which is
+ * what `discoverOIDC` uses to build discovery URLs and what
+ * `KeyringTokenStore` uses to key keychain entries.
+ *
+ * Rules (per RFC 3986 §6.2 URI comparison):
+ * - Trailing slashes stripped from the path.
+ * - Scheme and authority (host + optional port) lowercased — both are
+ *   case-insensitive per the RFC.
+ * - Default ports (80 for http, 443 for https) collapsed via `URL.host`.
+ * - Path preserved case-sensitively.
+ * - Query string and fragment dropped: OIDC issuers are defined by
+ *   scheme + authority + path, and carrying them through would break
+ *   downstream path concatenation (e.g. appending
+ *   `/.well-known/openid-configuration`).
+ *
+ * If the input is not a parseable URL, the function trims trailing
+ * slashes and returns — discovery will surface a clearer error than
+ * this function could.
+ */
+function normalizeIssuerURL(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return url.replace(/\/+$/, "");
+    }
+    // `URL.protocol` is already lowercased by the URL parser.
+    // `URL.host` retains input casing, so lowercase it explicitly.
+    const host = parsed.host.toLowerCase();
+    const pathname = parsed.pathname.replace(/\/+$/, "");
+    return `${parsed.protocol}//${host}${pathname}`;
+}

package/dist/oauth/keyringBinding.d.ts

@@ -0,0 +1,22 @@
+/** Minimal keyring-entry surface consumed by the package's stores. */
+export interface KeyringEntry {
+    /** Writes the password for this entry. */
+    setPassword(password: string): void;
+    /** Reads the current password, or returns `null` if none is set. */
+    getPassword(): string | null;
+    /** Deletes the password and returns `true` if one existed. */
+    deletePassword(): boolean;
+}
+/**
+ * Factory for `KeyringEntry` values. Injection seam for tests;
+ * production callers use the default that constructs
+ * `@napi-rs/keyring` entries lazily.
+ */
+export type KeyringEntryFactory = (service: string, account: string) => KeyringEntry;
+/**
+ * Default `KeyringEntryFactory`. Resolves `@napi-rs/keyring` lazily
+ * so platforms without a prebuilt binding only see a
+ * `KEYRING_UNAVAILABLE` on first store construction, not on module
+ * import.
+ */
+export declare const defaultEntryFactory: KeyringEntryFactory;

package/dist/oauth/keyringBinding.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultEntryFactory = void 0;
+const node_module_1 = require("node:module");
+const errors_1 = require("./errors");
+const requireFromHere = (0, node_module_1.createRequire)(__filename);
+// Lazy-resolved Entry constructor. Importing @napi-rs/keyring at the
+// top of this module would run its native binding loader at
+// module-load time, throwing before any of our OAuthFlowError code
+// catches it and preventing the module from being imported at all on
+// platforms without a prebuilt. We defer the require into
+// `defaultEntryFactory`, which turns that import-time failure into a
+// `KEYRING_UNAVAILABLE` surfaced on the first store construction —
+// not on first save/load/clear, since callers construct stores
+// eagerly as default-arg expressions. Runtime keychain errors
+// (missing D-Bus Secret Service, macOS Keychain denial, etc.) are a
+// separate concern and surface later, inside save/load/clear.
+let cachedEntryCtor = null;
+function resolveEntryCtor() {
+    if (cachedEntryCtor)
+        return cachedEntryCtor;
+    try {
+        const mod = requireFromHere("@napi-rs/keyring");
+        cachedEntryCtor = mod.Entry;
+        return cachedEntryCtor;
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `Could not load @napi-rs/keyring. A prebuilt native binding for this platform may be missing.`, { cause });
+    }
+}
+/**
+ * Default `KeyringEntryFactory`. Resolves `@napi-rs/keyring` lazily
+ * so platforms without a prebuilt binding only see a
+ * `KEYRING_UNAVAILABLE` on first store construction, not on module
+ * import.
+ */
+const defaultEntryFactory = (service, account) => {
+    const Ctor = resolveEntryCtor();
+    return new Ctor(service, account);
+};
+exports.defaultEntryFactory = defaultEntryFactory;

package/dist/oauth/openBrowser.d.ts

@@ -0,0 +1,19 @@
+import type { ChildProcess, SpawnOptions } from "node:child_process";
+/** Injection seam for `child_process.spawn`. Used by tests. */
+export type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+/** Options for `openBrowser`. */
+export interface OpenBrowserOptions {
+    /** Override for `process.platform`. Used by tests. */
+    platform?: NodeJS.Platform;
+    /** Override for `child_process.spawn`. Used by tests. */
+    spawnFn?: SpawnFn;
+}
+/**
+ * Launches the system browser at `url` in a detached child process.
+ * Returns synchronously once the child is spawned — completion of the
+ * browser load is intentionally not awaited.
+ *
+ * @param url Absolute URL to open.
+ * @param options Platform/spawn overrides; only exposed for tests.
+ */
+export declare function openBrowser(url: string, options?: OpenBrowserOptions): void;

package/dist/oauth/openBrowser.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openBrowser = openBrowser;
+const node_child_process_1 = require("node:child_process");
+const errors_1 = require("./errors");
+// On Windows `start` is a cmd.exe builtin, not a standalone binary.
+// The empty `""` pair is a positional placeholder for the window
+// title — without it `start` treats the URL as the title.
+//
+// The escape class covers:
+// - `& | ^ < >` — cmd metacharacters that would otherwise split the
+//   command line.
+// - `"` — would prematurely terminate the argument and break
+//   `start`'s quoting.
+// - `%` — triggers cmd.exe environment-variable expansion (e.g.
+//   `%USERNAME%`), which could leak or alter the URL.
+// - `\r \n` — embedded newlines let a crafted URL inject additional
+//   commands onto cmd.exe's line.
+//
+// URLs normally percent-encode most of these (so this is defense in
+// depth), but we do not fully trust the authorization endpoint that
+// came back from discovery.
+function windowsCommand(url) {
+    return {
+        command: "cmd.exe",
+        args: ["/c", "start", '""', url.replace(/[&|^<>"%\r\n]/g, (c) => `^${c}`)],
+    };
+}
+function browserCommand(platform, url) {
+    switch (platform) {
+        case "darwin":
+            return { command: "open", args: [url] };
+        case "win32":
+            return windowsCommand(url);
+        default:
+            // linux / freebsd / openbsd — xdg-open is part of xdg-utils which
+            // is near-universal on desktop Linux. Environments without it
+            // (headless servers, containers) will report the missing binary
+            // via an asynchronous child-process `error` event, which this
+            // module deliberately swallows (see `child.once("error", ...)`
+            // below); `BROWSER_LAUNCH_FAILED` is only raised for synchronous
+            // `spawn()` throws. The caller's fallback is the URL already
+            // surfaced via `onAuthorizationUrl` so the user can finish the
+            // flow manually.
+            return { command: "xdg-open", args: [url] };
+    }
+}
+/**
+ * Launches the system browser at `url` in a detached child process.
+ * Returns synchronously once the child is spawned — completion of the
+ * browser load is intentionally not awaited.
+ *
+ * @param url Absolute URL to open.
+ * @param options Platform/spawn overrides; only exposed for tests.
+ */
+function openBrowser(url, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const spawnFn = options.spawnFn ?? node_child_process_1.spawn;
+    const { command, args } = browserCommand(platform, url);
+    let child;
+    try {
+        child = spawnFn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("BROWSER_LAUNCH_FAILED", `Failed to launch the system browser (${command}). Open this URL manually:\n${url}`, { cause });
+    }
+    // `spawn` itself can succeed (the parent fork was fine) and then emit
+    // `error` asynchronously if the binary isn't on PATH. We can't surface
+    // that synchronously, but attaching a handler prevents the default
+    // "unhandled error" crash. Callers get a benign no-op if the browser
+    // never opens; the authorize() orchestrator prints the URL alongside
+    // the launch so the user has a fallback.
+    child.once("error", () => { });
+    child.unref();
+}

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generates a cryptographically random PKCE `code_verifier` per RFC 7636
+ * §4.1. 43 base64url characters, 256 bits of entropy.
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Derives the PKCE S256 `code_challenge` for the given verifier per
+ * RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(verifier)))`.
+ *
+ * @param verifier The PKCE verifier produced by `generateCodeVerifier`.
+ */
+export declare function deriveCodeChallenge(verifier: string): string;
+/**
+ * Generates a cryptographically random OAuth `state` value for CSRF
+ * protection. 22 base64url characters, 128 bits of entropy.
+ */
+export declare function generateState(): string;