@deque/axe-auth 1.1.0-next.6ad261c8 → 1.1.0-next.907ffbd7

package/dist/oauth/index.js

@@ -1,7 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OAuthCallbackError = exports.startCallbackServer = void 0;
+exports.discoverOIDC = exports.STORED_BLOB_VERSION = exports.KeyringTokenStore = exports.authorize = exports.OAuthFlowError = exports.OAuthCallbackError = exports.startCallbackServer = void 0;
 var callbackServer_1 = require("./callbackServer");
 Object.defineProperty(exports, "startCallbackServer", { enumerable: true, get: function () { return callbackServer_1.startCallbackServer; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "OAuthCallbackError", { enumerable: true, get: function () { return errors_1.OAuthCallbackError; } });
+Object.defineProperty(exports, "OAuthFlowError", { enumerable: true, get: function () { return errors_1.OAuthFlowError; } });
+var authorize_1 = require("./authorize");
+Object.defineProperty(exports, "authorize", { enumerable: true, get: function () { return authorize_1.authorize; } });
+var tokenStore_1 = require("./tokenStore");
+Object.defineProperty(exports, "KeyringTokenStore", { enumerable: true, get: function () { return tokenStore_1.KeyringTokenStore; } });
+Object.defineProperty(exports, "STORED_BLOB_VERSION", { enumerable: true, get: function () { return tokenStore_1.STORED_BLOB_VERSION; } });
+var discoverOIDC_1 = require("./discoverOIDC");
+Object.defineProperty(exports, "discoverOIDC", { enumerable: true, get: function () { return discoverOIDC_1.discoverOIDC; } });

package/dist/oauth/issuerURL.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Canonicalizes an OIDC issuer URL for equivalence comparison. Two URLs
+ * that normalize to the same string refer to the same issuer, which is
+ * what `discoverOIDC` uses to build discovery URLs and what
+ * `KeyringTokenStore` uses to key keychain entries.
+ *
+ * Rules (per RFC 3986 §6.2 URI comparison):
+ * - Trailing slashes stripped from the path.
+ * - Scheme and authority (host + optional port) lowercased — both are
+ *   case-insensitive per the RFC.
+ * - Default ports (80 for http, 443 for https) collapsed via `URL.host`.
+ * - Path preserved case-sensitively.
+ * - Query string and fragment dropped: OIDC issuers are defined by
+ *   scheme + authority + path, and carrying them through would break
+ *   downstream path concatenation (e.g. appending
+ *   `/.well-known/openid-configuration`).
+ *
+ * If the input is not a parseable URL, the function trims trailing
+ * slashes and returns — discovery will surface a clearer error than
+ * this function could.
+ */
+export declare function normalizeIssuerURL(url: string): string;

package/dist/oauth/issuerURL.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeIssuerURL = normalizeIssuerURL;
+/**
+ * Canonicalizes an OIDC issuer URL for equivalence comparison. Two URLs
+ * that normalize to the same string refer to the same issuer, which is
+ * what `discoverOIDC` uses to build discovery URLs and what
+ * `KeyringTokenStore` uses to key keychain entries.
+ *
+ * Rules (per RFC 3986 §6.2 URI comparison):
+ * - Trailing slashes stripped from the path.
+ * - Scheme and authority (host + optional port) lowercased — both are
+ *   case-insensitive per the RFC.
+ * - Default ports (80 for http, 443 for https) collapsed via `URL.host`.
+ * - Path preserved case-sensitively.
+ * - Query string and fragment dropped: OIDC issuers are defined by
+ *   scheme + authority + path, and carrying them through would break
+ *   downstream path concatenation (e.g. appending
+ *   `/.well-known/openid-configuration`).
+ *
+ * If the input is not a parseable URL, the function trims trailing
+ * slashes and returns — discovery will surface a clearer error than
+ * this function could.
+ */
+function normalizeIssuerURL(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return url.replace(/\/+$/, "");
+    }
+    // `URL.protocol` is already lowercased by the URL parser.
+    // `URL.host` retains input casing, so lowercase it explicitly.
+    const host = parsed.host.toLowerCase();
+    const pathname = parsed.pathname.replace(/\/+$/, "");
+    return `${parsed.protocol}//${host}${pathname}`;
+}

package/dist/oauth/openBrowser.d.ts

@@ -0,0 +1,19 @@
+import type { ChildProcess, SpawnOptions } from "node:child_process";
+/** Injection seam for `child_process.spawn`. Used by tests. */
+export type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+/** Options for `openBrowser`. */
+export interface OpenBrowserOptions {
+    /** Override for `process.platform`. Used by tests. */
+    platform?: NodeJS.Platform;
+    /** Override for `child_process.spawn`. Used by tests. */
+    spawnFn?: SpawnFn;
+}
+/**
+ * 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.
+ *
+ * @param url Absolute URL to open.
+ * @param options Platform/spawn overrides; only exposed for tests.
+ */
+export declare function openBrowser(url: string, options?: OpenBrowserOptions): void;

package/dist/oauth/openBrowser.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openBrowser = openBrowser;
+const node_child_process_1 = require("node:child_process");
+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
+// title — without it `start` treats the URL as the title.
+//
+// The escape class covers:
+// - `& | ^ < >` — cmd metacharacters that would otherwise split the
+//   command line.
+// - `"` — would prematurely terminate the argument and break
+//   `start`'s quoting.
+// - `%` — triggers cmd.exe environment-variable expansion (e.g.
+//   `%USERNAME%`), which could leak or alter the URL.
+// - `\r \n` — embedded newlines let a crafted URL inject additional
+//   commands onto cmd.exe's line.
+//
+// URLs normally percent-encode most of these (so this is defense in
+// depth), but we do not fully trust the authorization endpoint that
+// came back from discovery.
+function windowsCommand(url) {
+    return {
+        command: "cmd.exe",
+        args: ["/c", "start", '""', url.replace(/[&|^<>"%\r\n]/g, (c) => `^${c}`)],
+    };
+}
+function browserCommand(platform, url) {
+    switch (platform) {
+        case "darwin":
+            return { command: "open", args: [url] };
+        case "win32":
+            return windowsCommand(url);
+        default:
+            // linux / freebsd / openbsd — xdg-open is part of xdg-utils which
+            // is near-universal on desktop Linux. Environments without it
+            // (headless servers, containers) will report the missing binary
+            // via an asynchronous child-process `error` event, which this
+            // module deliberately swallows (see `child.once("error", ...)`
+            // below); `BROWSER_LAUNCH_FAILED` is only raised for synchronous
+            // `spawn()` throws. The caller's fallback is the URL already
+            // surfaced via `onAuthorizationUrl` so the user can finish the
+            // flow manually.
+            return { command: "xdg-open", args: [url] };
+    }
+}
+/**
+ * Launches the system browser at `url` in a detached child process.
+ * Returns synchronously once the child is spawned — completion of the
+ * browser load is intentionally not awaited.
+ *
+ * @param url Absolute URL to open.
+ * @param options Platform/spawn 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);
+    let child;
+    try {
+        child = spawnFn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("BROWSER_LAUNCH_FAILED", `Failed to launch the system browser (${command}). Open this URL manually:\n${url}`, { cause });
+    }
+    // `spawn` itself can succeed (the parent fork was fine) and then emit
+    // `error` asynchronously if the binary isn't on PATH. We can't surface
+    // that synchronously, but attaching a handler prevents the default
+    // "unhandled error" crash. Callers get a benign no-op if the browser
+    // never opens; the authorize() orchestrator prints the URL alongside
+    // the launch so the user has a fallback.
+    child.once("error", () => { });
+    child.unref();
+}

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generates a cryptographically random PKCE `code_verifier` per RFC 7636
+ * §4.1. 43 base64url characters, 256 bits of entropy.
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Derives the PKCE S256 `code_challenge` for the given verifier per
+ * RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(verifier)))`.
+ *
+ * @param verifier The PKCE verifier produced by `generateCodeVerifier`.
+ */
+export declare function deriveCodeChallenge(verifier: string): string;
+/**
+ * Generates a cryptographically random OAuth `state` value for CSRF
+ * protection. 22 base64url characters, 128 bits of entropy.
+ */
+export declare function generateState(): string;

package/dist/oauth/pkce.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateCodeVerifier = generateCodeVerifier;
+exports.deriveCodeChallenge = deriveCodeChallenge;
+exports.generateState = generateState;
+const node_crypto_1 = require("node:crypto");
+// PKCE per RFC 7636. We only ever emit S256; plain is permitted by the RFC
+// but explicitly disallowed by our authorization-server config so it can't
+// silently fall back in the face of a buggy server.
+/**
+ * Entropy for the PKCE `code_verifier`. 32 bytes yields 43 base64url chars
+ * (no padding), the minimum length RFC 7636 allows (43–128). 256 bits
+ * matches the S256 hash's security ceiling.
+ */
+const VERIFIER_ENTROPY_BYTES = 32;
+/**
+ * Entropy for the CSRF `state` parameter. 16 bytes yields 22 base64url
+ * chars — unguessable without bloating the authorization URL.
+ */
+const STATE_ENTROPY_BYTES = 16;
+/**
+ * Generates a cryptographically random PKCE `code_verifier` per RFC 7636
+ * §4.1. 43 base64url characters, 256 bits of entropy.
+ */
+function generateCodeVerifier() {
+    return (0, node_crypto_1.randomBytes)(VERIFIER_ENTROPY_BYTES).toString("base64url");
+}
+/**
+ * Derives the PKCE S256 `code_challenge` for the given verifier per
+ * RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(verifier)))`.
+ *
+ * @param verifier The PKCE verifier produced by `generateCodeVerifier`.
+ */
+function deriveCodeChallenge(verifier) {
+    return (0, node_crypto_1.createHash)("sha256").update(verifier, "ascii").digest("base64url");
+}
+/**
+ * Generates a cryptographically random OAuth `state` value for CSRF
+ * protection. 22 base64url characters, 128 bits of entropy.
+ */
+function generateState() {
+    return (0, node_crypto_1.randomBytes)(STATE_ENTROPY_BYTES).toString("base64url");
+}

package/dist/oauth/tokenExchange.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tokens returned by a successful authorization-code exchange.
+ *
+ * `refreshToken` is optional because not all flows return one —
+ * callers that did not request `offline_access` (or the provider
+ * equivalent) will receive only an access token. Refresh logic (issue
+ * #422) must handle this case.
+ *
+ * `grantedScope` reflects the authorization server's `scope` response
+ * field when present (RFC 6749 §5.1 says `scope` is required when the
+ * granted set differs from the requested set; optional otherwise).
+ * Callers comparing granted vs requested to surface diagnostics should
+ * read this field.
+ */
+export interface TokenSet {
+    /** Access token for authenticated API calls. */
+    accessToken: string;
+    /** Long-lived token used to mint new access tokens without re-auth. Absent if the flow did not request it. */
+    refreshToken?: string;
+    /** Absolute timestamp (ms since epoch) when the access token expires. */
+    expiresAt: number;
+    /** Space-delimited scopes the server actually granted, if reported. */
+    grantedScope?: string;
+}
+/** Options for `exchangeCodeForTokens`. */
+export interface ExchangeCodeForTokensOptions {
+    /** Token endpoint resolved from OIDC discovery. */
+    tokenEndpoint: string;
+    /** OAuth client identifier. */
+    clientId: string;
+    /** Authorization code received via the loopback callback. */
+    code: string;
+    /** PKCE verifier paired with the `code_challenge` sent at auth time. */
+    codeVerifier: string;
+    /** Redirect URI originally sent to the authorization endpoint. */
+    redirectUri: string;
+    /** Source of `now`. Injected for test determinism; defaults to `Date.now`. */
+    now?: () => number;
+    /** Aborts the underlying fetch when fired. */
+    signal?: AbortSignal;
+}
+/**
+ * Exchanges an authorization code for a `TokenSet` via the
+ * authorization server's token endpoint (RFC 6749 §4.1.3 + RFC 7636
+ * §4.5). Rejects with `OAuthFlowError("TOKEN_EXCHANGE_FAILED", ...)`
+ * for any failure mode, surfacing the OAuth `error` /
+ * `error_description` when available.
+ */
+export declare function exchangeCodeForTokens(options: ExchangeCodeForTokensOptions): Promise<TokenSet>;

package/dist/oauth/tokenExchange.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exchangeCodeForTokens = exchangeCodeForTokens;
+const errors_1 = require("./errors");
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}
+// 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.
+function parseExpiresIn(v) {
+    if (typeof v === "number" && Number.isFinite(v) && v > 0)
+        return v;
+    if (typeof v === "string") {
+        const n = Number(v);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return null;
+}
+function parseErrorBody(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return {};
+    const raw = parsed;
+    return {
+        error: isNonEmptyString(raw.error) ? raw.error : undefined,
+        description: isNonEmptyString(raw.error_description)
+            ? raw.error_description
+            : undefined,
+    };
+}
+function throwFromErrorResponse(status, body) {
+    const { error, description } = parseErrorBody(body);
+    const suffix = error
+        ? description
+            ? `: ${error}: ${description}`
+            : `: ${error}`
+        : "";
+    const details = {};
+    if (error)
+        details.error = error;
+    if (description)
+        details.error_description = description;
+    throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token exchange failed with HTTP ${status}${suffix}`, Object.keys(details).length > 0 ? { details } : undefined);
+}
+/**
+ * Exchanges an authorization code for a `TokenSet` via the
+ * authorization server's token endpoint (RFC 6749 §4.1.3 + RFC 7636
+ * §4.5). Rejects with `OAuthFlowError("TOKEN_EXCHANGE_FAILED", ...)`
+ * for any failure mode, surfacing the OAuth `error` /
+ * `error_description` when available.
+ */
+async function exchangeCodeForTokens(options) {
+    const now = options.now ?? Date.now;
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: options.clientId,
+        code: options.code,
+        code_verifier: options.codeVerifier,
+        redirect_uri: options.redirectUri,
+    });
+    // Capture `issuedAt` before the network call so we don't drift past
+    // expiry just because the network was slow. 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." That's the safer direction for any consumer doing
+    // pre-expiry checks.
+    const issuedAt = now();
+    let response;
+    try {
+        response = await fetch(options.tokenEndpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body,
+            signal: options.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Could not reach the token endpoint at ${options.tokenEndpoint}. Check your network connection.`, { cause });
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throwFromErrorResponse(response.status, text);
+    }
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${options.tokenEndpoint} returned a non-JSON response`, { cause });
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${options.tokenEndpoint} returned a non-object response`);
+    }
+    const raw = parsed;
+    if (!isNonEmptyString(raw.access_token)) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing 'access_token'`);
+    }
+    const expiresIn = parseExpiresIn(raw.expires_in);
+    if (expiresIn === null) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing or has invalid 'expires_in'`);
+    }
+    // RFC 6749 §5.1: token_type is REQUIRED. We only speak Bearer;
+    // DPoP / MAC / other proof-of-possession types need request-side
+    // support we don't implement, and silently treating them as Bearer
+    // would send tokens in the wrong header with unclear semantics.
+    if (!isNonEmptyString(raw.token_type)) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing required 'token_type'`);
+    }
+    if (raw.token_type.toLowerCase() !== "bearer") {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Unsupported token_type '${raw.token_type}'; this library only handles Bearer.`);
+    }
+    const tokens = {
+        accessToken: raw.access_token,
+        expiresAt: issuedAt + expiresIn * 1000,
+    };
+    if (isNonEmptyString(raw.refresh_token)) {
+        tokens.refreshToken = raw.refresh_token;
+    }
+    if (isNonEmptyString(raw.scope)) {
+        tokens.grantedScope = raw.scope;
+    }
+    return tokens;
+}

package/dist/oauth/tokenStore.d.ts

@@ -0,0 +1,78 @@
+import type { TokenSet } from "./tokenExchange";
+/**
+ * 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;
+/**
+ * Outcome of a `TokenStore.load()` call.
+ *
+ * Note on downgrades: the migrator chain only walks *forward*. A user
+ * who downgrades `axe-auth` to a release that predates a schema bump
+ * will see `version-mismatch` on any blob written by the newer
+ * release, even if the change was strictly additive. That is the safe
+ * default for a credentials blob — the older version cannot vouch for
+ * the meaning of fields it has never seen. Callers hitting this case
+ * should treat it as "re-authenticate" rather than attempting to
+ * parse an unknown future shape.
+ */
+export type LoadResult = {
+    ok: true;
+    tokens: TokenSet;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "corrupt";
+} | {
+    ok: false;
+    reason: "version-mismatch";
+    storedVersion: number;
+};
+/** Persistence layer for an OAuth `TokenSet`. */
+export interface TokenStore {
+    /** Write-through save. Replaces any previously stored tokens. */
+    save(tokens: TokenSet): Promise<void>;
+    /**
+     * Reads the stored tokens 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`
+     * (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. */
+    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.
+ */
+export type KeyringEntryFactory = (service: string, account: string) => KeyringEntry;
+/**
+ * `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.
+ */
+export declare class KeyringTokenStore implements TokenStore {
+    #private;
+    constructor(issuerURL: string, entryFactory?: KeyringEntryFactory);
+    save(tokens: TokenSet): Promise<void>;
+    load(): Promise<LoadResult>;
+    clear(): Promise<void>;
+}