@deque/axe-auth 1.1.0-next.d59ba863 → 1.1.0-next.d5a755f8

package/dist/oauth/authorize.js

@@ -9,7 +9,7 @@ const openBrowser_1 = require("./openBrowser");
 const tokenExchange_1 = require("./tokenExchange");
 const tokenStore_1 = require("./tokenStore");
 const errors_1 = require("./errors");
-function defaultOnAuthorizationUrl(url) {
+function defaultOnAuthorizationURL(url) {
     if (process.stderr.isTTY) {
         console.error(`Authorization URL: ${url}`);
     }
@@ -38,11 +38,9 @@ function defaultOnWarning(message) {
  * @throws {OAuthCallbackError} For loopback/callback-server failures.
  */
 async function authorize(options) {
-    const { issuerURL, clientId, walnutURL, scopes, timeoutMs, signal, tokenStore = new tokenStore_1.KeyringTokenStore(), openBrowser = openBrowser_1.openBrowser, onAuthorizationUrl = defaultOnAuthorizationUrl, onWarning = defaultOnWarning, allowInsecureIssuer, } = options;
-    // Discovery first. If the auth server is unreachable we want to fail
-    // *before* opening a browser — a rejected discovery throw is
-    // strictly more useful than a browser tab pointing at a
-    // wrong/unreachable URL.
+    const { issuerURL, clientId, walnutURL, scopes, timeoutMs, signal, tokenStore = new tokenStore_1.KeyringTokenStore(), openBrowser = openBrowser_1.openBrowser, onAuthorizationURL = defaultOnAuthorizationURL, onWarning = defaultOnWarning, allowInsecureIssuer, } = options;
+    // Discovery before browser-launch so a bad URL surfaces as a
+    // throw rather than a wrong/unreachable browser tab.
     const config = await (0, discoverOIDC_1.discoverOIDC)(issuerURL, {
         signal,
         allowInsecureIssuer,
@@ -59,7 +57,7 @@ async function authorize(options) {
         const authURL = (0, authorizationURL_1.buildAuthorizationURL)({
             authorizationEndpoint: config.authorizationEndpoint,
             clientId,
-            redirectUri: callback.redirectUri,
+            redirectURI: callback.redirectURI,
             codeChallenge,
             state,
             scopes,
@@ -67,13 +65,13 @@ async function authorize(options) {
         // Surface before launch so the URL is always visible even if the
         // browser spawn fails (or never does anything useful, e.g. on a
         // headless box).
-        onAuthorizationUrl(authURL);
+        onAuthorizationURL(authURL);
         try {
             openBrowser(authURL);
         }
         catch (err) {
             // Only swallow the "could not launch browser" case: the URL was
-            // already surfaced via onAuthorizationUrl so the user can
+            // already surfaced via onAuthorizationURL so the user can
             // complete the flow manually. Any other error (a bug in an
             // injected openBrowser, an unexpected throw) must propagate so
             // callers and tests can see it.
@@ -91,7 +89,7 @@ async function authorize(options) {
             clientId,
             code,
             codeVerifier,
-            redirectUri: callback.redirectUri,
+            redirectURI: callback.redirectURI,
             signal,
         });
         // If the caller requested offline_access but no refresh_token

package/dist/oauth/callbackServer.d.ts

@@ -1,23 +1,34 @@
 import { IncomingMessage, Server, ServerResponse } from "node:http";
-export type CallbackServerOptions = {
+/** Configures the loopback callback server. */
+export interface CallbackServerOptions {
     expectedState: string;
     timeoutMs?: number;
     signal?: AbortSignal;
-};
-export type CallbackResult = {
+}
+/** Authorization-code and state pair captured from a successful redirect. */
+export interface CallbackResult {
     code: string;
     state: string;
-};
-export type CallbackServerHandle = {
-    redirectUri: string;
+}
+/** Live handle to a running callback server. */
+export interface CallbackServerHandle {
+    redirectURI: string;
     result: Promise<CallbackResult>;
     close: () => Promise<void>;
-};
+}
 type RequestHandler = (req: IncomingMessage, res: ServerResponse) => void;
 type LoopbackListener = (handler: RequestHandler, host: string) => Promise<Server>;
-export declare const bindLoopback: (handler: RequestHandler, listenFn?: LoopbackListener) => Promise<{
+/**
+ * Binds an HTTP server to the loopback interface, preferring IPv4.
+ *
+ * RFC 8252 §7.3: "use whichever is available". Prefer IPv4; fall back to
+ * IPv6 only when the IPv4 loopback isn't configured on this host. `listenFn`
+ * is an injection seam for tests — production callers use the default.
+ */
+export declare function bindLoopback(handler: RequestHandler, listenFn?: LoopbackListener): Promise<{
     server: Server;
     host: "127.0.0.1" | "::1";
 }>;
-export declare const startCallbackServer: (opts: CallbackServerOptions) => Promise<CallbackServerHandle>;
+/** Starts a loopback HTTP server that captures the OAuth redirect. */
+export declare function startCallbackServer(opts: CallbackServerOptions): Promise<CallbackServerHandle>;
 export {};

package/dist/oauth/callbackServer.js

@@ -1,13 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startCallbackServer = exports.bindLoopback = void 0;
+exports.bindLoopback = bindLoopback;
+exports.startCallbackServer = startCallbackServer;
 const node_events_1 = require("node:events");
 const node_http_1 = require("node:http");
 const errors_1 = require("./errors");
-const renderHtml_1 = require("./renderHtml");
+const renderHTML_1 = require("./renderHTML");
 const DEFAULT_TIMEOUT_MS = 120_000;
 const LOOPBACK_ADDRESSES = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
-const isLoopback = (addr) => !!addr && LOOPBACK_ADDRESSES.has(addr);
+function isLoopback(addr) {
+    return !!addr && LOOPBACK_ADDRESSES.has(addr);
+}
 // Errors from bind(2) that mean "this address family isn't configured on this
 // host" — the signal to fall back to the other loopback family rather than
 // fail the caller.
@@ -19,10 +22,14 @@ const listen = async (handler, host) => {
     await (0, node_events_1.once)(server, "listening");
     return server;
 };
-// RFC 8252 §7.3: "use whichever is available". Prefer IPv4; fall back to
-// IPv6 only when the IPv4 loopback isn't configured on this host. `listenFn`
-// is an injection seam for tests — production callers use the default.
-const bindLoopback = async (handler, listenFn = listen) => {
+/**
+ * Binds an HTTP server to the loopback interface, preferring IPv4.
+ *
+ * RFC 8252 §7.3: "use whichever is available". Prefer IPv4; fall back to
+ * IPv6 only when the IPv4 loopback isn't configured on this host. `listenFn`
+ * is an injection seam for tests — production callers use the default.
+ */
+async function bindLoopback(handler, listenFn = listen) {
     try {
         return {
             server: await listenFn(handler, "127.0.0.1"),
@@ -44,32 +51,32 @@ const bindLoopback = async (handler, listenFn = listen) => {
             throw new errors_1.OAuthCallbackError("BIND_FAILED", `Failed to bind loopback server on 127.0.0.1 (${code}) and [::1]: ${ipv6Err.message}`, { cause: ipv6Err });
         }
     }
-};
-exports.bindLoopback = bindLoopback;
-const closeServer = async (server) => {
+}
+async function closeServer(server) {
     if (!server.listening)
         return;
     server.close();
     server.closeAllConnections?.();
     await (0, node_events_1.once)(server, "close");
-};
-const writeHtml = (res, status, html) => {
+}
+function writeHTML(res, status, html) {
     res.writeHead(status, {
         "Content-Type": "text/html; charset=utf-8",
-        "Content-Security-Policy": renderHtml_1.CSP_HEADER,
+        "Content-Security-Policy": renderHTML_1.CSP_HEADER,
         "X-Content-Type-Options": "nosniff",
     });
     res.end(html);
-};
-const writeText = (res, status, body, extraHeaders = {}) => {
+}
+function writeText(res, status, body, extraHeaders = {}) {
     res.writeHead(status, {
         "Content-Type": "text/plain; charset=utf-8",
         "X-Content-Type-Options": "nosniff",
         ...extraHeaders,
     });
     res.end(body + "\n");
-};
-const startCallbackServer = async (opts) => {
+}
+/** Starts a loopback HTTP server that captures the OAuth redirect. */
+async function startCallbackServer(opts) {
     const { expectedState, timeoutMs = DEFAULT_TIMEOUT_MS, signal } = opts;
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         throw new TypeError(`timeoutMs must be a positive finite number (received ${timeoutMs}).`);
@@ -164,7 +171,7 @@ const startCallbackServer = async (opts) => {
         // up front means once we start composing the response, no concurrent
         // settlement (timer/abort) can race us into a dropped connection.
         if (!tryConsume()) {
-            writeHtml(res, 409, (0, renderHtml_1.renderHtml)({
+            writeHTML(res, 409, (0, renderHTML_1.renderHTML)({
                 kind: "error",
                 reason: "This callback server has already handled a response.",
             }));
@@ -179,7 +186,7 @@ const startCallbackServer = async (opts) => {
                     : { error: providerError },
             });
             deferSettleOnClose(res, () => rejectResult(error));
-            writeHtml(res, 400, (0, renderHtml_1.renderHtml)({
+            writeHTML(res, 400, (0, renderHTML_1.renderHTML)({
                 kind: "error",
                 reason: providerError,
                 description,
@@ -191,7 +198,7 @@ const startCallbackServer = async (opts) => {
         if (!code) {
             const error = new errors_1.OAuthCallbackError("MISSING_CODE", "Authorization response missing 'code' parameter.");
             deferSettleOnClose(res, () => rejectResult(error));
-            writeHtml(res, 400, (0, renderHtml_1.renderHtml)({
+            writeHTML(res, 400, (0, renderHTML_1.renderHTML)({
                 kind: "error",
                 reason: "The authorization response was missing the 'code' parameter.",
             }));
@@ -200,19 +207,19 @@ const startCallbackServer = async (opts) => {
         if (state !== expectedState) {
             const error = new errors_1.OAuthCallbackError("STATE_MISMATCH", "Authorization response 'state' did not match expected value.");
             deferSettleOnClose(res, () => rejectResult(error));
-            writeHtml(res, 400, (0, renderHtml_1.renderHtml)({
+            writeHTML(res, 400, (0, renderHTML_1.renderHTML)({
                 kind: "error",
                 reason: "The authorization response failed state validation.",
             }));
             return;
         }
         deferSettleOnClose(res, () => resolveResult({ code, state }));
-        writeHtml(res, 200, (0, renderHtml_1.renderHtml)({ kind: "success" }));
+        writeHTML(res, 200, (0, renderHTML_1.renderHTML)({ kind: "success" }));
     };
-    const bound = await (0, exports.bindLoopback)(handler);
+    const bound = await bindLoopback(handler);
     server = bound.server;
     const port = server.address().port;
-    const redirectUri = bound.host === "::1"
+    const redirectURI = bound.host === "::1"
         ? `http://[::1]:${port}/callback`
         : `http://127.0.0.1:${port}/callback`;
     timeoutHandle = setTimeout(() => {
@@ -229,6 +236,5 @@ const startCallbackServer = async (opts) => {
             signal.addEventListener("abort", abortListener, { once: true });
         }
     }
-    return { redirectUri, result, close };
-};
-exports.startCallbackServer = startCallbackServer;
+    return { redirectURI, result, close };
+}

package/dist/oauth/discoverOIDC.d.ts

@@ -15,36 +15,19 @@ export interface OIDCConfiguration {
 export interface DiscoverOIDCOptions {
     /** Aborts the underlying fetch when fired. */
     signal?: AbortSignal;
-    /**
-     * Permit non-HTTPS issuer URLs whose host is not a loopback literal.
-     * Loopback hosts (`localhost`, `127.0.0.1`, `[::1]`) are always
-     * allowed over http since they cannot be intercepted remotely; this
-     * flag is for corporate dev setups or reverse-proxy scenarios where
-     * http is the only available path. Default `false`.
-     */
+    /** Permit non-HTTPS issuer URLs whose host is not a loopback literal. Default `false`. */
     allowInsecureIssuer?: boolean;
 }
 /**
- * Fetches and parses the OpenID Connect discovery document for a given
- * issuer. Fails fast (no retry) so the caller does not open a browser
- * against an unreachable authorization server.
+ * Fetches and parses the OIDC discovery document. Fails fast (no
+ * retry) so the caller does not open a browser against an unreachable
+ * authorization server. Verifies the server's claimed `issuer` matches
+ * the input URL per OIDC Discovery §3 — without this, a hostile
+ * discovery response could redirect the authorization and token
+ * endpoints to attacker hosts.
  *
- * This function uses the OIDC discovery well-known path as a
- * convention — most OAuth 2.0 providers expose it regardless of
- * whether you intend to perform identity validation. This library
- * itself does not perform OIDC identity validation (no id_token /
- * nonce / signature checks); callers needing OIDC-strength identity
- * assurance should layer that on top.
- *
- * Verifies that the server's claimed `issuer` matches the URL the
- * caller passed in, per OIDC Discovery §3 / defence against a hostile
- * discovery response redirecting `authorization_endpoint` and
- * `token_endpoint` to attacker-controlled hosts.
- *
- * @param issuerURL Authorization-server URL the discovery document
- *   claims as its `issuer`. For Keycloak, callers build this as
- *   `${serverURL}/realms/${realm}`. For other providers it is the
- *   hostname (or issuer path) advertised in their discovery document.
- *   Trailing slashes tolerated.
+ * Uses the OIDC well-known path as a convention; does not perform
+ * OIDC-strength identity validation (no id_token / nonce / signature
+ * checks). Callers needing identity assurance should layer that on top.
  */
 export declare function discoverOIDC(issuerURL: string, options?: DiscoverOIDCOptions): Promise<OIDCConfiguration>;

package/dist/oauth/discoverOIDC.js

@@ -9,13 +9,7 @@ const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 function optionalString(v) {
     return (0, predicates_1.isNonEmptyString)(v) ? v : undefined;
 }
-/**
- * Throws `DISCOVERY_FAILED` if `url` is not safe to transmit OAuth
- * secrets over. `https:` is always fine; `http:` is only fine for
- * loopback hosts, or for any host when `allowInsecurePermitted` is
- * `true`. `label` describes the URL being checked ("issuer URL",
- * "token_endpoint", etc.) and appears in the error message.
- */
+/** Throws `DISCOVERY_FAILED` if `url` is not safe to transmit OAuth secrets over. */
 function assertSecureURL(url, label, allowInsecurePermitted) {
     let parsed;
     try {
@@ -40,10 +34,9 @@ function assertSecureURL(url, label, allowInsecurePermitted) {
     throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Unsupported ${label} scheme '${parsed.protocol}'; expected https: or http: (loopback only).`);
 }
 function buildDiscoveryURL(issuerURL) {
-    // Use URL parsing (rather than string concat) so the discovery path
-    // lands on the URL's pathname, not accidentally after a query string
-    // or fragment. `normalizeIssuerURL` already strips those, but
-    // defense in depth keeps the contract obvious from the code.
+    // URL parsing (rather than concat) so the path lands on `pathname`
+    // even if the input has a query string or fragment. `normalizeIssuerURL`
+    // strips those, but defense in depth.
     const normalized = new URL((0, issuerURL_1.normalizeIssuerURL)(issuerURL));
     normalized.search = "";
     normalized.hash = "";
@@ -71,21 +64,10 @@ function parseConfiguration(body, url) {
     };
 }
 /**
- * `code_challenge_methods_supported` is OPTIONAL in OIDC discovery, so its
- * absence proves nothing — older providers may support PKCE without
- * advertising it. But when the list IS present and does not include
- * `S256` (the only method this CLI uses, per RFC 7636), the server has
- * explicitly declared it does not support the flow we need. Fail fast
- * with an actionable message instead of letting the user hit a generic
- * OAuth error several steps deeper into the flow.
- *
- * An empty list (`[]`) is treated the same as a populated list missing
- * `S256`: the server has explicitly advertised zero supported methods,
- * which is incompatible.
- *
- * Called from `discoverOIDC` after issuer verification so that a
- * tampered discovery doc surfaces the more security-critical issuer
- * mismatch first.
+ * `code_challenge_methods_supported` is OPTIONAL in OIDC discovery —
+ * absence is fine (older providers don't advertise). But when the
+ * list is present and excludes `S256` (the only method this CLI
+ * uses, per RFC 7636), fail fast with an actionable message.
  */
 function assertPKCESupport(body, url) {
     const methods = body.code_challenge_methods_supported;
@@ -96,27 +78,16 @@ function assertPKCESupport(body, url) {
     throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${url} advertises code_challenge_methods_supported = ${JSON.stringify(methods)}, but axe-auth requires S256 (PKCE per RFC 7636). The OAuth client used by axe-auth needs PKCE enabled, or you may be on an axe server version that predates OAuth-based MCP authentication.`);
 }
 /**
- * Fetches and parses the OpenID Connect discovery document for a given
- * issuer. Fails fast (no retry) so the caller does not open a browser
- * against an unreachable authorization server.
- *
- * This function uses the OIDC discovery well-known path as a
- * convention — most OAuth 2.0 providers expose it regardless of
- * whether you intend to perform identity validation. This library
- * itself does not perform OIDC identity validation (no id_token /
- * nonce / signature checks); callers needing OIDC-strength identity
- * assurance should layer that on top.
- *
- * Verifies that the server's claimed `issuer` matches the URL the
- * caller passed in, per OIDC Discovery §3 / defence against a hostile
- * discovery response redirecting `authorization_endpoint` and
- * `token_endpoint` to attacker-controlled hosts.
+ * Fetches and parses the OIDC discovery document. Fails fast (no
+ * retry) so the caller does not open a browser against an unreachable
+ * authorization server. Verifies the server's claimed `issuer` matches
+ * the input URL per OIDC Discovery §3 — without this, a hostile
+ * discovery response could redirect the authorization and token
+ * endpoints to attacker hosts.
  *
- * @param issuerURL Authorization-server URL the discovery document
- *   claims as its `issuer`. For Keycloak, callers build this as
- *   `${serverURL}/realms/${realm}`. For other providers it is the
- *   hostname (or issuer path) advertised in their discovery document.
- *   Trailing slashes tolerated.
+ * Uses the OIDC well-known path as a convention; does not perform
+ * OIDC-strength identity validation (no id_token / nonce / signature
+ * checks). Callers needing identity assurance should layer that on top.
  */
 async function discoverOIDC(issuerURL, options = {}) {
     const allowInsecure = options.allowInsecureIssuer ?? false;

package/dist/oauth/discoverSSOConfig.d.ts

@@ -1,9 +1,4 @@
-/**
- * Subset of the axe server's `/api/sso-config` response that this
- * package consumes. The full response may carry additional fields
- * (e.g. `publicClientId` for the SPA frontend); we ignore everything
- * except what the CLI needs to drive its OAuth flow.
- */
+/** Subset of `/api/sso-config` this package consumes. */
 export interface SSOConfig {
     /** Keycloak base URL, e.g. `https://auth.example.com`. */
     url: string;
@@ -16,12 +11,7 @@ export interface SSOConfig {
 export interface DiscoverSSOConfigOptions {
     /** Aborts the underlying fetch when fired. */
     signal?: AbortSignal;
-    /**
-     * Permit non-HTTPS axe server URLs whose host is not a loopback
-     * literal. Loopback hosts (`localhost`, `127.0.0.1`, `[::1]`) are
-     * always allowed over http; this flag is the opt-in for non-loopback
-     * http (corporate dev / reverse-proxy setups). Default `false`.
-     */
+    /** Permit non-HTTPS axe server URLs whose host is not a loopback literal. Default `false`. */
     allowInsecure?: boolean;
 }
 /**

package/dist/oauth/errors.d.ts

@@ -41,6 +41,8 @@ export type OAuthFlowErrorCode =
  | "TOKEN_EXCHANGE_FAILED"
 /** System keychain is unavailable (e.g. no D-Bus secret service on Linux). */
  | "KEYRING_UNAVAILABLE"
+/** OAuth blob is too large for the OS keystore (Windows Credential Manager: 2560 UTF-16 chars per entry, MAX_CHUNKS chunks max). The keystore itself is healthy; the IDP is issuing tokens with too many claims. */
+ | "TOKEN_TOO_LARGE"
 /** 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. */

package/dist/oauth/getValidAccessToken.d.ts

@@ -1,60 +1,25 @@
 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.
-     */
+    /** OIDC issuer URL. Must match the stored entry's `issuerURL`; mismatch throws NOT_AUTHENTICATED. */
     issuerURL: string;
-    /**
-     * OAuth client identifier. Must match the stored entry's
-     * `clientId`; see the note on `issuerURL` for the mismatch
-     * behavior.
-     */
+    /** OAuth client identifier. Must match the stored entry's `clientId`; same mismatch behavior as `issuerURL`. */
     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.
+     * How close to expiry preemptive refresh kicks in, in ms. Default
+     * 60_000. Buffer covers clock skew vs. the server. Assumes
+     * access-token TTL ≫ this; otherwise every call refreshes.
      */
     expiryBufferMs?: number;
-    /**
-     * Override for the token store. Defaults to a fresh
-     * `KeyringTokenStore()` (single keychain entry per machine).
-     */
+    /** Override for the token store. */
     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()`.
-     */
+    /** Pre-loaded `tokenStore.load()` result so the dispatcher's keychain read isn't repeated. */
     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.
-     */
+    /** Forwarded to discovery; permits 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.
-     */
+    /** Called for soft warnings (e.g. rotated tokens couldn't be persisted — see HAZARD note in the body). Default prints to stderr only when stderr is a TTY. */
     onWarning?: (message: string) => void;
     /** Source of `now`. Defaults to `Date.now`. Injected for test determinism. */
     now?: () => number;

package/dist/oauth/getValidAccessToken.js

@@ -59,21 +59,15 @@ async function getValidAccessToken(options) {
                 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.
+    // Refuse on issuer/client mismatch: refreshing tokens at a
+    // different endpoint would leak the refresh token to the wrong
+    // server.
     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) {
@@ -95,13 +89,10 @@ async function getValidAccessToken(options) {
     }
     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.
+            // Best-effort clear: if the clear itself fails, still surface
+            // NOT_AUTHENTICATED so the user gets the "please run login"
+            // signal — the next run will refresh, land back here, and
+            // retry the clear.
             try {
                 await tokenStore.clear();
             }

package/dist/oauth/openBrowser.d.ts

@@ -7,13 +7,24 @@ export interface OpenBrowserOptions {
     platform?: NodeJS.Platform;
     /** Override for `child_process.spawn`. Used by tests. */
     spawnFn?: SpawnFn;
+    /**
+     * Override for `process.env.BROWSER`. The de-facto convention shared
+     * with `xdg-open` and Python's `webbrowser`: when set, it names the
+     * command to invoke instead of the platform default. Parsed shlex-style
+     * (POSIX shell tokenization) so values like `firefox --new-window` or
+     * `/path/with\ spaces/firefox` work as expected. An empty or missing
+     * value falls back to the platform default.
+     */
+    browserEnv?: string;
 }
 /**
  * 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.
+ * Honors `$BROWSER` when set, falling back to the platform default
+ * (`open` / `xdg-open` / `cmd start`). 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.
+ * @param options Platform/spawn/env overrides; only exposed for tests.
  */
 export declare function openBrowser(url: string, options?: OpenBrowserOptions): void;

package/dist/oauth/openBrowser.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.openBrowser = openBrowser;
 const node_child_process_1 = require("node:child_process");
+const shlex_1 = require("shlex");
 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
@@ -26,7 +27,11 @@ function windowsCommand(url) {
         args: ["/c", "start", '""', url.replace(/[&|^<>"%\r\n]/g, (c) => `^${c}`)],
     };
 }
-function browserCommand(platform, url) {
+function browserCommand(platform, url, browserOverride) {
+    if (browserOverride && browserOverride.length > 0) {
+        const [command, ...extraArgs] = browserOverride;
+        return { command, args: [...extraArgs, url] };
+    }
     switch (platform) {
         case "darwin":
             return { command: "open", args: [url] };
@@ -40,23 +45,35 @@ function browserCommand(platform, url) {
             // 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
+            // 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.
+ * Honors `$BROWSER` when set, falling back to the platform default
+ * (`open` / `xdg-open` / `cmd start`). 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.
+ * @param options Platform/spawn/env 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);
+    const browserEnv = options.browserEnv ?? process.env.BROWSER;
+    let browserOverride;
+    if (browserEnv && browserEnv.length > 0) {
+        try {
+            browserOverride = (0, shlex_1.split)(browserEnv);
+        }
+        catch (cause) {
+            throw new errors_1.OAuthFlowError("BROWSER_LAUNCH_FAILED", `Failed to parse $BROWSER (${browserEnv}). Open this URL manually:\n${url}`, { cause });
+        }
+    }
+    const { command, args } = browserCommand(platform, url, browserOverride);
     let child;
     try {
         child = spawnFn(command, args, {