@deque/axe-auth 1.1.0-next.cc219a94 → 1.1.0-next.cd01fe5a

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/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

@@ -1,5 +1,16 @@
 import { type KeyringEntryFactory } from "./keyringBinding";
 import type { TokenSet } from "./tokenResponse";
+/**
+ * Whether `KeyringTokenStore` should split the stored blob across
+ * multiple keychain entries on this platform. Windows-only: Credential
+ * Manager has a 2560-byte per-entry cap that large OAuth tokens
+ * routinely exceed. macOS Keychain and Linux libsecret have no
+ * comparable limit, and on macOS each entry is independently lockable
+ * (chunking there would multiply per-entry ACL prompts). Exported
+ * (parameterized for tests) so the chunking path can be exercised
+ * deterministically.
+ */
+export declare function shouldChunkForKeyring(platform?: NodeJS.Platform): boolean;
 /**
  * Current on-disk blob schema version. Exported so consumers can
  * display "stored v:N, expected v:M" diagnostics when `load()` returns
@@ -100,6 +111,14 @@ 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: the underlying
+ * cause's text plus a per-platform hint. Platform is a parameter
+ * (defaulting to `process.platform`) so tests can drive each branch
+ * without mocking the runtime; mirrors the pattern in
+ * `platformKeyringHint`.
+ */
+export declare function keyringErrorMessage(op: string, cause: unknown, platform?: NodeJS.Platform): string;
 /**
  * Returns a per-platform hint appended to keychain error messages so
  * users see actionable guidance for their OS instead of generic or
@@ -111,14 +130,42 @@ export declare function platformKeyringHint(platform?: NodeJS.Platform): string;
 /**
  * `TokenStore` backed by the operating system's native keychain via
  * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux
- * Secret Service). One entry per machine, keyed by a fixed account
- * name; the blob carries its own issuer/client coordinates so verbs
- * can recover full config without per-issuer keying.
+ * Secret Service). On macOS and Linux the blob lives in a single entry
+ * keyed by the fixed `credentials` account name. On Windows the blob
+ * is split across `credentials.0`, `credentials.1`, … entries to fit
+ * under Credential Manager's 2560-byte (1280 UTF-16 char) per-entry
+ * cap; see `shouldChunkForKeyring`.
+ *
+ * The blob carries its own issuer/client coordinates so verbs can
+ * recover full config without per-issuer keying.
  */
 export declare class KeyringTokenStore implements TokenStore {
     #private;
+    /**
+     * @param entryFactory Injection seam for `@napi-rs/keyring` entries.
+     *   Defaults to the production lazy-resolved factory; tests pass a
+     *   recording / faking variant.
+     */
     constructor(entryFactory?: KeyringEntryFactory);
+    /**
+     * @internal Test seam. Constructs a store with an explicit chunking
+     * decision instead of the platform-determined default, so the
+     * chunked path can be exercised on macOS/Linux CI and the unchunked
+     * path on Windows CI. Production code must use the regular
+     * constructor and let `shouldChunkForKeyring()` decide — passing
+     * `chunked: true` on macOS would write data that the regular
+     * constructor wouldn't be able to read.
+     */
+    static forTesting(entryFactory: KeyringEntryFactory, chunked: boolean): KeyringTokenStore;
     save(entry: StoredEntry): Promise<void>;
     load(): Promise<LoadResult>;
     clear(): Promise<void>;
 }
+/**
+ * Splits `blob` into the N parts that `KeyringTokenStore.#saveChunked`
+ * writes to `credentials.0..N-1`. Chunk 0 is prefixed with `<N>\n` so
+ * the reader can learn N from a single getPassword call. Each chunk
+ * stays under `CHUNK_LIMIT` UTF-16 characters; throws if the blob would
+ * require more than `MAX_CHUNKS` chunks. Exported for tests.
+ */
+export declare function chunkBlobForKeyring(blob: string): string[];