@deque/axe-auth 1.1.0-next.97bcb8e6 → 1.1.0-next.9bc60204

package/dist/oauth/callbackServer.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startCallbackServer = exports.bindLoopback = void 0;
+const node_events_1 = require("node:events");
+const node_http_1 = require("node:http");
+const errors_1 = require("./errors");
+const renderHtml_1 = require("./renderHtml");
+const DEFAULT_TIMEOUT_MS = 120_000;
+const LOOPBACK_ADDRESSES = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+const isLoopback = (addr) => !!addr && LOOPBACK_ADDRESSES.has(addr);
+// Errors from bind(2) that mean "this address family isn't configured on this
+// host" — the signal to fall back to the other loopback family rather than
+// fail the caller.
+const FAMILY_UNAVAILABLE = new Set(["EAFNOSUPPORT", "EADDRNOTAVAIL"]);
+const listen = async (handler, host) => {
+    const server = (0, node_http_1.createServer)(handler);
+    server.listen(0, host);
+    // events.once rejects if the emitter fires 'error' before 'listening'.
+    await (0, node_events_1.once)(server, "listening");
+    return server;
+};
+// RFC 8252 §7.3: "use whichever is available". Prefer IPv4; fall back to
+// IPv6 only when the IPv4 loopback isn't configured on this host. `listenFn`
+// is an injection seam for tests — production callers use the default.
+const bindLoopback = async (handler, listenFn = listen) => {
+    try {
+        return {
+            server: await listenFn(handler, "127.0.0.1"),
+            host: "127.0.0.1",
+        };
+    }
+    catch (err) {
+        const code = err.code;
+        if (!code || !FAMILY_UNAVAILABLE.has(code)) {
+            throw new errors_1.OAuthCallbackError("BIND_FAILED", `Failed to bind loopback server on 127.0.0.1: ${err.message}`, { cause: err });
+        }
+        try {
+            return {
+                server: await listenFn(handler, "::1"),
+                host: "::1",
+            };
+        }
+        catch (ipv6Err) {
+            throw new errors_1.OAuthCallbackError("BIND_FAILED", `Failed to bind loopback server on 127.0.0.1 (${code}) and [::1]: ${ipv6Err.message}`, { cause: ipv6Err });
+        }
+    }
+};
+exports.bindLoopback = bindLoopback;
+const closeServer = async (server) => {
+    if (!server.listening)
+        return;
+    server.close();
+    server.closeAllConnections?.();
+    await (0, node_events_1.once)(server, "close");
+};
+const writeHtml = (res, status, html) => {
+    res.writeHead(status, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Content-Security-Policy": renderHtml_1.CSP_HEADER,
+        "X-Content-Type-Options": "nosniff",
+    });
+    res.end(html);
+};
+const writeText = (res, status, body, extraHeaders = {}) => {
+    res.writeHead(status, {
+        "Content-Type": "text/plain; charset=utf-8",
+        "X-Content-Type-Options": "nosniff",
+        ...extraHeaders,
+    });
+    res.end(body + "\n");
+};
+const startCallbackServer = async (opts) => {
+    const { expectedState, timeoutMs = DEFAULT_TIMEOUT_MS, signal } = opts;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new TypeError(`timeoutMs must be a positive finite number (received ${timeoutMs}).`);
+    }
+    let resolveResult;
+    let rejectResult;
+    const result = new Promise((resolve, reject) => {
+        resolveResult = resolve;
+        rejectResult = reject;
+    });
+    // Avoid unhandled rejection warnings if the caller defers attaching a
+    // .catch() until after the timer fires.
+    result.catch(() => { });
+    let consumed = false;
+    let closed = false;
+    let server = null;
+    let timeoutHandle = null;
+    let abortListener = null;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+            timeoutHandle = null;
+        }
+        if (abortListener && signal) {
+            signal.removeEventListener("abort", abortListener);
+            abortListener = null;
+        }
+        if (server)
+            await closeServer(server);
+    };
+    // Test-and-set on the one-shot slot. Returns true if the caller won the
+    // claim (and must settle the promise); false if another caller already
+    // consumed it (and must not touch the promise).
+    const tryConsume = () => {
+        if (consumed)
+            return false;
+        consumed = true;
+        return true;
+    };
+    // For out-of-band settlements (timeout, abort) that don't involve a response
+    // the client needs to see. Closes the server immediately.
+    const settleRejectNow = (err) => {
+        if (!tryConsume())
+            return;
+        rejectResult(err);
+        void close();
+    };
+    // For in-handler settlements: defer the promise + server-close until the
+    // response has been flushed to the client, so the browser actually sees the
+    // success/error page before we tear down the socket. "finish" is the event
+    // that fires when the response body has been handed to the OS; "close" and
+    // "error" are fallbacks for early aborts so we never leak an unsettled
+    // promise.
+    const deferSettleOnClose = (res, finalize) => {
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            res.off("finish", settle);
+            res.off("close", settle);
+            res.off("error", settle);
+            finalize();
+            void close();
+        };
+        res.once("finish", settle);
+        res.once("close", settle);
+        res.once("error", settle);
+    };
+    const handler = (req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (url.pathname === "/favicon.ico") {
+            writeText(res, 404, "Not Found");
+            return;
+        }
+        if (req.method !== "GET") {
+            writeText(res, 405, "Method Not Allowed", { Allow: "GET" });
+            return;
+        }
+        if (!isLoopback(req.socket.remoteAddress)) {
+            writeText(res, 403, "Forbidden");
+            return;
+        }
+        if (url.pathname !== "/callback") {
+            writeText(res, 404, "Not Found");
+            return;
+        }
+        // Atomically decide whether this request owns the one-shot slot. Claiming
+        // up front means once we start composing the response, no concurrent
+        // settlement (timer/abort) can race us into a dropped connection.
+        if (!tryConsume()) {
+            writeHtml(res, 409, (0, renderHtml_1.renderHtml)({
+                kind: "error",
+                reason: "This callback server has already handled a response.",
+            }));
+            return;
+        }
+        const providerError = url.searchParams.get("error");
+        if (providerError) {
+            const description = url.searchParams.get("error_description") ?? undefined;
+            const error = new errors_1.OAuthCallbackError("PROVIDER_ERROR", `Authorization server returned error: ${providerError}`, {
+                details: description
+                    ? { error: providerError, error_description: description }
+                    : { error: providerError },
+            });
+            deferSettleOnClose(res, () => rejectResult(error));
+            writeHtml(res, 400, (0, renderHtml_1.renderHtml)({
+                kind: "error",
+                reason: providerError,
+                description,
+            }));
+            return;
+        }
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        if (!code) {
+            const error = new errors_1.OAuthCallbackError("MISSING_CODE", "Authorization response missing 'code' parameter.");
+            deferSettleOnClose(res, () => rejectResult(error));
+            writeHtml(res, 400, (0, renderHtml_1.renderHtml)({
+                kind: "error",
+                reason: "The authorization response was missing the 'code' parameter.",
+            }));
+            return;
+        }
+        if (state !== expectedState) {
+            const error = new errors_1.OAuthCallbackError("STATE_MISMATCH", "Authorization response 'state' did not match expected value.");
+            deferSettleOnClose(res, () => rejectResult(error));
+            writeHtml(res, 400, (0, renderHtml_1.renderHtml)({
+                kind: "error",
+                reason: "The authorization response failed state validation.",
+            }));
+            return;
+        }
+        deferSettleOnClose(res, () => resolveResult({ code, state }));
+        writeHtml(res, 200, (0, renderHtml_1.renderHtml)({ kind: "success" }));
+    };
+    const bound = await (0, exports.bindLoopback)(handler);
+    server = bound.server;
+    const port = server.address().port;
+    const redirectUri = bound.host === "::1"
+        ? `http://[::1]:${port}/callback`
+        : `http://127.0.0.1:${port}/callback`;
+    timeoutHandle = setTimeout(() => {
+        settleRejectNow(new errors_1.OAuthCallbackError("TIMEOUT", `No OAuth callback received within ${timeoutMs}ms.`));
+    }, timeoutMs);
+    if (signal) {
+        if (signal.aborted) {
+            settleRejectNow(new errors_1.OAuthCallbackError("ABORTED", "Callback server aborted."));
+        }
+        else {
+            abortListener = () => {
+                settleRejectNow(new errors_1.OAuthCallbackError("ABORTED", "Callback server aborted."));
+            };
+            signal.addEventListener("abort", abortListener, { once: true });
+        }
+    }
+    return { redirectUri, result, close };
+};
+exports.startCallbackServer = startCallbackServer;

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,173 @@
+"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 userAgent_1 = require("../userAgent");
+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),
+    };
+}
+/**
+ * `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.
+ */
+function assertPKCESupport(body, url) {
+    const methods = body.code_challenge_methods_supported;
+    if (!Array.isArray(methods))
+        return;
+    if (methods.includes("S256"))
+        return;
+    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.
+ *
+ * @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, {
+            headers: { "User-Agent": userAgent_1.USER_AGENT },
+            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);
+    }
+    assertPKCESupport(body, url);
+    return config;
+}

package/dist/oauth/discoverSSOConfig.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+export interface SSOConfig {
+    /** Keycloak base URL, e.g. `https://auth.example.com`. */
+    url: string;
+    /** Keycloak realm name. */
+    realm: string;
+    /** OAuth client ID for the axe-auth CLI. */
+    mcpClientId: string;
+}
+/** Options for `discoverSSOConfig`. */
+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`.
+     */
+    allowInsecure?: boolean;
+}
+/**
+ * Fetches and parses the axe server's `/api/sso-config` discovery
+ * endpoint. Used by `axe-auth login` to derive the OAuth issuer URL,
+ * realm, and CLI-specific client ID from the axe server URL the user
+ * supplied (or the SaaS prod default), so users no longer have to know
+ * the underlying Keycloak coordinates.
+ *
+ * Distinguishes three failure shapes for the operator-relevant cases:
+ *
+ * - `mcpClientId` field absent: the axe server deployment predates the
+ *   field entirely. Surfaces as "needs upgrading".
+ * - `mcpClientId` is `null`: the axe server version supports the field
+ *   but the operator has not configured `KEYCLOAK_MCP_PUBLIC_CLIENT_ID`.
+ *   Surfaces as "ask the operator to configure".
+ * - any non-empty string: returned as-is.
+ *
+ * Other failure modes (unreachable, non-2xx, malformed JSON, missing
+ * `url` / `realm`) all map to `DISCOVERY_FAILED` with a descriptive
+ * message. The caller is expected to surface these errors verbatim.
+ */
+export declare function discoverSSOConfig(serverURL: string, options?: DiscoverSSOConfigOptions): Promise<SSOConfig>;

package/dist/oauth/discoverSSOConfig.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverSSOConfig = discoverSSOConfig;
+const errors_1 = require("./errors");
+const predicates_1 = require("./predicates");
+const userAgent_1 = require("../userAgent");
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+function assertSecureServerURL(serverURL, allowInsecure) {
+    let parsed;
+    try {
+        parsed = new URL(serverURL);
+    }
+    catch {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server URL is not a valid URL: ${serverURL}`);
+    }
+    if (parsed.protocol === "https:")
+        return parsed;
+    if (parsed.protocol === "http:") {
+        const hostname = parsed.host.toLowerCase().replace(/:\d+$/, "");
+        if (LOOPBACK_HOSTS.has(hostname))
+            return parsed;
+        if (allowInsecure)
+            return parsed;
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Refusing to use axe server URL over http:// against non-loopback host ${parsed.host}. Use https:// or pass --allow-insecure-issuer to override (only do this on trusted networks).`);
+    }
+    throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Unsupported axe server URL scheme '${parsed.protocol}'; expected https: or http: (loopback only).`);
+}
+function buildSSOConfigURL(parsed) {
+    const copy = new URL(parsed.toString());
+    copy.search = "";
+    copy.hash = "";
+    copy.pathname = `${copy.pathname.replace(/\/+$/, "")}/api/sso-config`;
+    return copy.toString();
+}
+/**
+ * Fetches and parses the axe server's `/api/sso-config` discovery
+ * endpoint. Used by `axe-auth login` to derive the OAuth issuer URL,
+ * realm, and CLI-specific client ID from the axe server URL the user
+ * supplied (or the SaaS prod default), so users no longer have to know
+ * the underlying Keycloak coordinates.
+ *
+ * Distinguishes three failure shapes for the operator-relevant cases:
+ *
+ * - `mcpClientId` field absent: the axe server deployment predates the
+ *   field entirely. Surfaces as "needs upgrading".
+ * - `mcpClientId` is `null`: the axe server version supports the field
+ *   but the operator has not configured `KEYCLOAK_MCP_PUBLIC_CLIENT_ID`.
+ *   Surfaces as "ask the operator to configure".
+ * - any non-empty string: returned as-is.
+ *
+ * Other failure modes (unreachable, non-2xx, malformed JSON, missing
+ * `url` / `realm`) all map to `DISCOVERY_FAILED` with a descriptive
+ * message. The caller is expected to surface these errors verbatim.
+ */
+async function discoverSSOConfig(serverURL, options = {}) {
+    const allowInsecure = options.allowInsecure ?? false;
+    const parsed = assertSecureServerURL(serverURL, allowInsecure);
+    const url = buildSSOConfigURL(parsed);
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { "User-Agent": userAgent_1.USER_AGENT },
+            signal: options.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Could not reach the axe server at ${url}. Check the --server URL and your network connection.`, { cause });
+    }
+    if (!response.ok) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${url} responded with HTTP ${response.status}. Check the --server URL.`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${url} did not return valid JSON.`, { cause });
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${url} returned a non-object response body.`);
+    }
+    const raw = body;
+    const missing = [];
+    if (!(0, predicates_1.isNonEmptyString)(raw.url))
+        missing.push("url");
+    if (!(0, predicates_1.isNonEmptyString)(raw.realm))
+        missing.push("realm");
+    if (missing.length > 0) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `${url} is missing required field(s): ${missing.join(", ")}`);
+    }
+    if (!("mcpClientId" in raw)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${serverURL} does not advertise OAuth-based MCP authentication. The deployment may need to be upgraded to a version that supports the axe-auth CLI.`);
+    }
+    if (raw.mcpClientId === null) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${serverURL} has not been configured for OAuth-based MCP authentication. Ask your operator to set the KEYCLOAK_MCP_PUBLIC_CLIENT_ID environment variable on the axe server.`);
+    }
+    if (!(0, predicates_1.isNonEmptyString)(raw.mcpClientId)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${serverURL} returned a malformed mcpClientId (expected a non-empty string).`);
+    }
+    return {
+        url: raw.url,
+        realm: raw.realm,
+        mcpClientId: raw.mcpClientId,
+    };
+}