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

package/README.md

@@ -1,6 +1,8 @@
 # @deque/axe-auth
 
-CLI for authenticating with Deque's axe MCP server and other services.
+CLI for authenticating with Deque services via the OAuth 2.0 Authorization Code + PKCE flow (RFC 6749, RFC 7636, RFC 8252 §7.3).
+
+**Status: early.** The `axe-auth` binary this package installs currently implements only `--version` / `--help`. The OAuth flow machinery (discovery, PKCE, loopback callback server, token exchange, keychain persistence) is in place; the user-facing subcommands (`login`, `logout`, `token`) are being added in [#423](https://github.com/dequelabs/axe-mcp-server/issues/423).
 
 ## Installation
 
@@ -20,9 +22,23 @@ npx @deque/axe-auth
 axe-auth [options]
 ```
 
-### Options
-
 | Flag              | Description         |
 | ----------------- | ------------------- |
 | `-v`, `--version` | Show version number |
 | `-h`, `--help`    | Show help message   |
+
+## Architecture
+
+Design notes live under [`packages/axe-auth/docs/`](https://github.com/dequelabs/axe-mcp-server/tree/develop/packages/axe-auth/docs):
+
+- [`oauth-flow.md`](https://github.com/dequelabs/axe-mcp-server/blob/develop/packages/axe-auth/docs/oauth-flow.md) — high-level OAuth 2.0 + PKCE flow.
+- [`callback-server.md`](https://github.com/dequelabs/axe-mcp-server/blob/develop/packages/axe-auth/docs/callback-server.md) — `startCallbackServer` API and RFC 8252 conformance.
+- [`callback-page.md`](https://github.com/dequelabs/axe-mcp-server/blob/develop/packages/axe-auth/docs/callback-page.md) — HTML response design, branding, and CSP rationale.
+
+## Caveats
+
+- **Linux keychain support is untested.** `@napi-rs/keyring` requires a working D-Bus Secret Service (GNOME Keyring, KWallet, etc.). Users on headless or minimal-desktop Linux environments may see `KEYRING_UNAVAILABLE`; a file-backed `TokenStore` fallback is tracked as a follow-up ([#464](https://github.com/dequelabs/axe-mcp-server/issues/464)).
+
+## Contributing
+
+Running the OAuth flow end-to-end against a local Keycloak, plus the two smoke-test scripts, is documented in [`docs/local-dev.md`](https://github.com/dequelabs/axe-mcp-server/blob/develop/packages/axe-auth/docs/local-dev.md).

package/dist/index.js

@@ -5,26 +5,7 @@ const node_util_1 = require("node:util");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8"));
-let values;
-try {
-    ({ values } = (0, node_util_1.parseArgs)({
-        options: {
-            version: { type: "boolean", short: "v" },
-            help: { type: "boolean", short: "h" },
-        },
-        strict: true,
-    }));
-}
-catch (err) {
-    console.error(err.message);
-    process.exit(1);
-}
-if (values.version) {
-    console.log(pkg.version);
-    process.exit(0);
-}
-if (values.help) {
-    console.log(`${pkg.name} v${pkg.version}
+const helpText = `${pkg.name} v${pkg.version}
 
 ${pkg.description}
 
@@ -33,8 +14,34 @@ Usage:
 
 Options:
   -v, --version  Show version number
-  -h, --help     Show this help message`);
-    process.exit(0);
-}
-console.log("No arguments provided. Use --help for usage information.\n");
-process.exit(1);
+  -h, --help     Show this help message`;
+const main = async () => {
+    let values;
+    try {
+        ({ values } = (0, node_util_1.parseArgs)({
+            options: {
+                version: { type: "boolean", short: "v" },
+                help: { type: "boolean", short: "h" },
+            },
+            strict: true,
+        }));
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+    if (values.version) {
+        console.log(pkg.version);
+        return 0;
+    }
+    if (values.help) {
+        console.log(helpText);
+        return 0;
+    }
+    console.log("No arguments provided. Use --help for usage information.");
+    return 1;
+};
+main().then((code) => process.exit(code), (err) => {
+    console.error(err);
+    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,83 @@
+import { type TokenSet } from "./tokenExchange";
+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
+     * `KeyringTokenStore` keyed by the normalized issuer URL.
+     */
+    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,114 @@
+"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(issuerURL), 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 === undefined) {
+            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);
+        return tokens;
+    }
+    finally {
+        await callback.close();
+    }
+}

package/dist/oauth/callbackServer.d.ts

@@ -0,0 +1,23 @@
+import { IncomingMessage, Server, ServerResponse } from "node:http";
+export type CallbackServerOptions = {
+    expectedState: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export type CallbackResult = {
+    code: string;
+    state: string;
+};
+export type CallbackServerHandle = {
+    redirectUri: string;
+    result: Promise<CallbackResult>;
+    close: () => Promise<void>;
+};
+type RequestHandler = (req: IncomingMessage, res: ServerResponse) => void;
+type LoopbackListener = (handler: RequestHandler, host: string) => Promise<Server>;
+export declare const bindLoopback: (handler: RequestHandler, listenFn?: LoopbackListener) => Promise<{
+    server: Server;
+    host: "127.0.0.1" | "::1";
+}>;
+export declare const startCallbackServer: (opts: CallbackServerOptions) => Promise<CallbackServerHandle>;
+export {};

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;