dsh-plugin-subscription-oauth 0.0.0-stage → 0.2.0

package/lib/auth/glm-flow.js

@@ -0,0 +1,194 @@
+/**
+ * The ZCode CLI-style OAuth flow BigModel's coding plan signs in with.
+ *
+ * ZCode does not authorize by device code or by a loopback redirect. It asks its
+ * own backend for a *flow*: `init` returns an `authorize_url` plus a flow id, the
+ * user signs in at `bigmodel.cn` in a browser, and the callback is completed
+ * server-side by `zcode.z.ai`. The client then polls the flow until the backend
+ * reports it ready and hands back the tokens.
+ *
+ * That shape is what makes this implementable outside the ZCode app: nothing has
+ * to receive a `zcode://oauth/callback` custom-protocol redirect, and no app
+ * secret is involved. The poll is authenticated with a secret this client
+ * generates itself, so the flow belongs to whoever started it.
+ *
+ * Wire contract, read out of ZCode 3.14.4's host bundle and verified against the
+ * live endpoint:
+ *
+ * - `POST /api/v1/oauth/cli/init`, `Authorization: Bearer <64 hex>`,
+ *   `{ "provider": "bigmodel" }`
+ *   → `{ code: 0, data: { flow_id, poll_token, authorize_url, expires_at,
+ *     poll_interval_sec } }`
+ * - `GET /api/v1/oauth/cli/poll/<flow_id>`, same bearer
+ *   → `{ code: 0, data: { status: "pending" } }` while waiting, then
+ *     `{ code: 0, data: { status: "ready", token, user, bigmodel: {
+ *     access_token, refresh_token } } }`
+ *
+ * @module dsh-plugin-subscription-oauth/auth/glm-flow
+ */
+import { randomBytes } from 'node:crypto';
+import { decodeJwtClaims } from './device-flow.js';
+/** Backend that brokers the flow; the browser never talks to it directly. */
+export const GLM_OAUTH_BASE = 'https://zcode.z.ai';
+/** Flow-initiation path on the broker. */
+export const GLM_INIT_PATH = '/api/v1/oauth/cli/init';
+/** Flow-poll path on the broker; the flow id is appended. */
+export const GLM_POLL_PATH = '/api/v1/oauth/cli/poll';
+/** Provider key the broker knows the China-region coding plan by. */
+export const GLM_BROKER_PROVIDER = 'bigmodel';
+/** How long one request to the broker may take. */
+const REQUEST_TIMEOUT_MS = 20_000;
+/** Poll cadence used when `init` states none. */
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+/** Fallback token lifetime when neither the token nor the response states one. */
+const DEFAULT_TOKEN_TTL_MS = 24 * 60 * 60 * 1000;
+/** Non-empty trimmed string, or undefined. */
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/** A finite number, or undefined. */
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** A JSON object, or undefined. */
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Read the token from either casing the broker has used. */
+function tokenField(source, snake, camel) {
+    if (source === undefined)
+        return undefined;
+    return text(source[snake]) ?? text(source[camel]);
+}
+/**
+ * Decode one broker response body.
+ *
+ * The broker answers HTTP 200 with a business `code` for most refusals, so the
+ * envelope is checked before the payload is.
+ *
+ * @param payload - the decoded body.
+ * @param what - label used in the error message.
+ * @returns the `data` object.
+ * @throws {Error} when the envelope is a refusal or carries no data.
+ */
+function dataOf(payload, what) {
+    const envelope = record(payload);
+    if (envelope === undefined)
+        throw new Error(`${what}: the broker sent no JSON object`);
+    const code = finite(envelope.code);
+    if (code !== undefined && code !== 0) {
+        throw new Error(`${what}: ${text(envelope.msg) ?? `the broker refused with code ${String(code)}`}`);
+    }
+    const data = record(envelope.data);
+    if (data === undefined)
+        throw new Error(`${what}: the broker sent no data`);
+    return data;
+}
+/**
+ * Create a flow and return the URL the user signs in at.
+ *
+ * @param spec - broker origin, fetch, and clock.
+ * @param signal - optional caller cancellation.
+ * @returns the live flow.
+ * @throws {Error} when the broker refuses or answers a shape this build cannot use.
+ */
+export async function startGlmFlow(spec = {}, signal) {
+    const base = (spec.baseUrl ?? GLM_OAUTH_BASE).replace(/\/+$/, '');
+    const fetchFn = spec.fetchFn ?? fetch;
+    const now = spec.now ?? Date.now;
+    // The flow is authenticated by a secret only this caller knows, so a poll can
+    // never pick up somebody else's login.
+    const pollToken = randomBytes(32).toString('hex');
+    const response = await fetchFn(`${base}${GLM_INIT_PATH}`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${pollToken}`,
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({ provider: GLM_BROKER_PROVIDER }),
+        signal: signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`GLM sign-in could not start (HTTP ${response.status})`);
+    }
+    const data = dataOf(await response.json(), 'GLM sign-in could not start');
+    const flowId = text(data.flow_id);
+    const authorizeUrl = text(data.authorize_url);
+    if (flowId === undefined || authorizeUrl === undefined) {
+        throw new Error('GLM sign-in could not start: the broker stated no flow');
+    }
+    let parsed;
+    try {
+        parsed = new URL(authorizeUrl);
+    }
+    catch {
+        throw new Error('GLM sign-in could not start: the broker stated an unusable authorize URL');
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error('GLM sign-in could not start: the authorize URL is not https');
+    }
+    const expiresAtSeconds = finite(data.expires_at);
+    const intervalSeconds = finite(data.poll_interval_sec);
+    return {
+        flowId,
+        authorizeUrl: parsed.toString(),
+        expiresAt: expiresAtSeconds === undefined ? now() + 15 * 60 * 1000 : expiresAtSeconds * 1000,
+        pollIntervalMs: intervalSeconds === undefined ? DEFAULT_POLL_INTERVAL_MS : Math.max(1_000, intervalSeconds * 1000),
+        pollToken,
+    };
+}
+/**
+ * Ask the broker once whether the flow completed.
+ *
+ * @param spec - broker origin, fetch, and clock.
+ * @param start - the flow to ask about.
+ * @param signal - optional caller cancellation.
+ * @returns the tokens once the flow is ready, or undefined while it is pending.
+ * @throws {Error} when the flow expired, failed, or the broker refused.
+ */
+export async function pollGlmFlow(spec, start, signal) {
+    const base = (spec.baseUrl ?? GLM_OAUTH_BASE).replace(/\/+$/, '');
+    const fetchFn = spec.fetchFn ?? fetch;
+    const now = spec.now ?? Date.now;
+    if (now() >= start.expiresAt)
+        throw new Error('GLM sign-in expired; start it again');
+    const response = await fetchFn(`${base}${GLM_POLL_PATH}/${encodeURIComponent(start.flowId)}`, {
+        headers: { authorization: `Bearer ${start.pollToken}` },
+        signal: signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok)
+        throw new Error(`GLM sign-in polling failed (HTTP ${response.status})`);
+    const data = dataOf(await response.json(), 'GLM sign-in polling failed');
+    const status = text(data.status);
+    if (status === 'pending')
+        return undefined;
+    if (status === 'failed')
+        throw new Error('GLM sign-in was refused in the browser');
+    if (status !== 'ready')
+        throw new Error(`GLM sign-in polling failed: unknown status ${JSON.stringify(status)}`);
+    const bigmodel = record(data.bigmodel);
+    const accessToken = tokenField(bigmodel, 'access_token', 'accessToken');
+    const zcodeJwt = text(data.token);
+    if (accessToken === undefined || zcodeJwt === undefined) {
+        throw new Error('GLM sign-in completed without the tokens this build needs');
+    }
+    const refreshToken = tokenField(bigmodel, 'refresh_token', 'refreshToken');
+    const user = record(data.user);
+    const accountId = text(user?.user_id) ?? text(user?.userId);
+    const label = text(user?.name) ?? text(user?.email);
+    // The JWT states its own expiry; the access token does not, so the earlier of
+    // the two is what the session treats as the deadline.
+    const claims = decodeJwtClaims(zcodeJwt);
+    const expSeconds = finite(claims?.exp);
+    const jwtExpiry = expSeconds === undefined ? undefined : expSeconds * 1000;
+    return {
+        accessToken,
+        zcodeJwt,
+        ...refreshToken === undefined ? {} : { refreshToken },
+        expiresAt: jwtExpiry ?? now() + DEFAULT_TOKEN_TTL_MS,
+        ...accountId === undefined ? {} : { accountId },
+        ...label === undefined ? {} : { label },
+    };
+}

package/lib/auth/headers.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The `X-Msh-*` client-identity headers Kimi Code admits a request under.
+ *
+ * Kimi's coding service admits a caller through this header family rather than
+ * a bearer-token grant alone: the CLI declares its own version, its platform
+ * family, and a per-machine device id that must stay stable across restarts
+ * (the service correlates usage to it). The device model string is a single
+ * `<platform> <release> <arch>` line, not three headers.
+ *
+ * @module dsh-plugin-subscription-oauth/auth/headers
+ */
+/**
+ * The platform word Kimi's client reports. `os.platform()` yields `win32` and
+ * `darwin`, which the service does not recognise; the CLI reports the
+ * marketing name instead.
+ * @param platform - `process.platform` value.
+ * @returns the platform word used in `X-Msh-Device-Model`.
+ */
+export declare function platformWord(platform?: string): string;
+/**
+ * Build the device-model header value: `<platform> <release> <arch>`.
+ * @param platform - `process.platform` value.
+ * @returns one space-separated descriptor line.
+ */
+export declare function deviceModel(platform?: string): string;
+/**
+ * Resolve the OS-version header. `os.version()` is absent on some runtimes, so
+ * an unavailable value degrades to the kernel release rather than the literal
+ * string `"undefined"`.
+ * @returns a non-empty version descriptor.
+ */
+export declare function osVersion(): string;
+/**
+ * Assemble the identity headers every Kimi Code request carries.
+ * @param deviceId - this machine's persisted 32-hex device id.
+ * @returns the `X-Msh-*` / `User-Agent` header record.
+ */
+export declare function kimiIdentityHeaders(deviceId: string): Record<string, string>;
+/**
+ * Merge the Kimi client identity with the harness attribution header for one
+ * provider request.
+ *
+ * Two requirements meet here: Kimi's service admits a request by the
+ * `KimiCLI/<version>` product token, and the harness contract requires
+ * `attributionHeaders()` on every provider request. Sending both products as
+ * separate `User-Agent` fields would let a transport join them with `", "`, so
+ * they are combined into one RFC 9110 product value instead. Every other
+ * identity header is passed through untouched.
+ *
+ * @param identity - {@link kimiIdentityHeaders} output for this machine.
+ * @param extra - request-specific headers, which win on collision.
+ * @returns the header record to send.
+ */
+export declare function kimiRequestHeaders(identity: Record<string, string>, extra?: Record<string, string>): Record<string, string>;
+/**
+ * Attribution headers for a provider that needs no client identity of its own.
+ *
+ * @param extra - request-specific headers, which win on collision.
+ * @returns the header record to send.
+ */
+export declare function attributedHeaders(extra?: Record<string, string>): Record<string, string>;

package/lib/auth/headers.js

@@ -0,0 +1,106 @@
+/**
+ * The `X-Msh-*` client-identity headers Kimi Code admits a request under.
+ *
+ * Kimi's coding service admits a caller through this header family rather than
+ * a bearer-token grant alone: the CLI declares its own version, its platform
+ * family, and a per-machine device id that must stay stable across restarts
+ * (the service correlates usage to it). The device model string is a single
+ * `<platform> <release> <arch>` line, not three headers.
+ *
+ * @module dsh-plugin-subscription-oauth/auth/headers
+ */
+import os from 'node:os';
+import { attributionHeaders, userAgent } from '@deepseek-ai/dsh-llm';
+import { KIMI_CLI_VERSION } from '../constants.js';
+/**
+ * The platform word Kimi's client reports. `os.platform()` yields `win32` and
+ * `darwin`, which the service does not recognise; the CLI reports the
+ * marketing name instead.
+ * @param platform - `process.platform` value.
+ * @returns the platform word used in `X-Msh-Device-Model`.
+ */
+export function platformWord(platform = process.platform) {
+    switch (platform) {
+        case 'win32': return 'Windows';
+        case 'darwin': return 'macOS';
+        case 'linux': return 'Linux';
+        default: return platform;
+    }
+}
+/**
+ * Build the device-model header value: `<platform> <release> <arch>`.
+ * @param platform - `process.platform` value.
+ * @returns one space-separated descriptor line.
+ */
+export function deviceModel(platform = process.platform) {
+    return `${platformWord(platform)} ${os.release()} ${os.arch()}`;
+}
+/**
+ * Resolve the OS-version header. `os.version()` is absent on some runtimes, so
+ * an unavailable value degrades to the kernel release rather than the literal
+ * string `"undefined"`.
+ * @returns a non-empty version descriptor.
+ */
+export function osVersion() {
+    const version = os.version;
+    if (typeof version === 'function') {
+        try {
+            const value = version();
+            if (typeof value === 'string' && value.length > 0)
+                return value;
+        }
+        catch {
+            // fall through to the release string
+        }
+    }
+    return os.release();
+}
+/**
+ * Assemble the identity headers every Kimi Code request carries.
+ * @param deviceId - this machine's persisted 32-hex device id.
+ * @returns the `X-Msh-*` / `User-Agent` header record.
+ */
+export function kimiIdentityHeaders(deviceId) {
+    return {
+        'User-Agent': `KimiCLI/${KIMI_CLI_VERSION}`,
+        'X-Msh-Platform': 'kimi_code_cli',
+        'X-Msh-Version': KIMI_CLI_VERSION,
+        'X-Msh-Device-Name': os.hostname(),
+        'X-Msh-Device-Model': deviceModel(),
+        'X-Msh-Os-Version': osVersion(),
+        'X-Msh-Device-Id': deviceId,
+    };
+}
+/**
+ * Merge the Kimi client identity with the harness attribution header for one
+ * provider request.
+ *
+ * Two requirements meet here: Kimi's service admits a request by the
+ * `KimiCLI/<version>` product token, and the harness contract requires
+ * `attributionHeaders()` on every provider request. Sending both products as
+ * separate `User-Agent` fields would let a transport join them with `", "`, so
+ * they are combined into one RFC 9110 product value instead. Every other
+ * identity header is passed through untouched.
+ *
+ * @param identity - {@link kimiIdentityHeaders} output for this machine.
+ * @param extra - request-specific headers, which win on collision.
+ * @returns the header record to send.
+ */
+export function kimiRequestHeaders(identity, extra = {}) {
+    const cliAgent = identity['User-Agent'] ?? identity['user-agent'];
+    const headers = { ...identity, ...attributionHeaders(), ...extra };
+    if (cliAgent !== undefined) {
+        delete headers['user-agent'];
+        headers['User-Agent'] = `${cliAgent} ${userAgent()}`;
+    }
+    return headers;
+}
+/**
+ * Attribution headers for a provider that needs no client identity of its own.
+ *
+ * @param extra - request-specific headers, which win on collision.
+ * @returns the header record to send.
+ */
+export function attributedHeaders(extra = {}) {
+    return { ...attributionHeaders(), ...extra };
+}

package/lib/auth/pkce-flow.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Loopback OAuth: PKCE helpers plus a temporary local redirect listener.
+ *
+ * Providers that complete authorization in the browser (xAI, Google) redirect to
+ * a `127.0.0.1` URL this process owns for the duration of one attempt. The
+ * authorization code never leaves the machine, and `state` is validated before
+ * the code is accepted so a stray or replayed redirect cannot settle the login.
+ *
+ * @module dsh-plugin-subscription-oauth/auth/pkce-flow
+ */
+import type { AuthAttempt, AuthFlow } from './flow.js';
+import type { SessionBase } from './store.js';
+/** One PKCE verifier/challenge pair; the verifier stays local until exchange. */
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+/** Mint a fresh PKCE pair (32-byte verifier, S256 challenge). */
+export declare function createPkce(): PkcePair;
+/** Mint a random OAuth `state` value. */
+export declare function randomState(): string;
+/** Inputs an authorize-URL builder needs for one attempt. */
+export interface LoopbackAuthorizeInput {
+    /** Loopback redirect URI pointing at the temporary listener. */
+    redirectUri: string;
+    state: string;
+    pkce: PkcePair;
+}
+/** Inputs a token exchange needs once the code arrives. */
+export interface LoopbackExchangeInput<S extends SessionBase> {
+    code: string;
+    redirectUri: string;
+    pkce: PkcePair;
+    state: string;
+    /** Aborts when the attempt is cancelled or times out. */
+    signal: AbortSignal;
+}
+/** Static facts of one provider's loopback flow. */
+export interface LoopbackFlowSpec<S extends SessionBase> {
+    /** Ports tried in order; the first free one wins. */
+    readonly ports: readonly number[];
+    /** Path the provider redirects to. */
+    readonly callbackPath: string;
+    /** Attempt lifetime; defaults to three minutes. */
+    readonly timeoutMs?: number;
+    /**
+     * Resolve anything `buildAuthorizeUrl` needs but only an async step can fetch,
+     * such as OIDC discovery endpoints. Called before the listener is opened.
+     */
+    prepare?(): Promise<void>;
+    /** Build the URL the user's browser opens. */
+    buildAuthorizeUrl(input: LoopbackAuthorizeInput): string;
+    /** Exchange the authorization code for a session. */
+    exchange(input: LoopbackExchangeInput<S>): Promise<S>;
+}
+/** Attempt lifetime when a spec names none. */
+export declare const DEFAULT_FLOW_TIMEOUT_MS = 180000;
+/** Message every cancelled attempt rejects with. */
+export declare const LOGIN_CANCELLED_MESSAGE = "login cancelled";
+/**
+ * Owns at most one in-flight loopback login per provider.
+ *
+ * A listener is created per attempt and closed as soon as the attempt settles,
+ * so nothing stays open on this machine between logins.
+ */
+export declare class LoopbackFlow<S extends SessionBase> implements AuthFlow<S> {
+    private readonly key;
+    private readonly spec;
+    private readonly host;
+    private readonly attempts;
+    /**
+     * @param key - provider route key, so one attempt runs at a time per route.
+     * @param spec - static flow facts for this provider.
+     */
+    constructor(key: string, spec: LoopbackFlowSpec<S>, host?: string);
+    pending(): AuthAttempt<S> | undefined;
+    start(): Promise<AuthAttempt<S>>;
+}

package/lib/auth/pkce-flow.js

@@ -0,0 +1,205 @@
+/**
+ * Loopback OAuth: PKCE helpers plus a temporary local redirect listener.
+ *
+ * Providers that complete authorization in the browser (xAI, Google) redirect to
+ * a `127.0.0.1` URL this process owns for the duration of one attempt. The
+ * authorization code never leaves the machine, and `state` is validated before
+ * the code is accepted so a stray or replayed redirect cannot settle the login.
+ *
+ * @module dsh-plugin-subscription-oauth/auth/pkce-flow
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+/** Mint a fresh PKCE pair (32-byte verifier, S256 challenge). */
+export function createPkce() {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    return { verifier, challenge };
+}
+/** Mint a random OAuth `state` value. */
+export function randomState() {
+    return randomBytes(32).toString('base64url');
+}
+/** Attempt lifetime when a spec names none. */
+export const DEFAULT_FLOW_TIMEOUT_MS = 180_000;
+/** Message every cancelled attempt rejects with. */
+export const LOGIN_CANCELLED_MESSAGE = 'login cancelled';
+const SUCCESS_PAGE = '<!doctype html><html><head><meta charset="utf-8"><title>Login successful</title></head>'
+    + '<body style="font-family:sans-serif"><h1>Login successful</h1>'
+    + '<p>You can close this tab and return to DeepSeek Harness.</p></body></html>';
+/**
+ * Addresses one listen host covers.
+ *
+ * `localhost` resolves to `::1` or `127.0.0.1` depending on the client, and a
+ * listener binds exactly one family per call — a browser picking the other gets
+ * connection-refused and the login times out, so both families must serve.
+ */
+function listenHosts(host) {
+    return host === 'localhost' ? ['127.0.0.1', '::1'] : [host];
+}
+/** True when an address family simply does not exist here (safe to skip). */
+function familyUnavailable(error) {
+    const code = error.code;
+    return code === 'EADDRNOTAVAIL' || code === 'EPROTONOSUPPORT';
+}
+/** Listen on the first port free on every loopback family. */
+async function listen(handler, host, ports) {
+    const hosts = listenHosts(host);
+    let lastError;
+    for (const candidate of ports) {
+        const servers = [];
+        let port = candidate;
+        let unusable = false;
+        for (const address of hosts) {
+            const server = createServer(handler);
+            try {
+                await new Promise((resolve, reject) => {
+                    const onError = (error) => reject(error);
+                    server.once('error', onError);
+                    server.listen(port, address, () => {
+                        server.removeListener('error', onError);
+                        resolve();
+                    });
+                });
+                const bound = server.address();
+                if (bound === null)
+                    throw new Error(`callback listener on ${address}:${String(port)} has no address`);
+                if (port === 0)
+                    port = bound.port;
+                servers.push(server);
+            }
+            catch (error) {
+                server.close();
+                if (familyUnavailable(error))
+                    continue;
+                lastError = error;
+                unusable = true;
+                break;
+            }
+        }
+        if (unusable || servers.length === 0) {
+            for (const server of servers)
+                server.close();
+            continue;
+        }
+        return { servers, port };
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`callback listener could not bind ${host} (ports ${ports.join(', ')})`);
+}
+/**
+ * Owns at most one in-flight loopback login per provider.
+ *
+ * A listener is created per attempt and closed as soon as the attempt settles,
+ * so nothing stays open on this machine between logins.
+ */
+export class LoopbackFlow {
+    key;
+    spec;
+    host;
+    attempts = new Map();
+    /**
+     * @param key - provider route key, so one attempt runs at a time per route.
+     * @param spec - static flow facts for this provider.
+     */
+    constructor(key, spec, host = '127.0.0.1') {
+        this.key = key;
+        this.spec = spec;
+        this.host = host;
+    }
+    pending() {
+        return this.attempts.get(this.key);
+    }
+    async start() {
+        if (this.attempts.has(this.key)) {
+            throw new Error(`a ${this.key} login attempt is already in progress`);
+        }
+        const pkce = createPkce();
+        const state = randomState();
+        const timeoutMs = this.spec.timeoutMs ?? DEFAULT_FLOW_TIMEOUT_MS;
+        const controller = new AbortController();
+        // Discovery-backed specs resolve their endpoints before anything is bound.
+        await this.spec.prepare?.();
+        let settle;
+        let fail;
+        const session = new Promise((resolve, reject) => {
+            settle = resolve;
+            fail = reject;
+        });
+        session.catch(() => undefined);
+        let settled = false;
+        let timer;
+        let servers = [];
+        /** The bound port, known once the listener is up; the handler runs later. */
+        let port = 0;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            for (const server of servers) {
+                server.close();
+                server.closeAllConnections();
+            }
+            this.attempts.delete(this.key);
+            controller.abort();
+            if (error !== undefined)
+                fail(error);
+            else if (value !== undefined)
+                settle(value);
+        };
+        const handler = (request, response) => {
+            const url = new URL(request.url ?? '/', 'http://localhost');
+            if (url.pathname !== this.spec.callbackPath) {
+                response.writeHead(404, { 'content-type': 'text/plain' });
+                response.end('not found');
+                return;
+            }
+            const reported = url.searchParams.get('error_description') ?? url.searchParams.get('error');
+            if (reported !== null) {
+                response.writeHead(200, { 'content-type': 'text/html' });
+                response.end('<!doctype html><html><body><h1>Login failed</h1></body></html>');
+                finish(new Error(`authorization failed: ${reported}`));
+                return;
+            }
+            if (url.searchParams.get('state') !== state) {
+                // A stray or replayed redirect must not kill the real attempt.
+                response.writeHead(400, { 'content-type': 'text/plain' });
+                response.end('state mismatch');
+                return;
+            }
+            const code = url.searchParams.get('code');
+            if (code === null || code.length === 0) {
+                response.writeHead(400, { 'content-type': 'text/plain' });
+                response.end('missing authorization code');
+                return;
+            }
+            response.writeHead(200, { 'content-type': 'text/html' });
+            response.end(SUCCESS_PAGE);
+            const redirectUri = `http://${this.host}:${String(port)}${this.spec.callbackPath}`;
+            void this.spec.exchange({ code, redirectUri, pkce, state, signal: controller.signal })
+                .then((session) => { finish(undefined, session); })
+                .catch((error) => {
+                finish(error instanceof Error ? error : new Error(String(error)));
+            });
+        };
+        const bound = await listen(handler, this.host, this.spec.ports);
+        servers = bound.servers;
+        port = bound.port;
+        const redirectUri = `http://${this.host}:${String(port)}${this.spec.callbackPath}`;
+        timer = setTimeout(() => {
+            finish(new Error(`login timed out after ${String(Math.round(timeoutMs / 1000))}s`));
+        }, timeoutMs);
+        timer.unref?.();
+        const prompt = { url: this.spec.buildAuthorizeUrl({ redirectUri, state, pkce }), expiresAt: Date.now() + timeoutMs, mode: 'open-url' };
+        const attempt = {
+            prompt,
+            session,
+            cancel: () => { finish(new Error(LOGIN_CANCELLED_MESSAGE)); },
+        };
+        this.attempts.set(this.key, attempt);
+        return attempt;
+    }
+}