@deque/axe-auth 1.1.0-next.789db6ed → 1.1.0-next.8e9934f2

package/dist/oauth/discoverOIDC.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverOIDC = discoverOIDC;
+const errors_1 = require("./errors");
+const issuerURL_1 = require("./issuerURL");
+const predicates_1 = require("./predicates");
+const userAgent_1 = require("../userAgent");
+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.
+ */
+function assertSecureURL(url, label, allowInsecurePermitted) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `${label} is not a valid URL: ${url}`);
+    }
+    if (parsed.protocol === "https:")
+        return;
+    if (parsed.protocol === "http:") {
+        const host = parsed.host.toLowerCase();
+        // Keycloak on localhost:8080 → host === "localhost:8080"; strip
+        // the port for the loopback check.
+        const hostname = host.replace(/:\d+$/, "");
+        if (LOOPBACK_HOSTS.has(hostname))
+            return;
+        if (allowInsecurePermitted)
+            return;
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Refusing to use ${label} over http:// against non-loopback host ${parsed.host}. Use https:// or pass allowInsecureIssuer: true to override (only do this on trusted networks).`);
+    }
+    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.
+    const normalized = new URL((0, issuerURL_1.normalizeIssuerURL)(issuerURL));
+    normalized.search = "";
+    normalized.hash = "";
+    normalized.pathname = `${normalized.pathname.replace(/\/$/, "")}/.well-known/openid-configuration`;
+    return normalized.toString();
+}
+function parseConfiguration(body, url) {
+    const missing = [];
+    if (!(0, predicates_1.isNonEmptyString)(body.issuer))
+        missing.push("issuer");
+    if (!(0, predicates_1.isNonEmptyString)(body.authorization_endpoint)) {
+        missing.push("authorization_endpoint");
+    }
+    if (!(0, predicates_1.isNonEmptyString)(body.token_endpoint))
+        missing.push("token_endpoint");
+    if (missing.length > 0) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${url} is missing required field(s): ${missing.join(", ")}`);
+    }
+    return {
+        issuer: body.issuer,
+        authorizationEndpoint: body.authorization_endpoint,
+        tokenEndpoint: body.token_endpoint,
+        revocationEndpoint: optionalString(body.revocation_endpoint),
+        endSessionEndpoint: optionalString(body.end_session_endpoint),
+    };
+}
+/**
+ * `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.
+ */
+function assertPKCESupport(body, url) {
+    const methods = body.code_challenge_methods_supported;
+    if (!Array.isArray(methods))
+        return;
+    if (methods.includes("S256"))
+        return;
+    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.
+ *
+ * @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.
+ */
+async function discoverOIDC(issuerURL, options = {}) {
+    const allowInsecure = options.allowInsecureIssuer ?? false;
+    assertSecureURL(issuerURL, "issuer URL", allowInsecure);
+    const url = buildDiscoveryURL(issuerURL);
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { "User-Agent": userAgent_1.USER_AGENT },
+            signal: options.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Could not reach the authentication server at ${url}. Check the URL and your network connection.`, { cause });
+    }
+    if (!response.ok) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Authentication server at ${url} responded with HTTP ${response.status}. Check the issuer URL.`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Authentication server at ${url} did not return a valid JSON OpenID configuration`, { cause });
+    }
+    if (body === null || typeof body !== "object") {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${url} was not a JSON object`);
+    }
+    const config = parseConfiguration(body, url);
+    // OIDC Discovery §3: the `issuer` value returned MUST equal the URL
+    // the client used for discovery. Without this check (and without
+    // id_token signature validation, which this library does not do),
+    // a hostile discovery response could redirect the authorization and
+    // token endpoints to attacker hosts while still appearing to come
+    // from the legitimate origin.
+    if ((0, issuerURL_1.normalizeIssuerURL)(config.issuer) !== (0, issuerURL_1.normalizeIssuerURL)(issuerURL)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Issuer mismatch: requested ${issuerURL} but discovery document claims ${config.issuer}`);
+    }
+    // Enforce scheme on the endpoints the flow actually hits. A tampered
+    // discovery response could claim the legitimate issuer while
+    // returning http://... for authorization_endpoint or token_endpoint,
+    // which would leak the auth code + PKCE verifier to a cleartext
+    // path. Same loopback / allowInsecureIssuer policy as the input.
+    assertSecureURL(config.authorizationEndpoint, "authorization_endpoint", allowInsecure);
+    assertSecureURL(config.tokenEndpoint, "token_endpoint", allowInsecure);
+    if (config.revocationEndpoint) {
+        assertSecureURL(config.revocationEndpoint, "revocation_endpoint", allowInsecure);
+    }
+    if (config.endSessionEndpoint) {
+        assertSecureURL(config.endSessionEndpoint, "end_session_endpoint", allowInsecure);
+    }
+    assertPKCESupport(body, url);
+    return config;
+}

package/dist/oauth/discoverSSOConfig.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+export interface SSOConfig {
+    /** Keycloak base URL, e.g. `https://auth.example.com`. */
+    url: string;
+    /** Keycloak realm name. */
+    realm: string;
+    /** OAuth client ID for the axe-auth CLI. */
+    mcpClientId: string;
+}
+/** Options for `discoverSSOConfig`. */
+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`.
+     */
+    allowInsecure?: boolean;
+}
+/**
+ * Fetches and parses the axe server's `/api/sso-config` discovery
+ * endpoint. Used by `axe-auth login` to derive the OAuth issuer URL,
+ * realm, and CLI-specific client ID from the axe server URL the user
+ * supplied (or the SaaS prod default), so users no longer have to know
+ * the underlying Keycloak coordinates.
+ *
+ * Distinguishes three failure shapes for the operator-relevant cases:
+ *
+ * - `mcpClientId` field absent: the axe server deployment predates the
+ *   field entirely. Surfaces as "needs upgrading".
+ * - `mcpClientId` is `null`: the axe server version supports the field
+ *   but the operator has not configured `KEYCLOAK_MCP_PUBLIC_CLIENT_ID`.
+ *   Surfaces as "ask the operator to configure".
+ * - any non-empty string: returned as-is.
+ *
+ * Other failure modes (unreachable, non-2xx, malformed JSON, missing
+ * `url` / `realm`) all map to `DISCOVERY_FAILED` with a descriptive
+ * message. The caller is expected to surface these errors verbatim.
+ */
+export declare function discoverSSOConfig(serverURL: string, options?: DiscoverSSOConfigOptions): Promise<SSOConfig>;

package/dist/oauth/discoverSSOConfig.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverSSOConfig = discoverSSOConfig;
+const errors_1 = require("./errors");
+const predicates_1 = require("./predicates");
+const userAgent_1 = require("../userAgent");
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+function assertSecureServerURL(serverURL, allowInsecure) {
+    let parsed;
+    try {
+        parsed = new URL(serverURL);
+    }
+    catch {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server URL is not a valid URL: ${serverURL}`);
+    }
+    if (parsed.protocol === "https:")
+        return parsed;
+    if (parsed.protocol === "http:") {
+        const hostname = parsed.host.toLowerCase().replace(/:\d+$/, "");
+        if (LOOPBACK_HOSTS.has(hostname))
+            return parsed;
+        if (allowInsecure)
+            return parsed;
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Refusing to use axe server URL over http:// against non-loopback host ${parsed.host}. Use https:// or pass --allow-insecure-issuer to override (only do this on trusted networks).`);
+    }
+    throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Unsupported axe server URL scheme '${parsed.protocol}'; expected https: or http: (loopback only).`);
+}
+function buildSSOConfigURL(parsed) {
+    const copy = new URL(parsed.toString());
+    copy.search = "";
+    copy.hash = "";
+    copy.pathname = `${copy.pathname.replace(/\/+$/, "")}/api/sso-config`;
+    return copy.toString();
+}
+/**
+ * Fetches and parses the axe server's `/api/sso-config` discovery
+ * endpoint. Used by `axe-auth login` to derive the OAuth issuer URL,
+ * realm, and CLI-specific client ID from the axe server URL the user
+ * supplied (or the SaaS prod default), so users no longer have to know
+ * the underlying Keycloak coordinates.
+ *
+ * Distinguishes three failure shapes for the operator-relevant cases:
+ *
+ * - `mcpClientId` field absent: the axe server deployment predates the
+ *   field entirely. Surfaces as "needs upgrading".
+ * - `mcpClientId` is `null`: the axe server version supports the field
+ *   but the operator has not configured `KEYCLOAK_MCP_PUBLIC_CLIENT_ID`.
+ *   Surfaces as "ask the operator to configure".
+ * - any non-empty string: returned as-is.
+ *
+ * Other failure modes (unreachable, non-2xx, malformed JSON, missing
+ * `url` / `realm`) all map to `DISCOVERY_FAILED` with a descriptive
+ * message. The caller is expected to surface these errors verbatim.
+ */
+async function discoverSSOConfig(serverURL, options = {}) {
+    const allowInsecure = options.allowInsecure ?? false;
+    const parsed = assertSecureServerURL(serverURL, allowInsecure);
+    const url = buildSSOConfigURL(parsed);
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { "User-Agent": userAgent_1.USER_AGENT },
+            signal: options.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Could not reach the axe server at ${url}. Check the --server URL and your network connection.`, { cause });
+    }
+    if (!response.ok) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${url} responded with HTTP ${response.status}. Check the --server URL.`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${url} did not return valid JSON.`, { cause });
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${url} returned a non-object response body.`);
+    }
+    const raw = body;
+    const missing = [];
+    if (!(0, predicates_1.isNonEmptyString)(raw.url))
+        missing.push("url");
+    if (!(0, predicates_1.isNonEmptyString)(raw.realm))
+        missing.push("realm");
+    if (missing.length > 0) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `${url} is missing required field(s): ${missing.join(", ")}`);
+    }
+    if (!("mcpClientId" in raw)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${serverURL} does not advertise OAuth-based MCP authentication. The deployment may need to be upgraded to a version that supports the axe-auth CLI.`);
+    }
+    if (raw.mcpClientId === null) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${serverURL} has not been configured for OAuth-based MCP authentication. Ask your operator to set the KEYCLOAK_MCP_PUBLIC_CLIENT_ID environment variable on the axe server.`);
+    }
+    if (!(0, predicates_1.isNonEmptyString)(raw.mcpClientId)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${serverURL} returned a malformed mcpClientId (expected a non-empty string).`);
+    }
+    return {
+        url: raw.url,
+        realm: raw.realm,
+        mcpClientId: raw.mcpClientId,
+    };
+}

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,140 @@
+"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,
+            walnutURL: loaded.entry.walnutURL,
+        });
+    }
+    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;
+}