@deque/axe-auth 1.1.0-next.6ad261c8 → 1.1.0-next.759bd5c5

package/dist/index.js

@@ -1,47 +1,167 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const node_util_1 = require("node:util");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const ts_dedent_1 = require("ts-dedent");
+const commonArgs_1 = require("./cli/commonArgs");
+const tokenStore_1 = require("./oauth/tokenStore");
+const login_1 = __importDefault(require("./commands/login"));
+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"));
-const helpText = `${pkg.name} v${pkg.version}
+// Iteration order is the order verbs appear in `axe-auth --help`.
+const COMMANDS = [
+    login_1.default,
+    logout_1.default,
+    token_1.default,
+];
+function findCommand(verb) {
+    return COMMANDS.find((c) => c.name === verb);
+}
+function topLevelHelp() {
+    const width = Math.max(...COMMANDS.map((c) => c.name.length));
+    const verbList = COMMANDS.map((c) => `  ${c.name.padEnd(width)}  ${c.summary}`).join("\n");
+    return `${pkg.name} v${pkg.version}
 
 ${pkg.description}
 
 Usage:
-  axe-auth [options]
+  axe-auth <command> [options]
+
+Commands:
+${verbList}
+
+Run \`axe-auth <command> --help\` for command-specific options.
 
-Options:
-  -v, --version  Show version number
-  -h, --help     Show this help message`;
-const main = async () => {
-    let values;
+Top-level options:
+  -v, --version  Show version number.
+  -h, --help     Show this help.`;
+}
+async function dispatch(argv) {
+    const [first, ...rest] = argv;
+    if (first === undefined || first === "-h" || first === "--help") {
+        process.stdout.write(`${topLevelHelp()}\n`);
+        return 0;
+    }
+    if (first === "-v" || first === "--version") {
+        process.stdout.write(`${pkg.version}\n`);
+        return 0;
+    }
+    if (first.startsWith("-")) {
+        process.stderr.write(`Unknown option: ${first}. Run \`axe-auth --help\` for usage.\n`);
+        return 2;
+    }
+    const command = findCommand(first);
+    if (!command) {
+        process.stderr.write(`Unknown command: ${first}. Run \`axe-auth --help\` for usage.\n`);
+        return 2;
+    }
+    let parsed;
     try {
-        ({ values } = (0, node_util_1.parseArgs)({
+        parsed = (0, node_util_1.parseArgs)({
+            args: rest,
             options: {
-                version: { type: "boolean", short: "v" },
+                ...commonArgs_1.COMMON_OPTIONS,
+                ...command.options,
                 help: { type: "boolean", short: "h" },
             },
             strict: true,
-        }));
+            allowPositionals: false,
+        });
     }
     catch (err) {
-        console.error(err.message);
-        return 1;
+        process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        return 2;
     }
-    if (values.version) {
-        console.log(pkg.version);
+    if (parsed.values.help) {
+        process.stdout.write(`${command.helpText}\n`);
         return 0;
     }
-    if (values.help) {
-        console.log(helpText);
+    // Best-effort load of the stored config — but only when at least
+    // one common field is unspecified. The dispatcher's fallback is
+    // all-or-nothing (parseCommonArgs ignores defaults if any flag/env
+    // is set), so a fully-flagged invocation gains nothing from a
+    // keychain hit on the hot path.
+    //
+    // The load failure isn't fatal on its own — if the user passed
+    // flags/env, the stored config doesn't matter — but if
+    // `parseCommonArgs` then throws `MissingConfigError`, we surface
+    // this failure alongside it so the user understands the keychain
+    // (not just missing flags) is the proximate cause.
+    let defaults = null;
+    let defaultLoadError = null;
+    let loadedEntry;
+    const commonValues = parsed.values;
+    const allFlagsPresent = Boolean(commonValues.server && commonValues.realm && commonValues["client-id"]);
+    if (!allFlagsPresent) {
+        try {
+            loadedEntry = await new tokenStore_1.KeyringTokenStore().load();
+            if (loadedEntry.ok) {
+                defaults = {
+                    issuerURL: loadedEntry.entry.issuerURL,
+                    clientId: loadedEntry.entry.clientId,
+                    allowInsecureIssuer: loadedEntry.entry.allowInsecureIssuer,
+                };
+            }
+        }
+        catch (err) {
+            defaultLoadError = err;
+        }
+    }
+    let common;
+    try {
+        common = (0, commonArgs_1.parseCommonArgs)(commonValues, process.env, defaults);
+    }
+    catch (err) {
+        if (err instanceof errors_1.MissingConfigError && !command.requiresConfig) {
+            // The verb operates on the stored entry alone (token,
+            // logout). It has its own handling for the empty / corrupt /
+            // version-mismatch cases, which is friendlier than the
+            // generic "missing required configuration" error
+            // (`No stored credentials. Run \`axe-auth login\` first.` for
+            // token; `Already logged out.` for logout). Pass a
+            // sentinel-empty CommonArgs so the verb runs and decides.
+            common = { issuerURL: "", clientId: "", allowInsecureIssuer: false };
+        }
+        else if (err instanceof errors_1.MissingConfigError && defaultLoadError !== null) {
+            process.stderr.write((0, ts_dedent_1.dedent) `
+        ${err.message}
+        Could not read the stored credentials from the keychain (${(0, errors_1.describeError)(defaultLoadError)});
+        pass the flags explicitly or fix the keychain.
+      ` + "\n");
+            return 2;
+        }
+        else {
+            process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+            return 2;
+        }
+    }
+    const deps = {
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        loadedEntry,
+    };
+    try {
+        await command.run({ ...common, ...parsed.values }, deps);
         return 0;
     }
-    console.log("No arguments provided. Use --help for usage information.");
-    return 1;
-};
-main().then((code) => process.exit(code), (err) => {
-    console.error(err);
+    catch (err) {
+        if (err instanceof errors_1.CLIError) {
+            process.stderr.write(`${err.message}\n`);
+            return err.exitCode;
+        }
+        process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        return 2;
+    }
+}
+dispatch(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
     process.exit(1);
 });

package/dist/oauth/authorizationURL.d.ts

@@ -0,0 +1,29 @@
+/** Options for `buildAuthorizationURL`. */
+export interface BuildAuthorizationURLOptions {
+    /** Authorization endpoint resolved from OIDC discovery. */
+    authorizationEndpoint: string;
+    /** OAuth client identifier registered with the authorization server. */
+    clientId: string;
+    /** Loopback redirect URI the callback server is listening on. */
+    redirectUri: string;
+    /** PKCE `code_challenge` derived via S256. */
+    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.
+     */
+    scopes: readonly string[];
+}
+/**
+ * Builds the OAuth authorization URL (RFC 6749 §4.1.1 + RFC 7636 §4.3)
+ * that the user's browser is sent to. Non-OAuth params already present
+ * on the authorization endpoint (e.g. Keycloak's `kc_idp_hint`) pass
+ * through unchanged. Throws if the endpoint already carries any of the
+ * OAuth-required params — that collision is a server misconfiguration
+ * we refuse to paper over.
+ */
+export declare function buildAuthorizationURL(options: BuildAuthorizationURLOptions): string;

package/dist/oauth/authorizationURL.js

@@ -0,0 +1,52 @@
+"use strict";
+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.
+const OAUTH_REQUIRED_PARAMS = [
+    "response_type",
+    "client_id",
+    "redirect_uri",
+    "code_challenge",
+    "code_challenge_method",
+    "state",
+    "scope",
+];
+/**
+ * Builds the OAuth authorization URL (RFC 6749 §4.1.1 + RFC 7636 §4.3)
+ * that the user's browser is sent to. Non-OAuth params already present
+ * on the authorization endpoint (e.g. Keycloak's `kc_idp_hint`) pass
+ * through unchanged. Throws if the endpoint already carries any of the
+ * OAuth-required params — that collision is a server misconfiguration
+ * we refuse to paper over.
+ */
+function buildAuthorizationURL(options) {
+    const url = new URL(options.authorizationEndpoint);
+    const collisions = [];
+    for (const name of OAUTH_REQUIRED_PARAMS) {
+        if (url.searchParams.has(name))
+            collisions.push(name);
+    }
+    if (collisions.length > 0) {
+        throw new errors_1.OAuthFlowError("INVALID_AUTHORIZATION_ENDPOINT", `Authorization endpoint ${options.authorizationEndpoint} already carries OAuth-required param(s) ${collisions.join(", ")}; refusing to ship a URL the server may disambiguate unpredictably.`, { details: { params: collisions.join(",") } });
+    }
+    // `set` each required OAuth param. Non-OAuth params the discovery
+    // endpoint already carries (e.g. Keycloak's `kc_idp_hint=github`)
+    // ride through untouched since we never reference those names. The
+    // collision check above has already proved none of the OAuth names
+    // exist on the URL, so `set` and `append` are equivalent here —
+    // `set` just reads more conventionally.
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", options.clientId);
+    url.searchParams.set("redirect_uri", options.redirectUri);
+    url.searchParams.set("code_challenge", options.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("state", options.state);
+    url.searchParams.set("scope", options.scopes.join(" "));
+    return url.toString();
+}

package/dist/oauth/authorize.d.ts

@@ -0,0 +1,84 @@
+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.
+     */
+    issuerURL: string;
+    /** OAuth client ID registered with the authorization server. */
+    clientId: 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.
+     */
+    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).
+     */
+    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.
+     */
+    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).
+     */
+    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`.
+     */
+    allowInsecureIssuer?: boolean;
+}
+/**
+ * Runs the full OAuth 2.0 Authorization Code + PKCE flow (RFC 6749 +
+ * RFC 7636): discovery, PKCE + state generation, loopback callback
+ * server, browser launch, code → token exchange, and keychain
+ * persistence.
+ *
+ * Note on identity: this library uses the OIDC discovery well-known
+ * path as a convention (most OAuth 2.0 providers expose it) but does
+ * *not* perform OIDC-strength identity validation — no id_token
+ * parsing, nonce checks, or JWKS signature verification. Callers
+ * needing authenticated identity claims should layer that on top.
+ *
+ * @returns The `TokenSet` on success. Also persisted via `tokenStore`.
+ *   `refreshToken` will be absent if the requested scopes did not
+ *   include `offline_access` (or the provider's equivalent).
+ * @throws {OAuthFlowError} For discovery, token-exchange, or keychain failures.
+ * @throws {OAuthCallbackError} For loopback/callback-server failures.
+ */
+export declare function authorize(options: AuthorizeOptions): Promise<TokenSet>;

package/dist/oauth/authorize.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorize = authorize;
+const callbackServer_1 = require("./callbackServer");
+const discoverOIDC_1 = require("./discoverOIDC");
+const pkce_1 = require("./pkce");
+const authorizationURL_1 = require("./authorizationURL");
+const openBrowser_1 = require("./openBrowser");
+const tokenExchange_1 = require("./tokenExchange");
+const tokenStore_1 = require("./tokenStore");
+const errors_1 = require("./errors");
+function defaultOnAuthorizationUrl(url) {
+    if (process.stderr.isTTY) {
+        console.error(`Authorization URL: ${url}`);
+    }
+}
+function defaultOnWarning(message) {
+    if (process.stderr.isTTY) {
+        console.error(`axe-auth: ${message}`);
+    }
+}
+/**
+ * Runs the full OAuth 2.0 Authorization Code + PKCE flow (RFC 6749 +
+ * RFC 7636): discovery, PKCE + state generation, loopback callback
+ * server, browser launch, code → token exchange, and keychain
+ * persistence.
+ *
+ * Note on identity: this library uses the OIDC discovery well-known
+ * path as a convention (most OAuth 2.0 providers expose it) but does
+ * *not* perform OIDC-strength identity validation — no id_token
+ * parsing, nonce checks, or JWKS signature verification. Callers
+ * needing authenticated identity claims should layer that on top.
+ *
+ * @returns The `TokenSet` on success. Also persisted via `tokenStore`.
+ *   `refreshToken` will be absent if the requested scopes did not
+ *   include `offline_access` (or the provider's equivalent).
+ * @throws {OAuthFlowError} For discovery, token-exchange, or keychain failures.
+ * @throws {OAuthCallbackError} For loopback/callback-server failures.
+ */
+async function authorize(options) {
+    const { issuerURL, clientId, 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.
+    const config = await (0, discoverOIDC_1.discoverOIDC)(issuerURL, {
+        signal,
+        allowInsecureIssuer,
+    });
+    const codeVerifier = (0, pkce_1.generateCodeVerifier)();
+    const codeChallenge = (0, pkce_1.deriveCodeChallenge)(codeVerifier);
+    const state = (0, pkce_1.generateState)();
+    const callback = await (0, callbackServer_1.startCallbackServer)({
+        expectedState: state,
+        timeoutMs,
+        signal,
+    });
+    try {
+        const authURL = (0, authorizationURL_1.buildAuthorizationURL)({
+            authorizationEndpoint: config.authorizationEndpoint,
+            clientId,
+            redirectUri: callback.redirectUri,
+            codeChallenge,
+            state,
+            scopes,
+        });
+        // Surface before launch so the URL is always visible even if the
+        // browser spawn fails (or never does anything useful, e.g. on a
+        // headless box).
+        onAuthorizationUrl(authURL);
+        try {
+            openBrowser(authURL);
+        }
+        catch (err) {
+            // Only swallow the "could not launch browser" case: the URL was
+            // already surfaced via onAuthorizationUrl so the user can
+            // complete the flow manually. Any other error (a bug in an
+            // injected openBrowser, an unexpected throw) must propagate so
+            // callers and tests can see it.
+            if (err instanceof errors_1.OAuthFlowError &&
+                err.code === "BROWSER_LAUNCH_FAILED") {
+                onWarning(err.message);
+            }
+            else {
+                throw err;
+            }
+        }
+        const { code } = await callback.result;
+        const tokens = await (0, tokenExchange_1.exchangeCodeForTokens)({
+            tokenEndpoint: config.tokenEndpoint,
+            clientId,
+            code,
+            codeVerifier,
+            redirectUri: callback.redirectUri,
+            signal,
+        });
+        // If the caller requested offline_access but no refresh_token
+        // came back, warn. Prefer the server's reported `grantedScope`
+        // when present (RFC 6749 §5.1) since the provider's consent
+        // screen may have dropped the scope.
+        if (scopes.includes("offline_access") && !tokens.refreshToken) {
+            const grantedSuffix = tokens.grantedScope
+                ? ` (server granted: ${tokens.grantedScope})`
+                : "";
+            onWarning(`'offline_access' was requested but no refresh_token was returned${grantedSuffix}. Cross-session refresh will not be available.`);
+        }
+        await tokenStore.save({
+            tokens,
+            issuerURL,
+            clientId,
+            allowInsecureIssuer: allowInsecureIssuer ?? false,
+        });
+        return tokens;
+    }
+    finally {
+        await callback.close();
+    }
+}

package/dist/oauth/discoverOIDC.d.ts

@@ -0,0 +1,50 @@
+/** Subset of the OIDC discovery document that this package consumes. */
+export interface OIDCConfiguration {
+    /** Issuer identifier. Same value the authorization server will claim in tokens. */
+    issuer: string;
+    /** Endpoint the browser is redirected to for authorization. */
+    authorizationEndpoint: string;
+    /** Endpoint for code → token exchange and refresh-token grants. */
+    tokenEndpoint: string;
+    /** Present on most providers (Keycloak, Auth0); OIDC spec does not require it. */
+    revocationEndpoint?: string;
+    /** Present on providers that implement RP-initiated logout (OIDC session management). */
+    endSessionEndpoint?: string;
+}
+/** Options for `discoverOIDC`. */
+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`.
+     */
+    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.
+ *
+ * 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.
+ */
+export declare function discoverOIDC(issuerURL: string, options?: DiscoverOIDCOptions): Promise<OIDCConfiguration>;

package/dist/oauth/discoverOIDC.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverOIDC = discoverOIDC;
+const errors_1 = require("./errors");
+const issuerURL_1 = require("./issuerURL");
+const predicates_1 = require("./predicates");
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+function optionalString(v) {
+    return (0, predicates_1.isNonEmptyString)(v) ? v : undefined;
+}
+/**
+ * Throws `DISCOVERY_FAILED` if `url` is not safe to transmit OAuth
+ * secrets over. `https:` is always fine; `http:` is only fine for
+ * loopback hosts, or for any host when `allowInsecurePermitted` is
+ * `true`. `label` describes the URL being checked ("issuer URL",
+ * "token_endpoint", etc.) and appears in the error message.
+ */
+function assertSecureURL(url, label, allowInsecurePermitted) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `${label} is not a valid URL: ${url}`);
+    }
+    if (parsed.protocol === "https:")
+        return;
+    if (parsed.protocol === "http:") {
+        const host = parsed.host.toLowerCase();
+        // Keycloak on localhost:8080 → host === "localhost:8080"; strip
+        // the port for the loopback check.
+        const hostname = host.replace(/:\d+$/, "");
+        if (LOOPBACK_HOSTS.has(hostname))
+            return;
+        if (allowInsecurePermitted)
+            return;
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Refusing to use ${label} over http:// against non-loopback host ${parsed.host}. Use https:// or pass allowInsecureIssuer: true to override (only do this on trusted networks).`);
+    }
+    throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Unsupported ${label} scheme '${parsed.protocol}'; expected https: or http: (loopback only).`);
+}
+function buildDiscoveryURL(issuerURL) {
+    // Use URL parsing (rather than string concat) so the discovery path
+    // lands on the URL's pathname, not accidentally after a query string
+    // or fragment. `normalizeIssuerURL` already strips those, but
+    // defense in depth keeps the contract obvious from the code.
+    const normalized = new URL((0, issuerURL_1.normalizeIssuerURL)(issuerURL));
+    normalized.search = "";
+    normalized.hash = "";
+    normalized.pathname = `${normalized.pathname.replace(/\/$/, "")}/.well-known/openid-configuration`;
+    return normalized.toString();
+}
+function parseConfiguration(body, url) {
+    const missing = [];
+    if (!(0, predicates_1.isNonEmptyString)(body.issuer))
+        missing.push("issuer");
+    if (!(0, predicates_1.isNonEmptyString)(body.authorization_endpoint)) {
+        missing.push("authorization_endpoint");
+    }
+    if (!(0, predicates_1.isNonEmptyString)(body.token_endpoint))
+        missing.push("token_endpoint");
+    if (missing.length > 0) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${url} is missing required field(s): ${missing.join(", ")}`);
+    }
+    return {
+        issuer: body.issuer,
+        authorizationEndpoint: body.authorization_endpoint,
+        tokenEndpoint: body.token_endpoint,
+        revocationEndpoint: optionalString(body.revocation_endpoint),
+        endSessionEndpoint: optionalString(body.end_session_endpoint),
+    };
+}
+/**
+ * Fetches and parses the OpenID Connect discovery document for a given
+ * issuer. Fails fast (no retry) so the caller does not open a browser
+ * against an unreachable authorization server.
+ *
+ * This function uses the OIDC discovery well-known path as a
+ * convention — most OAuth 2.0 providers expose it regardless of
+ * whether you intend to perform identity validation. This library
+ * itself does not perform OIDC identity validation (no id_token /
+ * nonce / signature checks); callers needing OIDC-strength identity
+ * assurance should layer that on top.
+ *
+ * Verifies that the server's claimed `issuer` matches the URL the
+ * caller passed in, per OIDC Discovery §3 / defence against a hostile
+ * discovery response redirecting `authorization_endpoint` and
+ * `token_endpoint` to attacker-controlled hosts.
+ *
+ * @param issuerURL Authorization-server URL the discovery document
+ *   claims as its `issuer`. For Keycloak, callers build this as
+ *   `${serverURL}/realms/${realm}`. For other providers it is the
+ *   hostname (or issuer path) advertised in their discovery document.
+ *   Trailing slashes tolerated.
+ */
+async function discoverOIDC(issuerURL, options = {}) {
+    const allowInsecure = options.allowInsecureIssuer ?? false;
+    assertSecureURL(issuerURL, "issuer URL", allowInsecure);
+    const url = buildDiscoveryURL(issuerURL);
+    let response;
+    try {
+        response = await fetch(url, { signal: options.signal });
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Could not reach the authentication server at ${url}. Check the URL and your network connection.`, { cause });
+    }
+    if (!response.ok) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Authentication server at ${url} responded with HTTP ${response.status}. Check the issuer URL.`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Authentication server at ${url} did not return a valid JSON OpenID configuration`, { cause });
+    }
+    if (body === null || typeof body !== "object") {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${url} was not a JSON object`);
+    }
+    const config = parseConfiguration(body, url);
+    // OIDC Discovery §3: the `issuer` value returned MUST equal the URL
+    // the client used for discovery. Without this check (and without
+    // id_token signature validation, which this library does not do),
+    // a hostile discovery response could redirect the authorization and
+    // token endpoints to attacker hosts while still appearing to come
+    // from the legitimate origin.
+    if ((0, issuerURL_1.normalizeIssuerURL)(config.issuer) !== (0, issuerURL_1.normalizeIssuerURL)(issuerURL)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Issuer mismatch: requested ${issuerURL} but discovery document claims ${config.issuer}`);
+    }
+    // Enforce scheme on the endpoints the flow actually hits. A tampered
+    // discovery response could claim the legitimate issuer while
+    // returning http://... for authorization_endpoint or token_endpoint,
+    // which would leak the auth code + PKCE verifier to a cleartext
+    // path. Same loopback / allowInsecureIssuer policy as the input.
+    assertSecureURL(config.authorizationEndpoint, "authorization_endpoint", allowInsecure);
+    assertSecureURL(config.tokenEndpoint, "token_endpoint", allowInsecure);
+    if (config.revocationEndpoint) {
+        assertSecureURL(config.revocationEndpoint, "revocation_endpoint", allowInsecure);
+    }
+    if (config.endSessionEndpoint) {
+        assertSecureURL(config.endSessionEndpoint, "end_session_endpoint", allowInsecure);
+    }
+    return config;
+}