@deque/axe-auth 1.1.0-next.adf1ee93 → 1.1.0-next.bd805a7a

package/dist/cli/commonArgs.d.ts

@@ -1,37 +1,18 @@
 import type { ParseArgsConfig } from "node:util";
-/**
- * Default axe server URL for `axe-auth` users on Deque's SaaS prod
- * deployment. The CLI's `--server` flag (and `AXE_SERVER_URL` env)
- * override this; non-prod customers must supply their own walnut URL.
- */
+/** Default axe server URL for Deque SaaS prod. */
 export declare const DEFAULT_WALNUT_URL = "https://axe.deque.com";
 /** Common configuration the CLI verbs share. */
 export interface CommonArgs {
-    /**
-     * axe server URL (walnut). Used by `login` to fetch
-     * `/api/sso-config` and derive the OAuth issuer / realm / client
-     * coordinates. `token` and `logout` operate on the stored entry
-     * alone and ignore this value.
-     */
+    /** axe server URL (walnut). */
     walnutURL: string;
-    /**
-     * Whether to permit non-loopback http walnut/issuer URLs. Loopback
-     * hosts (`localhost` / `127.0.0.1` / `[::1]`) are always allowed
-     * over http; this flag is the opt-in for non-loopback http
-     * deployments.
-     */
+    /** Whether non-loopback http walnut/issuer URLs are permitted. */
     allowInsecureIssuer: boolean;
 }
 /**
- * `parseArgs`-shaped options describing the flags every CLI verb
- * accepts (--server, --allow-insecure-issuer, --no-allow-insecure-issuer).
- * Subcommands spread this into their own `options` so they can add
- * verb-specific flags alongside.
- *
- * Node's `parseArgs` doesn't support `--no-` boolean negation
- * natively, so the opt-out is registered as its own flag. Passing
- * both `--allow-insecure-issuer` and `--no-allow-insecure-issuer` is
- * treated as user error and rejected.
+ * `parseArgs`-shaped options shared by every CLI verb. `parseArgs`
+ * doesn't support `--no-` boolean negation natively, so the opt-out
+ * is registered as its own flag and `parseCommonArgs` rejects passing
+ * both together.
  */
 export declare const COMMON_OPTIONS: NonNullable<ParseArgsConfig["options"]>;
 /** Subset of `parseArgs(...).values` this helper consumes. */
@@ -40,43 +21,15 @@ export interface ParsedCommonValues {
     "allow-insecure-issuer"?: boolean;
     "no-allow-insecure-issuer"?: boolean;
 }
-/**
- * Subset of a stored entry used as a fallback for
- * `allowInsecureIssuer` when the user passes neither
- * `--allow-insecure-issuer` nor `--no-allow-insecure-issuer`.
- * Sourced from `KeyringTokenStore.load()` by the dispatcher.
- *
- * `walnutURL` is carried alongside so the fallback only applies when
- * the user is targeting the same deployment as the stored entry —
- * otherwise a dev-time HTTP-allow setting would silently carry over
- * to a prod login.
- */
+/** Stored fallback for `allowInsecureIssuer` + the `walnutURL` it was minted against. */
 export interface StoredCommonDefaults {
     walnutURL: string;
     allowInsecureIssuer: boolean;
 }
 /**
  * Resolves common configuration from parsed flag values, falling
- * back to `AXE_SERVER_URL` when `--server` is absent and finally to
- * the SaaS prod walnut URL when neither is set.
- *
- * `allowInsecureIssuer` is consumed by `login` (it is forwarded to
- * SSO discovery and the OAuth flow). The fallback to a stored value
- * exists so an interactive re-login on a private dev instance does
- * not need the flag re-passed when the previous login set it. The
- * fallback is gated on the resolved walnut URL matching the stored
- * one: a user logging in to a different deployment must opt back in
- * with `--allow-insecure-issuer` explicitly. The `token` and `logout`
- * verbs do **not** consume this resolved value — they read
- * `allowInsecureIssuer` directly from the keychain entry's metadata,
- * so flag/env input is silently ignored there (and the help text for
- * those verbs documents that).
- *
- * @param values   The `values` object returned from `parseArgs`.
- * @param env      Environment to consult for fallback. Defaults to
- *   `process.env`; injected for test determinism.
- * @param defaults Stored fallback for `allowInsecureIssuer` plus the
- *   `walnutURL` it was minted against. Pass `null` (or omit) when
- *   nothing is stored.
+ * back to `AXE_SERVER_URL` and finally to `DEFAULT_WALNUT_URL`.
+ * `allowInsecureIssuer` falls back to `defaults` only when the
+ * resolved walnut URL matches `defaults.walnutURL`.
  */
 export declare function parseCommonArgs(values: ParsedCommonValues, env?: NodeJS.ProcessEnv, defaults?: StoredCommonDefaults | null): CommonArgs;

package/dist/cli/commonArgs.js

@@ -6,22 +6,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.COMMON_OPTIONS = exports.DEFAULT_WALNUT_URL = void 0;
 exports.parseCommonArgs = parseCommonArgs;
 const remove_trailing_slash_1 = __importDefault(require("remove-trailing-slash"));
-/**
- * Default axe server URL for `axe-auth` users on Deque's SaaS prod
- * deployment. The CLI's `--server` flag (and `AXE_SERVER_URL` env)
- * override this; non-prod customers must supply their own walnut URL.
- */
+/** Default axe server URL for Deque SaaS prod. */
 exports.DEFAULT_WALNUT_URL = "https://axe.deque.com";
 /**
- * `parseArgs`-shaped options describing the flags every CLI verb
- * accepts (--server, --allow-insecure-issuer, --no-allow-insecure-issuer).
- * Subcommands spread this into their own `options` so they can add
- * verb-specific flags alongside.
- *
- * Node's `parseArgs` doesn't support `--no-` boolean negation
- * natively, so the opt-out is registered as its own flag. Passing
- * both `--allow-insecure-issuer` and `--no-allow-insecure-issuer` is
- * treated as user error and rejected.
+ * `parseArgs`-shaped options shared by every CLI verb. `parseArgs`
+ * doesn't support `--no-` boolean negation natively, so the opt-out
+ * is registered as its own flag and `parseCommonArgs` rejects passing
+ * both together.
  */
 exports.COMMON_OPTIONS = {
     server: { type: "string" },
@@ -30,27 +21,9 @@ exports.COMMON_OPTIONS = {
 };
 /**
  * Resolves common configuration from parsed flag values, falling
- * back to `AXE_SERVER_URL` when `--server` is absent and finally to
- * the SaaS prod walnut URL when neither is set.
- *
- * `allowInsecureIssuer` is consumed by `login` (it is forwarded to
- * SSO discovery and the OAuth flow). The fallback to a stored value
- * exists so an interactive re-login on a private dev instance does
- * not need the flag re-passed when the previous login set it. The
- * fallback is gated on the resolved walnut URL matching the stored
- * one: a user logging in to a different deployment must opt back in
- * with `--allow-insecure-issuer` explicitly. The `token` and `logout`
- * verbs do **not** consume this resolved value — they read
- * `allowInsecureIssuer` directly from the keychain entry's metadata,
- * so flag/env input is silently ignored there (and the help text for
- * those verbs documents that).
- *
- * @param values   The `values` object returned from `parseArgs`.
- * @param env      Environment to consult for fallback. Defaults to
- *   `process.env`; injected for test determinism.
- * @param defaults Stored fallback for `allowInsecureIssuer` plus the
- *   `walnutURL` it was minted against. Pass `null` (or omit) when
- *   nothing is stored.
+ * back to `AXE_SERVER_URL` and finally to `DEFAULT_WALNUT_URL`.
+ * `allowInsecureIssuer` falls back to `defaults` only when the
+ * resolved walnut URL matches `defaults.walnutURL`.
  */
 function parseCommonArgs(values, env = process.env, defaults = null) {
     const walnutURL = (0, remove_trailing_slash_1.default)(values.server ?? env.AXE_SERVER_URL ?? exports.DEFAULT_WALNUT_URL);

package/dist/cli/confirm.js

@@ -9,9 +9,6 @@ const node_readline_1 = require("node:readline");
  * default action stays conservative.
  */
 async function confirm(options) {
-    // Annotate after the ?? fallbacks so the union of `Writable |
-    // NodeJS.WriteStream` (from `process.stderr`) collapses to the
-    // base class — otherwise `output.write(...)` is ambiguous.
     const input = options.input ?? process.stdin;
     const output = options.output ?? process.stderr;
     const question = options.question.endsWith(" ")

package/dist/cli/errors.d.ts

@@ -2,19 +2,12 @@
 export type CLIErrorCode = "NOT_AUTHENTICATED" | "USER_CANCELLED" | "ALREADY_AUTHENTICATED" | "OAUTH_FAILED" | "KEYCHAIN_FAILURE";
 /**
  * Thrown from a verb's `run` to signal a known failure. The
- * dispatcher in `src/index.ts` writes `message` to stderr and exits
- * with `exitCode`. The `code` field is the load-bearing
- * discriminator; `exitCode` is derived for shell scripts and is
- * documented in the README.
+ * dispatcher writes `message` to stderr and exits with `exitCode`.
  */
 export declare class CLIError extends Error {
     readonly code: CLIErrorCode;
     readonly exitCode: number;
     constructor(code: CLIErrorCode, message: string);
 }
-/**
- * Returns the `message` of an `Error`-shaped value, or its `String`
- * coercion otherwise. Used in user-facing error templates so
- * callers don't inline the `instanceof` ternary every time.
- */
+/** Returns the `message` of an `Error`, or its `String` coercion otherwise. */
 export declare function describeError(err: unknown): string;

package/dist/cli/errors.js

@@ -11,10 +11,7 @@ const EXIT_CODE_BY_ERROR_CODE = {
 };
 /**
  * Thrown from a verb's `run` to signal a known failure. The
- * dispatcher in `src/index.ts` writes `message` to stderr and exits
- * with `exitCode`. The `code` field is the load-bearing
- * discriminator; `exitCode` is derived for shell scripts and is
- * documented in the README.
+ * dispatcher writes `message` to stderr and exits with `exitCode`.
  */
 class CLIError extends Error {
     code;
@@ -27,11 +24,7 @@ class CLIError extends Error {
     }
 }
 exports.CLIError = CLIError;
-/**
- * Returns the `message` of an `Error`-shaped value, or its `String`
- * coercion otherwise. Used in user-facing error templates so
- * callers don't inline the `instanceof` ternary every time.
- */
+/** Returns the `message` of an `Error`, or its `String` coercion otherwise. */
 function describeError(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/cli/types.d.ts

@@ -4,48 +4,22 @@ import type { LoadResult } from "../oauth/tokenStore";
 import type { CommonArgs } from "./commonArgs";
 /** Mapping passed to `parseArgs` for verb-specific flags. */
 export type VerbOptions = NonNullable<ParseArgsConfig["options"]>;
-/**
- * The injectables every CLI verb sees. The dispatcher fills these in
- * with the real `process.*` streams; tests pass synthetic values.
- * Verb-specific overrides (e.g. `getToken`, `authorize`) extend this
- * interface in the relevant verb's module — TS allows the dispatcher
- * to pass a plain `CommandDeps` because the verb-specific extras are
- * declared optional.
- */
+/** Injectables every CLI verb sees. Dispatcher fills with `process.*`; tests pass synthetic values. */
 export interface CommandDeps {
-    /**
-     * Standard input. Carries an optional `isTTY` so verbs like
-     * `login` can branch on interactivity. Real `process.stdin`
-     * satisfies the shape; test fixtures using `Readable.from([])`
-     * leave `isTTY` undefined, which coerces to `false`.
-     */
+    /** `isTTY` is optional so `Readable.from([])` test fixtures coerce to non-TTY. */
     stdin: Readable & {
         isTTY?: boolean;
     };
     stdout: Writable;
     stderr: Writable;
     /**
-     * Pre-loaded result of `KeyringTokenStore.load()`, populated by the
-     * dispatcher when it ran the keychain read to derive the
-     * `parseCommonArgs` fallback. Verbs prefer this over loading
-     * again so a single `axe-auth token` invocation hits the keychain
-     * once instead of three times. Tests typically leave this
-     * undefined and inject a fake `tokenStore` instead.
+     * Pre-loaded result of `KeyringTokenStore.load()` from the
+     * dispatcher's keychain read, so a single CLI invocation hits the
+     * keychain once instead of N times.
      */
     loadedEntry?: LoadResult;
 }
-/**
- * Specification of a single CLI verb. The dispatcher in
- * `src/index.ts` consumes one of these per registered command:
- * parses argv, resolves common args, prints `helpText` for `--help`,
- * runs `run`, and translates thrown `CLIError`s (see `./errors`)
- * into exit codes.
- *
- * Each verb narrows the `run` parameters to its own
- * `CommonArgs & <Verb>Flags` and `<Verb>Deps`. Method-shorthand
- * bivariance lets that narrower signature satisfy this interface
- * without casts at the verb definition.
- */
+/** Specification of a single CLI verb consumed by the dispatcher. */
 export interface CommandSpec {
     /** Verb name, e.g. `"login"`. */
     readonly name: string;
@@ -53,27 +27,13 @@ export interface CommandSpec {
     readonly summary: string;
     /** Full help text printed for `axe-auth <verb> --help`. */
     readonly helpText: string;
-    /**
-     * Verb-specific `parseArgs` options. Common options
-     * (`--server` / `--allow-insecure-issuer` / `--no-allow-insecure-issuer`)
-     * are added by the dispatcher; do not duplicate them here.
-     */
+    /** Verb-specific `parseArgs` options; common options are added by the dispatcher. */
     readonly options: VerbOptions;
-    /**
-     * `true` if this verb cannot run without a usable walnut URL
-     * (login). `false` for verbs that operate on the stored entry
-     * alone (token, logout) and have their own "not authenticated" /
-     * "already logged out" handling for the empty-entry case. With
-     * the SaaS prod default in `parseCommonArgs`, the walnut URL is
-     * never strictly missing, but this flag remains for future
-     * required-config additions.
-     */
+    /** `true` if this verb cannot run without a usable walnut URL (login). */
     readonly requiresConfig: boolean;
     /**
-     * Run the verb with already-resolved args and the dispatcher's
-     * deps. Throw a `CLIError` to signal a known failure with an
-     * explicit exit code; throw any other error for a generic exit
-     * code 2 plus the error message on stderr.
+     * Throw `CLIError` for a known failure with an explicit exit code;
+     * any other error becomes exit code 2 with the message on stderr.
      */
     run(args: CommonArgs, deps: CommandDeps): Promise<void>;
 }

package/dist/commands/login.d.ts

@@ -17,10 +17,7 @@ export interface LoginDeps extends CommandDeps {
      * so the pre-check and post-flow save agree on the keychain entry.
      */
     tokenStore?: TokenStore;
-    /**
-     * Override the confirmation prompt (for tests). Receives the
-     * issuer URL and returns whether the user wants to proceed.
-     */
+    /** Override the confirmation prompt (for tests). */
     confirm?: (prompt: string) => Promise<boolean>;
 }
 /** Verb-specific flags for `axe-auth login`. */

package/dist/commands/login.js

@@ -32,9 +32,6 @@ const loginCommand = {
                 output: deps.stderr,
             }));
         const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
-        // 1. Ask the axe server where its Keycloak lives and which client to use.
-        //    This is the only step that hits the axe server directly; from here on
-        //    the CLI talks to Keycloak using the discovered coordinates.
         let ssoConfig;
         try {
             ssoConfig = await discoverFn(args.walnutURL, {
@@ -49,16 +46,11 @@ const loginCommand = {
         }
         const issuerURL = `${(0, remove_trailing_slash_1.default)(ssoConfig.url)}/auth/realms/${ssoConfig.realm}`;
         const clientId = ssoConfig.mcpClientId;
-        // 2. Re-auth confirmation. Same UX as the previous flag-driven
-        //    flow, but the comparison is against the *discovered* issuer
-        //    + client, not user-supplied flags.
         if (!args.force) {
             const stored = deps.loadedEntry ?? (await tokenStore.load());
             if (!stored.ok && stored.reason !== "empty") {
-                // Existing entry is unreadable (corrupt or stored under a
-                // schema we can't migrate). authorize() will overwrite it
-                // either way, but the user deserves a breadcrumb for what
-                // disappeared.
+                // authorize() will overwrite either way, but the user
+                // deserves a breadcrumb for what disappeared.
                 deps.stderr.write(`axe-auth: replacing unreadable stored credentials (${stored.reason}).\n`);
             }
             if (stored.ok) {
@@ -86,9 +78,8 @@ const loginCommand = {
                 }
             }
         }
-        // 3. Drive the OAuth flow. The originating axe server URL rides along
-        //    so it lands in the StoredEntry and future verbs (re-discovery,
-        //    revoke) can operate without user-supplied flags.
+        // `walnutURL` lands in the StoredEntry so future verbs
+        // (re-discovery, revoke) operate without user-supplied flags.
         try {
             await authorizeFn({
                 issuerURL,

package/dist/commands/logout.js

@@ -16,8 +16,6 @@ const logoutCommand = {
         const discoverFn = deps.discoverOIDC ?? discoverOIDC_1.discoverOIDC;
         const revokeFn = deps.revokeRefreshToken ?? revokeToken_1.revokeRefreshToken;
         const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
-        // Prefer the entry the dispatcher already loaded; only fall back
-        // to a fresh read when there isn't one (test path).
         const loaded = deps.loadedEntry ?? (await tokenStore.load());
         if (!loaded.ok) {
             if (loaded.reason === "empty") {

package/dist/commands/token.js

@@ -15,10 +15,6 @@ const tokenCommand = {
     async run(_args, deps) {
         const getToken = deps.getToken ?? getValidAccessToken_1.getValidAccessToken;
         const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
-        // Stored entry is the only source of truth: single-entry-per-machine
-        // model, the blob carries the issuer/client coordinates the tokens
-        // were minted against, and there is no longer a flag to override
-        // them with.
         const loaded = deps.loadedEntry ?? (await tokenStore.load());
         let token;
         try {

package/dist/index.js

@@ -14,7 +14,6 @@ const logout_1 = __importDefault(require("./commands/logout"));
 const token_1 = __importDefault(require("./commands/token"));
 const errors_1 = require("./cli/errors");
 const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8"));
-// Iteration order is the order verbs appear in `axe-auth --help`.
 const COMMANDS = [
     login_1.default,
     logout_1.default,
@@ -82,14 +81,9 @@ async function dispatch(argv) {
         process.stdout.write(`${command.helpText}\n`);
         return 0;
     }
-    // Best-effort load of the stored entry. Used to (a) supply the
-    // `allowInsecureIssuer` fallback on flag-free invocations, and (b)
-    // hand the entry to the verb via `deps.loadedEntry` so a single
-    // `axe-auth token` invocation hits the keychain once instead of
-    // twice. A read failure here is non-fatal — `parseCommonArgs`
-    // always succeeds (the SaaS prod default fills any unsupplied
-    // walnut URL), and verbs that need a stored entry have their own
-    // empty/corrupt-entry handling.
+    // Best-effort load: handed to verbs via `deps.loadedEntry` so a
+    // single CLI invocation hits the keychain once. Read failure is
+    // non-fatal — verbs handle their own empty/corrupt cases.
     let defaults = null;
     let loadedEntry;
     try {
@@ -102,9 +96,8 @@ async function dispatch(argv) {
         }
     }
     catch {
-        // Keychain unavailable: leave defaults null. login will fail at
-        // `tokenStore.save()` with a clearer error than we can produce
-        // here; token / logout's own empty-entry path handles it.
+        // Keychain unavailable: leave defaults null. Verbs surface their
+        // own clearer errors at the actual save / read site.
     }
     let common;
     try {

package/dist/oauth/authorizationURL.d.ts

@@ -10,12 +10,7 @@ export interface BuildAuthorizationURLOptions {
     codeChallenge: string;
     /** CSRF `state` value, echoed by the auth server and validated on callback. */
     state: string;
-    /**
-     * OAuth scopes to request. No default — callers must choose explicitly.
-     * Keycloak-idiomatic value for a refresh-token flow is `["offline_access"]`;
-     * Google uses `access_type=offline` (a custom parameter) instead; Auth0
-     * tolerates `offline_access` only with specific audience settings.
-     */
+    /** OAuth scopes to request. No default; callers choose explicitly. */
     scopes: readonly string[];
 }
 /**

package/dist/oauth/authorizationURL.js

@@ -2,12 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAuthorizationURL = buildAuthorizationURL;
 const errors_1 = require("./errors");
-// Names of OAuth params we always set. If any of these are already
-// present on the authorization endpoint URL returned by discovery,
-// something is wrong on the server side (or with the caller's
-// endpoint override) and silently keeping both values would be a
-// security trap: the authorization server's disambiguation is
-// unspecified and varies by implementation.
+// Pre-existing values for these on the authorization endpoint are a
+// security trap: the auth server's disambiguation is unspecified.
 const OAUTH_REQUIRED_PARAMS = [
     "response_type",
     "client_id",

package/dist/oauth/authorize.d.ts

@@ -2,72 +2,34 @@ import type { TokenSet } from "./tokenResponse";
 import { type TokenStore } from "./tokenStore";
 /** Options for `authorize`. */
 export interface AuthorizeOptions {
-    /**
-     * 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.
-     */
+    /** Issuer URL the OIDC discovery document advertises (e.g. `${serverURL}/realms/${realm}` for Keycloak). */
     issuerURL: string;
     /** OAuth client ID registered with the authorization server. */
     clientId: string;
-    /**
-     * Originating walnut (axe server) URL the user supplied (or the
-     * SaaS prod default) at login. Persisted in the stored entry
-     * alongside the OAuth coordinates so future verbs can re-discover
-     * `/api/sso-config` without user-supplied flags.
-     */
+    /** Persisted alongside the tokens so future verbs can re-discover `/api/sso-config` without flags. */
     walnutURL: string;
-    /**
-     * OAuth scopes to request. Required — this library has no opinion
-     * about which scopes your provider expects. Keycloak callers who
-     * want a refresh token typically pass `["offline_access"]`; Google
-     * uses `access_type=offline` as a separate query param and
-     * therefore needs an empty scope list plus that param threaded
-     * through elsewhere.
-     */
+    /** OAuth scopes to request. Keycloak callers typically pass `["offline_access"]` for a refresh token. */
     scopes: readonly string[];
     /** Max time to wait for the loopback callback, in milliseconds. */
     timeoutMs?: number;
     /** Aborts the in-flight discovery, callback wait, and token exchange. */
     signal?: AbortSignal;
-    /**
-     * Override for the token persistence layer. Defaults to a fresh
-     * `KeyringTokenStore()` (single keychain entry per machine; the
-     * blob carries its own issuer/client coordinates).
-     */
+    /** Override for the token persistence layer. */
     tokenStore?: TokenStore;
     /** Override for the system browser launcher. Injected for tests. */
     openBrowser?: (url: string) => void;
-    /**
-     * Called with the authorization URL just before the browser launch.
-     * The default prints to stderr only when stderr is a TTY, so a
-     * parent CLI consuming this library as a dependency does not
-     * double-print. Pass a custom handler to route the URL through your
-     * own UI, or `() => {}` to suppress entirely.
-     */
+    /** Called with the authorization URL just before the browser launch. Default prints to stderr only when stderr is a TTY. */
     onAuthorizationUrl?: (url: string) => void;
     /**
-     * Called for soft warnings that are not errors but warrant user
-     * attention (e.g. `offline_access` was requested but the server did
-     * not return a `refresh_token`, or the browser failed to launch).
-     * 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 entirely.
-     *
-     * Non-TTY callers who want warning visibility (log files, parent
-     * CLIs, background workers) should pass an explicit handler.
-     * Dropped warnings have no visible symptom at the time they fire —
-     * users only discover the consequence later (e.g. being prompted to
-     * re-authenticate at the next session).
+     * Called for soft warnings (e.g. requested `offline_access` but the
+     * server returned no refresh token, or the browser failed to
+     * launch). Default prints to stderr only when stderr is a TTY.
+     * Non-TTY callers who want warning visibility should pass an
+     * explicit handler — dropped warnings have no symptom at the time
+     * they fire; users discover the consequence later.
      */
     onWarning?: (message: string) => void;
-    /**
-     * Forwarded to the discovery step. Loopback hosts (`localhost` /
-     * `127.0.0.1` / `[::1]`) are always permitted over http; this flag
-     * is the opt-in for non-loopback http issuers and for non-loopback
-     * http endpoints returned by discovery. Default `false`.
-     */
+    /** Forwarded to discovery; permits non-loopback http issuers + endpoints. */
     allowInsecureIssuer?: boolean;
 }
 /**

package/dist/oauth/authorize.js

@@ -39,10 +39,8 @@ function defaultOnWarning(message) {
  */
 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.
+    // 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,

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/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/refreshTokens.js

@@ -53,9 +53,6 @@ async function refreshTokens(options) {
         await (0, tokenResponse_1.throwTokenEndpointError)(response, "Token refresh");
     }
     const fresh = await (0, tokenResponse_1.parseTokenResponse)(response, issuedAt, options.tokenEndpoint);
-    // Preserve the input refresh token if the server didn't rotate.
-    // Keycloak rotates by default; others (e.g. Okta with some
-    // configs) don't.
     return {
         ...fresh,
         refreshToken: fresh.refreshToken ?? options.refreshToken,

package/dist/oauth/tokenResponse.d.ts

@@ -1,18 +1,4 @@
-/**
- * Tokens returned by a successful token-endpoint call (authorization
- * code exchange, refresh-token grant, etc.).
- *
- * `refreshToken` is optional because not all flows return one. On
- * authorization-code exchange it's absent if the caller did not
- * request `offline_access` (or the provider equivalent); on refresh
- * some providers rotate tokens (return a new one) while others don't
- * (the caller should keep the existing refresh token).
- *
- * `grantedScope` reflects the authorization server's `scope` response
- * field when present. RFC 6749 §5.1 says `scope` is required in the
- * response when the granted set differs from the requested set; many
- * servers send it unconditionally.
- */
+/** Tokens returned by a successful token-endpoint call. */
 export interface TokenSet {
     /** Access token for authenticated API calls. */
     accessToken: string;
@@ -24,31 +10,13 @@ export interface TokenSet {
     grantedScope?: string;
 }
 /**
- * Reads a non-2xx response body and throws
- * `OAuthFlowError("TOKEN_EXCHANGE_FAILED", …)` with the OAuth
- * `error` / `error_description` surfaced in both message and details
- * when present. Shared by both the authorization-code exchange and
- * refresh-token paths since the error contract is identical.
- *
- * @param context Short human-readable description of which call
- *   failed ("Token exchange", "Token refresh", etc.). Appears in the
- *   error message.
+ * Reads a non-2xx response body and throws `TOKEN_EXCHANGE_FAILED`
+ * with the OAuth `error` / `error_description` surfaced when present.
  */
 export declare function throwTokenEndpointError(response: Response, context: string): Promise<never>;
 /**
- * Parses a 2xx response body from an RFC 6749 §5.1 token endpoint
- * (authorization-code exchange, refresh-token grant, etc.) into a
- * `TokenSet`. Validates the required shape (`access_token`,
- * `expires_in`, Bearer `token_type`) and converts the relative
- * `expires_in` into an absolute `expiresAt` using `issuedAt`.
- *
- * @param response The HTTP response (must be 2xx; caller handles
- *   error statuses via `throwTokenEndpointError`).
- * @param issuedAt The timestamp captured just before the network
- *   call. Slightly conservative — the token actually expires
- *   `expires_in` seconds from when the server issued it, so the
- *   effective usable window is `expires_in - RTT`, which errs toward
- *   "expires sooner" rather than "expires later."
- * @param endpointURL URL used for error messages.
+ * Parses a 2xx response from an RFC 6749 §5.1 token endpoint into a
+ * `TokenSet`. `issuedAt` is the timestamp captured just before the
+ * network call; the resulting `expiresAt` is conservative by ~RTT.
  */
 export declare function parseTokenResponse(response: Response, issuedAt: number, endpointURL: string): Promise<TokenSet>;

package/dist/oauth/tokenResponse.js

@@ -4,10 +4,8 @@ exports.throwTokenEndpointError = throwTokenEndpointError;
 exports.parseTokenResponse = parseTokenResponse;
 const errors_1 = require("./errors");
 const predicates_1 = require("./predicates");
-// RFC 6749 §5.1 describes `expires_in` as "the lifetime in seconds"
-// without pinning the JSON type, and some providers historically send
-// numeric strings. Accept both; reject anything non-positive or
-// non-finite.
+// RFC 6749 §5.1 doesn't pin the JSON type and some providers send
+// numeric strings; accept both, reject non-positive or non-finite.
 function parseExpiresIn(v) {
     if (typeof v === "number" && Number.isFinite(v) && v > 0)
         return v;
@@ -37,15 +35,8 @@ function parseErrorBody(body) {
     };
 }
 /**
- * Reads a non-2xx response body and throws
- * `OAuthFlowError("TOKEN_EXCHANGE_FAILED", …)` with the OAuth
- * `error` / `error_description` surfaced in both message and details
- * when present. Shared by both the authorization-code exchange and
- * refresh-token paths since the error contract is identical.
- *
- * @param context Short human-readable description of which call
- *   failed ("Token exchange", "Token refresh", etc.). Appears in the
- *   error message.
+ * Reads a non-2xx response body and throws `TOKEN_EXCHANGE_FAILED`
+ * with the OAuth `error` / `error_description` surfaced when present.
  */
 async function throwTokenEndpointError(response, context) {
     const body = await response.text().catch(() => "");
@@ -63,20 +54,9 @@ async function throwTokenEndpointError(response, context) {
     throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `${context} failed with HTTP ${response.status}${suffix}`, Object.keys(details).length > 0 ? { details } : undefined);
 }
 /**
- * Parses a 2xx response body from an RFC 6749 §5.1 token endpoint
- * (authorization-code exchange, refresh-token grant, etc.) into a
- * `TokenSet`. Validates the required shape (`access_token`,
- * `expires_in`, Bearer `token_type`) and converts the relative
- * `expires_in` into an absolute `expiresAt` using `issuedAt`.
- *
- * @param response The HTTP response (must be 2xx; caller handles
- *   error statuses via `throwTokenEndpointError`).
- * @param issuedAt The timestamp captured just before the network
- *   call. Slightly conservative — the token actually expires
- *   `expires_in` seconds from when the server issued it, so the
- *   effective usable window is `expires_in - RTT`, which errs toward
- *   "expires sooner" rather than "expires later."
- * @param endpointURL URL used for error messages.
+ * Parses a 2xx response from an RFC 6749 §5.1 token endpoint into a
+ * `TokenSet`. `issuedAt` is the timestamp captured just before the
+ * network call; the resulting `expiresAt` is conservative by ~RTT.
  */
 async function parseTokenResponse(response, issuedAt, endpointURL) {
     let parsed;

package/dist/oauth/tokenStore.d.ts

@@ -108,6 +108,29 @@ export type BlobChainResult = {
  * and `MIGRATORS` and applies the latest-shape check on top.
  */
 export declare function parseAndMigrateBlob(raw: string | null, expectedVersion?: number, migrators?: ReadonlyMap<number, (old: unknown) => unknown | null>): BlobChainResult;
+/**
+ * Builds the user-facing keychain error message. Platform is a
+ * parameter (defaulting to `process.platform`) so tests can drive each
+ * branch without mocking the runtime; mirrors the pattern in
+ * `platformKeyringHint`.
+ *
+ * The Windows-specific size-limit message is only used when the
+ * underlying error matches the binding's "longer than the platform
+ * limit" wording AND the runtime is win32 — that combination is the
+ * only way the size cap actually manifests in practice. On other
+ * platforms (or for any other binding error) we fall back to the
+ * generic per-platform hint.
+ */
+export declare function keyringErrorMessage(op: string, cause: unknown, platform?: NodeJS.Platform): string;
+/**
+ * Detects the `@napi-rs/keyring` error string for "value too large".
+ * In practice only Windows Credential Manager triggers this — its
+ * stored values are capped at 2560 UTF-16 chars; macOS Keychain and
+ * Linux libsecret have no comparable limit. Exported (but not
+ * re-exported from the package index) so tests can exercise the
+ * detector independently of the wrap path.
+ */
+export declare function isKeyringSizeError(cause: unknown): boolean;
 /**
  * Returns a per-platform hint appended to keychain error messages so
  * users see actionable guidance for their OS instead of generic or

package/dist/oauth/tokenStore.js

@@ -3,29 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyringTokenStore = exports.STORED_BLOB_VERSION = void 0;
 exports.shouldChunkForKeyring = shouldChunkForKeyring;
 exports.parseAndMigrateBlob = parseAndMigrateBlob;
+exports.keyringErrorMessage = keyringErrorMessage;
+exports.isKeyringSizeError = isKeyringSizeError;
 exports.platformKeyringHint = platformKeyringHint;
 exports.chunkBlobForKeyring = chunkBlobForKeyring;
 const errors_1 = require("./errors");
 const keyringBinding_1 = require("./keyringBinding");
-// On macOS: Keychain generic password item with the service name below.
-// On Windows: Credential Manager entry. On Linux: Secret Service / libsecret.
-// Exposed as a human-readable string because these all surface the service
-// name in OS UIs (Keychain Access, credmgr.exe, seahorse).
 const SERVICE_NAME = "axe-auth";
-// Single keychain entry per machine on macOS / Linux. (Windows splits
-// across `credentials.0`, `credentials.1`, … — see `CHUNK_LIMIT`
-// below.) The blob it holds is fully self-describing (issuerURL,
-// clientId, allowInsecureIssuer, plus the tokens), so verbs that
-// don't pass `--server` / `--realm` / `--client-id` can resolve their
-// config from the entry.
-//
-// Account name is human-readable so users investigating the entry in
-// macOS Keychain Access (or `secret-tool` on Linux, credmgr on
-// Windows) can tell what it is. Not versioned: the schema version
-// lives inside the blob and migrators handle the upgrade path. Note:
-// Windows entries hold base64-encoded JSON rather than the raw JSON
-// macOS / Linux store, so a Windows user inspecting their Credential
-// Manager will see opaque base64; that's a side effect of chunking.
+// On Windows the blob is base64-encoded and split across
+// `credentials.0`, `credentials.1`, … entries (see `CHUNK_LIMIT`); a
+// Windows dev inspecting Credential Manager will see opaque base64.
 const ACCOUNT_NAME = "credentials";
 // Windows Credential Manager caps stored values at 2560 UTF-16 code
 // units, which large OAuth access-token JWTs (many groups/roles
@@ -158,10 +145,6 @@ function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION,
     const storedVersion = getStoredVersion(parsed);
     if (storedVersion === null)
         return { ok: false, reason: "corrupt" };
-    // Walk the migrator chain until we reach the expected version. A
-    // missing or null-returning migrator means the old blob cannot be
-    // upgraded; surface that so callers can prompt re-auth with a
-    // clear signal instead of silently returning `empty`.
     let current = parsed;
     let currentVersion = storedVersion;
     while (currentVersion !== expectedVersion) {
@@ -175,8 +158,6 @@ function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION,
         }
         const nextVersion = getStoredVersion(next);
         if (nextVersion === null || nextVersion <= currentVersion) {
-            // Migrator output is malformed or didn't advance. Treat the
-            // stored blob as un-migratable rather than loop forever.
             return { ok: false, reason: "version-mismatch", storedVersion };
         }
         current = next;
@@ -194,8 +175,42 @@ function wrapKeyringError(op, cause) {
     if (cause instanceof errors_1.OAuthFlowError) {
         throw cause;
     }
+    throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", keyringErrorMessage(op, cause), {
+        cause,
+    });
+}
+/**
+ * Builds the user-facing keychain error message. Platform is a
+ * parameter (defaulting to `process.platform`) so tests can drive each
+ * branch without mocking the runtime; mirrors the pattern in
+ * `platformKeyringHint`.
+ *
+ * The Windows-specific size-limit message is only used when the
+ * underlying error matches the binding's "longer than the platform
+ * limit" wording AND the runtime is win32 — that combination is the
+ * only way the size cap actually manifests in practice. On other
+ * platforms (or for any other binding error) we fall back to the
+ * generic per-platform hint.
+ */
+function keyringErrorMessage(op, cause, platform = process.platform) {
+    if (platform === "win32" && isKeyringSizeError(cause)) {
+        return `System keychain ${op} failed: Windows Credential Manager limits stored values to 2560 UTF-16 characters. Large OAuth access-token JWTs (many groups/roles claims) commonly exceed this.`;
+    }
     const causeMessage = cause instanceof Error ? cause.message : String(cause);
-    throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `System keychain ${op} failed: ${causeMessage}. ${platformKeyringHint()}`, { cause });
+    return `System keychain ${op} failed: ${causeMessage}. ${platformKeyringHint(platform)}`;
+}
+/**
+ * Detects the `@napi-rs/keyring` error string for "value too large".
+ * In practice only Windows Credential Manager triggers this — its
+ * stored values are capped at 2560 UTF-16 chars; macOS Keychain and
+ * Linux libsecret have no comparable limit. Exported (but not
+ * re-exported from the package index) so tests can exercise the
+ * detector independently of the wrap path.
+ */
+function isKeyringSizeError(cause) {
+    if (!(cause instanceof Error))
+        return false;
+    return /longer than the platform limit/.test(cause.message);
 }
 /**
  * Returns a per-platform hint appended to keychain error messages so
@@ -388,10 +403,6 @@ class KeyringTokenStore {
      * could trip it.
      */
     #saveChunked(parts) {
-        // Read previous N before any writes so the cleanup sweep is
-        // bounded. If the previous chunk 0 is missing or its header is
-        // unparseable we have no upper bound, so fall back to the full
-        // safety range as a one-time defensive recovery.
         const previousN = this.#previousChunkN();
         for (let i = parts.length - 1; i >= 1; i--) {
             this.#entry(`${ACCOUNT_NAME}.${i}`).setPassword(parts[i]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.1.0-next.adf1ee93",
+  "version": "1.1.0-next.bd805a7a",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",