@deque/axe-auth 1.1.0-next.5c407e02 → 1.1.0-next.689a4b1a

package/dist/oauth/openBrowser.d.ts

@@ -7,13 +7,24 @@ export interface OpenBrowserOptions {
     platform?: NodeJS.Platform;
     /** Override for `child_process.spawn`. Used by tests. */
     spawnFn?: SpawnFn;
+    /**
+     * Override for `process.env.BROWSER`. The de-facto convention shared
+     * with `xdg-open` and Python's `webbrowser`: when set, it names the
+     * command to invoke instead of the platform default. Parsed shlex-style
+     * (POSIX shell tokenization) so values like `firefox --new-window` or
+     * `/path/with\ spaces/firefox` work as expected. An empty or missing
+     * value falls back to the platform default.
+     */
+    browserEnv?: string;
 }
 /**
  * Launches the system browser at `url` in a detached child process.
- * Returns synchronously once the child is spawned — completion of the
- * browser load is intentionally not awaited.
+ * Honors `$BROWSER` when set, falling back to the platform default
+ * (`open` / `xdg-open` / `cmd start`). Returns synchronously once the
+ * child is spawned — completion of the browser load is intentionally
+ * not awaited.
  *
  * @param url Absolute URL to open.
- * @param options Platform/spawn overrides; only exposed for tests.
+ * @param options Platform/spawn/env overrides; only exposed for tests.
  */
 export declare function openBrowser(url: string, options?: OpenBrowserOptions): void;

package/dist/oauth/openBrowser.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.openBrowser = openBrowser;
 const node_child_process_1 = require("node:child_process");
+const shlex_1 = require("shlex");
 const errors_1 = require("./errors");
 // On Windows `start` is a cmd.exe builtin, not a standalone binary.
 // The empty `""` pair is a positional placeholder for the window
@@ -26,7 +27,11 @@ function windowsCommand(url) {
         args: ["/c", "start", '""', url.replace(/[&|^<>"%\r\n]/g, (c) => `^${c}`)],
     };
 }
-function browserCommand(platform, url) {
+function browserCommand(platform, url, browserOverride) {
+    if (browserOverride && browserOverride.length > 0) {
+        const [command, ...extraArgs] = browserOverride;
+        return { command, args: [...extraArgs, url] };
+    }
     switch (platform) {
         case "darwin":
             return { command: "open", args: [url] };
@@ -47,16 +52,28 @@ function browserCommand(platform, url) {
 }
 /**
  * Launches the system browser at `url` in a detached child process.
- * Returns synchronously once the child is spawned — completion of the
- * browser load is intentionally not awaited.
+ * Honors `$BROWSER` when set, falling back to the platform default
+ * (`open` / `xdg-open` / `cmd start`). Returns synchronously once the
+ * child is spawned — completion of the browser load is intentionally
+ * not awaited.
  *
  * @param url Absolute URL to open.
- * @param options Platform/spawn overrides; only exposed for tests.
+ * @param options Platform/spawn/env overrides; only exposed for tests.
  */
 function openBrowser(url, options = {}) {
     const platform = options.platform ?? process.platform;
     const spawnFn = options.spawnFn ?? node_child_process_1.spawn;
-    const { command, args } = browserCommand(platform, url);
+    const browserEnv = options.browserEnv ?? process.env.BROWSER;
+    let browserOverride;
+    if (browserEnv && browserEnv.length > 0) {
+        try {
+            browserOverride = (0, shlex_1.split)(browserEnv);
+        }
+        catch (cause) {
+            throw new errors_1.OAuthFlowError("BROWSER_LAUNCH_FAILED", `Failed to parse $BROWSER (${browserEnv}). Open this URL manually:\n${url}`, { cause });
+        }
+    }
+    const { command, args } = browserCommand(platform, url, browserOverride);
     let child;
     try {
         child = spawnFn(command, args, {

package/dist/oauth/refreshTokens.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.refreshTokens = refreshTokens;
 const errors_1 = require("./errors");
 const tokenResponse_1 = require("./tokenResponse");
+const userAgent_1 = require("../userAgent");
 /**
  * Exchanges a refresh token for a fresh access token via RFC 6749 §6.
  *
@@ -39,6 +40,7 @@ async function refreshTokens(options) {
             headers: {
                 "Content-Type": "application/x-www-form-urlencoded",
                 Accept: "application/json",
+                "User-Agent": userAgent_1.USER_AGENT,
             },
             body,
             signal: options.signal,
@@ -51,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/revokeToken.d.ts

@@ -0,0 +1,28 @@
+/** Options for `revokeRefreshToken`. */
+export interface RevokeRefreshTokenOptions {
+    /** Revocation endpoint resolved from OIDC discovery. */
+    revocationEndpoint: string;
+    /** OAuth client ID. */
+    clientId: string;
+    /** The refresh token to revoke server-side. */
+    refreshToken: string;
+    /** Aborts the underlying fetch when fired. */
+    signal?: AbortSignal;
+}
+/**
+ * Revokes a refresh token via RFC 7009. Servers SHOULD return 200
+ * regardless of whether the token was valid (the spec doesn't want
+ * revocation to be a probing oracle for token existence). In
+ * practice this helper still surfaces network errors and any
+ * non-2xx response from the revocation endpoint, on the assumption
+ * that a 4xx is more likely a misconfiguration the user should hear
+ * about than a routine condition to swallow.
+ *
+ * Throws a plain `Error` rather than `OAuthFlowError`: revocation
+ * is best-effort cleanup invoked from `axe-auth logout`, and the
+ * caller already handles failure by warning + continuing with the
+ * local clear. Adding a dedicated `OAuthFlowError` code for this
+ * one shallow operation is more bloat than the discrimination is
+ * worth.
+ */
+export declare function revokeRefreshToken(options: RevokeRefreshTokenOptions): Promise<void>;

package/dist/oauth/revokeToken.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.revokeRefreshToken = revokeRefreshToken;
+const userAgent_1 = require("../userAgent");
+/**
+ * Revokes a refresh token via RFC 7009. Servers SHOULD return 200
+ * regardless of whether the token was valid (the spec doesn't want
+ * revocation to be a probing oracle for token existence). In
+ * practice this helper still surfaces network errors and any
+ * non-2xx response from the revocation endpoint, on the assumption
+ * that a 4xx is more likely a misconfiguration the user should hear
+ * about than a routine condition to swallow.
+ *
+ * Throws a plain `Error` rather than `OAuthFlowError`: revocation
+ * is best-effort cleanup invoked from `axe-auth logout`, and the
+ * caller already handles failure by warning + continuing with the
+ * local clear. Adding a dedicated `OAuthFlowError` code for this
+ * one shallow operation is more bloat than the discrimination is
+ * worth.
+ */
+async function revokeRefreshToken(options) {
+    const body = new URLSearchParams({
+        token: options.refreshToken,
+        token_type_hint: "refresh_token",
+        client_id: options.clientId,
+    });
+    let response;
+    try {
+        response = await fetch(options.revocationEndpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                "User-Agent": userAgent_1.USER_AGENT,
+            },
+            body,
+            signal: options.signal,
+        });
+    }
+    catch (cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new Error(`Could not reach the revocation endpoint at ${options.revocationEndpoint}: ${reason}`, { cause });
+    }
+    if (!response.ok) {
+        // Deliberately do NOT include the response body. The request
+        // body we POSTed contains the refresh token; some Keycloak
+        // custom error templates and many WAFs / reverse proxies echo
+        // request fields back into 4xx pages, which would land the
+        // refresh token on stderr (the caller's `describeError(err)`
+        // path is `axe-auth: server-side revocation failed (...)`). Status
+        // alone is enough for the user to act on; if more detail is
+        // needed they can hit the revocation endpoint directly.
+        //
+        // We also drain the body so the underlying connection isn't
+        // held open by the unread stream.
+        try {
+            await response.text();
+        }
+        catch {
+            // ignore — body is purely diagnostic
+        }
+        throw new Error(`Revocation endpoint at ${options.revocationEndpoint} returned HTTP ${response.status}`);
+    }
+}

package/dist/oauth/tokenExchange.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.exchangeCodeForTokens = exchangeCodeForTokens;
 const errors_1 = require("./errors");
 const tokenResponse_1 = require("./tokenResponse");
+const userAgent_1 = require("../userAgent");
 /**
  * Exchanges an authorization code for a `TokenSet` via the
  * authorization server's token endpoint (RFC 6749 §4.1.3 + RFC 7636
@@ -27,6 +28,7 @@ async function exchangeCodeForTokens(options) {
             headers: {
                 "Content-Type": "application/x-www-form-urlencoded",
                 Accept: "application/json",
+                "User-Agent": userAgent_1.USER_AGENT,
             },
             body,
             signal: options.signal,

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,10 +1,43 @@
+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
  * a `version-mismatch` result.
  */
 export declare const STORED_BLOB_VERSION = 1;
+/**
+ * What `KeyringTokenStore` persists: the OAuth tokens plus the
+ * issuer/client coordinates they were minted against. Carrying the
+ * coordinates inside the entry means a verb can recover its full
+ * config from the keychain alone, with no separate "default issuer"
+ * pointer.
+ */
+export interface StoredEntry {
+    tokens: TokenSet;
+    /** OIDC issuer URL the tokens were minted against. */
+    issuerURL: string;
+    /** OAuth client ID used at login. */
+    clientId: string;
+    /** Whether the original login allowed a non-loopback http issuer. */
+    allowInsecureIssuer: boolean;
+    /**
+     * Originating axe server (walnut) URL the user supplied (or the
+     * SaaS prod default) at login.
+     */
+    walnutURL: string;
+}
 /**
  * Outcome of a `TokenStore.load()` call.
  *
@@ -19,7 +52,7 @@ export declare const STORED_BLOB_VERSION = 1;
  */
 export type LoadResult = {
     ok: true;
-    tokens: TokenSet;
+    entry: StoredEntry;
 } | {
     ok: false;
     reason: "empty";
@@ -31,48 +64,108 @@ export type LoadResult = {
     reason: "version-mismatch";
     storedVersion: number;
 };
-/** Persistence layer for an OAuth `TokenSet`. */
+/** Persistence layer for an OAuth `StoredEntry`. */
 export interface TokenStore {
-    /** Write-through save. Replaces any previously stored tokens. */
-    save(tokens: TokenSet): Promise<void>;
+    /** Write-through save. Replaces any previously stored entry. */
+    save(entry: StoredEntry): Promise<void>;
     /**
-     * Reads the stored tokens and returns a structured result.
+     * Reads the stored entry and returns a structured result.
      *
      * Callers should branch on `result.ok` first. When `ok` is `false`,
-     * `reason` tells them *why* there is no usable `TokenSet`: `empty`
+     * `reason` tells them *why* there is no usable entry: `empty`
      * (nothing stored), `corrupt` (unparseable or shape-invalid), or
      * `version-mismatch` (stored under a schema we cannot migrate from).
      * The library does not emit output on these cases — surfacing them
      * to the user is the caller's responsibility.
      */
     load(): Promise<LoadResult>;
-    /** Removes any stored tokens. No-op if none are present. */
+    /** Removes any stored entry. No-op if none is present. */
     clear(): Promise<void>;
 }
-/** Minimal keyring-entry surface consumed by `KeyringTokenStore`. */
-export interface KeyringEntry {
-    /** Writes the password for this entry. */
-    setPassword(password: string): void;
-    /** Reads the current password, or returns `null` if none is set. */
-    getPassword(): string | null;
-    /** Deletes the password and returns `true` if one existed. */
-    deletePassword(): boolean;
-}
 /**
- * Factory for `KeyringEntry` values. Injection seam for tests;
- * production callers use the default that constructs
- * `@napi-rs/keyring` entries lazily.
+ * Outcome of `parseAndMigrateBlob`: same set of failure reasons as
+ * `LoadResult`, but on success carries the post-migration blob as an
+ * unknown payload. The caller is responsible for shape-validating
+ * that payload against the latest schema.
  */
-export type KeyringEntryFactory = (service: string, account: string) => KeyringEntry;
+export type BlobChainResult = {
+    ok: true;
+    blob: unknown;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "corrupt";
+} | {
+    ok: false;
+    reason: "version-mismatch";
+    storedVersion: number;
+};
+/**
+ * JSON-parses the raw keychain password and walks the migrator chain
+ * until it reaches `expectedVersion`. Exported with `expectedVersion`
+ * and `migrators` parameters only for testing the chain mechanics
+ * against synthetic versions / migrators; production callers use
+ * `KeyringTokenStore.load()`, which feeds in `STORED_BLOB_VERSION`
+ * 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
+ * Linux-only advice. Exported (but not re-exported from the package
+ * index) so tests can exercise each branch without mocking
+ * `process.platform`.
+ */
+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). Account is keyed by the normalized issuer URL.
+ * 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;
-    constructor(issuerURL: string, entryFactory?: KeyringEntryFactory);
-    save(tokens: TokenSet): Promise<void>;
+    /**
+     * @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[];