@n24q02m/hull 0.0.0-stage → 0.4.0-beta.10

package/build/auth/local-oauth-app.js

@@ -0,0 +1,975 @@
+/**
+ * Local OAuth 2.1 Authorization Server as an HTTP request handler.
+ *
+ * Provides a self-hosted Authorization Server for single-user MCP servers.
+ * Implements the OAuth 2.1 PKCE flow with credential collection via a
+ * browser-rendered form.
+ *
+ * Routes:
+ * - GET  /                                         -- Auto-bootstrap PKCE then redirect to /authorize
+ * - GET  /authorize                                -- Render credential form
+ * - POST /authorize                                -- Save credentials, return auth code
+ * - POST /otp                                      -- Submit multi-step credential (OTP / 2FA password)
+ * - POST /token                                    -- Exchange auth code + PKCE verifier for JWT
+ * - GET  /setup-status                             -- Poll background setup completion
+ * - GET  /callback-done                            -- Friendly "tab can be closed" page after PKCE callback
+ * - GET  /.well-known/oauth-authorization-server   -- RFC 8414 metadata
+ * - GET  /.well-known/oauth-protected-resource     -- RFC 9728 metadata
+ *
+ * The /mcp endpoint is NOT included -- it is mounted by the transport layer.
+ *
+ * This is a TypeScript port of core-py's ``local_oauth_app.py``. Behavior,
+ * protocol, and TTL constants are kept identical for cross-language parity.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { JWTIssuer } from '../oauth/jwt-issuer.js';
+import { markSetupComplete as markConfigSetupComplete } from '../storage/credential-store.js';
+import { isOAuthField, isSecretField, renderCredentialForm } from './credential-form.js';
+import { configureRelayLogin, createRelayLoginMiddleware, loginGetHandler, loginPostHandler } from './relay-login.js';
+import { createRouter, htmlResponse, jsonResponse, parseFormBody, parseJsonBody } from './router.js';
+import { deriveStableSub } from './stable-sub.js';
+import { authorizationServerMetadata, protectedResourceMetadata } from './well-known.js';
+// Auth codes and PKCE sessions expire after 10 minutes.
+const AUTH_CODE_TTL_S = 600;
+const SESSION_TTL_S = 600;
+// Multi-step auth (OTP / 2FA password) constraints.
+const OTP_TIMEOUT_S = 300;
+const OTP_MAX_ATTEMPTS = 5;
+/**
+ * Verify PKCE S256: ``base64url(sha256(code_verifier)) == code_challenge``,
+ * using a timing-safe comparison to prevent timing attacks.
+ */
+function s256Verify(codeVerifier, codeChallenge) {
+    const computed = createHash('sha256').update(codeVerifier, 'ascii').digest('base64url');
+    const computedBuf = Buffer.from(computed, 'ascii');
+    const challengeBuf = Buffer.from(codeChallenge, 'ascii');
+    const isLengthEqual = computedBuf.length === challengeBuf.length;
+    const compareBuf = isLengthEqual ? challengeBuf : computedBuf;
+    try {
+        return timingSafeEqual(computedBuf, compareBuf) && isLengthEqual;
+    }
+    catch {
+        return false;
+    }
+}
+/** Prune entries older than ``ttlMs`` milliseconds from an in-memory store. */
+function pruneExpired(store, ttlMs) {
+    const now = Date.now();
+    for (const [key, value] of store) {
+        if (now - value.createdAt > ttlMs)
+            store.delete(key);
+    }
+}
+/**
+ * Derive the public base URL of this request (protocol + host, no trailing slash).
+ *
+ * Resolution order:
+ * 1. ``PUBLIC_URL`` env var -- trusted, explicit. This is the remote-deploy
+ *    convention (oci-vm-prod) where the container sits behind CF Tunnel ->
+ *    Caddy (HTTP internal) but is served to clients over HTTPS. Without this,
+ *    OAuth 2.1 metadata would leak ``http://`` as the issuer and strict
+ *    clients reject the discovery document.
+ * 2. ``X-Forwarded-Proto`` header (first value) + Host header -- for reverse
+ *    proxies that forward the original scheme.
+ * 3. Socket ``encrypted`` flag -- TLS-terminated at this process.
+ * 4. ``http://<host>`` fallback -- plain local dev.
+ */
+function getBaseUrl(req) {
+    const publicUrl = process.env.PUBLIC_URL;
+    if (publicUrl !== undefined && publicUrl.length > 0) {
+        return publicUrl.replace(/\/+$/, '');
+    }
+    const host = req.headers.host ?? 'localhost';
+    const encrypted = req.socket.encrypted === true;
+    const forwardedProto = req.headers['x-forwarded-proto'];
+    let protocol = encrypted ? 'https' : 'http';
+    if (typeof forwardedProto === 'string' && forwardedProto.length > 0) {
+        const commaIdx = forwardedProto.indexOf(',');
+        protocol = (commaIdx !== -1 ? forwardedProto.substring(0, commaIdx) : forwardedProto).trim();
+    }
+    return `${protocol}://${host}`;
+}
+/**
+ * Create OAuth 2.1 Authorization Server HTTP handler.
+ *
+ * Returns a handler compatible with ``http.createServer`` along with the
+ * ``JWTIssuer`` (for the transport layer to verify Bearer tokens) and a
+ * ``markSetupComplete`` function for background setup callbacks (e.g. GDrive
+ * device code flow).
+ */
+export async function createLocalOAuthApp(options) {
+    const signingSecret = process.env.MCP_JWT_SIGNING_SECRET ?? process.env.CREDENTIAL_SECRET ?? null;
+    const jwtIssuer = options.jwtIssuer ?? new JWTIssuer(options.serverName, undefined, signingSecret);
+    await jwtIssuer.init();
+    // In-memory stores keyed by nonce / auth_code. Each entry has a ``createdAt``
+    // for TTL expiry.
+    const pendingSessions = new Map();
+    const authCodes = new Map();
+    // Server-side prefill keyed by OAuth ``state`` (the PKCE state token chosen
+    // by the client BEFORE the GET /authorize redirect). The E2E driver POSTs
+    // skret-derived form values here so the URL it announces to the user does
+    // NOT contain credential bytes. Without this, ``?prefill_TELEGRAM_PHONE=
+    // %2B84...`` would land in browser history, server access logs, screenshots
+    // and HTTP referrer headers — every place a URL leaks.
+    const pendingPrefills = new Map();
+    const PREFILL_TTL_S = 300;
+    // Single-user local mode: one pending multi-step session at a time.
+    let pendingStep = null;
+    const setupStatus = { gdrive: 'idle' };
+    // Edge auth password gate. When ``MCP_RELAY_PASSWORD`` is set, /authorize
+    // GET + POST + /authorize/prefill are fronted by a cookie-session
+    // middleware. Empty password disables the gate (single-user dev). See
+    // spec ``2026-05-01-stdio-pure-http-multiuser §4.2.1``. Configured here
+    // (not module-scope) so multi-app test setups don't leak state across
+    // apps; the relay-login module itself keeps a single shared password
+    // string, intentional because in deploy each container hosts one app.
+    const relayPassword = process.env.MCP_RELAY_PASSWORD ?? '';
+    configureRelayLogin(relayPassword);
+    const relayMw = createRelayLoginMiddleware({ password: relayPassword });
+    function markPendingStep(sub) {
+        pendingStep = { active: true, createdAt: Date.now(), attempts: 0, sub };
+    }
+    function clearPendingStep() {
+        pendingStep = null;
+    }
+    // ------------------------------------------------------------------
+    // Route handlers
+    // ------------------------------------------------------------------
+    async function authorizeGet(req, res) {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const params = url.searchParams;
+        const clientId = params.get('client_id');
+        const redirectUri = params.get('redirect_uri');
+        const state = params.get('state');
+        const codeChallenge = params.get('code_challenge');
+        const codeChallengeMethod = params.get('code_challenge_method') ?? 'S256';
+        if (!clientId || !redirectUri || !state || !codeChallenge) {
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Missing required parameters'
+            });
+            return;
+        }
+        // Resolve prefill values for the form. Two channels, in priority order:
+        //  1. Server-side store keyed by ``state`` — written by the E2E driver
+        //     via POST /authorize/prefill BEFORE the user opens the URL. This is
+        //     the safe channel; nothing leaves the server boundary.
+        //  2. URL query string ``?prefill_<KEY>=<VALUE>`` — legacy fallback for
+        //     callers that have not migrated yet. Deprecated; emitted to
+        //     ``X-Prefill-Source: url`` so callers can find them via access logs.
+        // Renderers receive the flat ``{KEY: VALUE}`` map and emit ``value="..."``
+        // on matching inputs.
+        const prefill = {};
+        pruneExpired(pendingPrefills, PREFILL_TTL_S * 1000);
+        const stored = pendingPrefills.get(state);
+        if (stored) {
+            // Explicit per-key copy (not Object.assign / spread) — values landed
+            // here via authorizePrefill which coerces every value through String()
+            // and rejects empty strings, but we restate the contract here so static
+            // analyzers don't flag the merge as a mass-assignment sink.
+            // nosemgrep: javascript.express.security.express-data-exfiltration.express-data-exfiltration
+            for (const [k, v] of Object.entries(stored.data)) {
+                prefill[k] = String(v);
+            }
+            pendingPrefills.delete(state);
+        }
+        else {
+            params.forEach((value, key) => {
+                if (key.startsWith('prefill_')) {
+                    prefill[key.slice('prefill_'.length)] = value;
+                }
+            });
+        }
+        const nonce = randomBytes(32).toString('base64url');
+        // Generate a per-authorize-request subject here (not at /token time) so the
+        // credential save callback and the eventual JWT share the same ``sub``. If
+        // this were derived at /token, concurrent authorize requests would collide
+        // on a static 'local-user' subject and leak credentials across users.
+        const sub = randomBytes(16).toString('base64url');
+        pendingSessions.set(nonce, {
+            clientId,
+            redirectUri,
+            state,
+            codeChallenge,
+            codeChallengeMethod,
+            createdAt: Date.now(),
+            sub
+        });
+        pruneExpired(pendingSessions, SESSION_TTL_S * 1000);
+        const base = getBaseUrl(req);
+        const submitUrl = `${base}/authorize?nonce=${nonce}`;
+        const html = options.customCredentialFormHtml !== undefined
+            ? options.customCredentialFormHtml(options.relaySchema, { submitUrl, prefill })
+            : renderCredentialForm(options.relaySchema, {
+                submitUrl,
+                prefill,
+                includeUsernameField: options.stableSubEnabled === true
+            });
+        htmlResponse(res, 200, html);
+    }
+    async function authorizePost(req, res) {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const nonce = url.searchParams.get('nonce');
+        if (!nonce || !pendingSessions.has(nonce)) {
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Invalid or expired nonce'
+            });
+            return;
+        }
+        const session = pendingSessions.get(nonce);
+        pendingSessions.delete(nonce);
+        if (Date.now() - session.createdAt > SESSION_TTL_S * 1000) {
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Session expired'
+            });
+            return;
+        }
+        let credentials;
+        try {
+            credentials = await parseJsonBody(req);
+        }
+        catch {
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Invalid JSON body'
+            });
+            return;
+        }
+        // Reserved partition key: remove it so it is never persisted as a provider
+        // credential. When stable-sub is enabled and a username was supplied,
+        // override the random per-authorize sub with a STABLE one derived from it
+        // (same username -> same per-sub bucket across re-auth and devices).
+        // Blank username or disabled flag -> keep the random sub (unchanged).
+        const submittedUsername = String(credentials.__sub_username ?? '').trim();
+        delete credentials.__sub_username;
+        if (options.stableSubEnabled === true && submittedUsername) {
+            session.sub = deriveStableSub(submittedUsername, options.serverName, process.env.CREDENTIAL_SECRET);
+        }
+        // Reset stale completion markers from previous authorize submits.
+        // setupStatus is module-scoped, so a key flipped to "complete" by a
+        // prior background poll (e.g. Outlook device code finished on the
+        // first attempt) would otherwise persist into the next form submit.
+        // The frontend renders a fresh oauth_device_code UI and starts
+        // polling /setup-status, which returns the stale "complete" within
+        // a few seconds and triggers a premature redirect — the user sees
+        // the device code flash on screen and then the "setup complete"
+        // banner before they ever open microsoft.com/link. Reset all keys
+        // back to "idle" here so each submit starts from a clean state.
+        for (const key of Object.keys(setupStatus)) {
+            setupStatus[key] = 'idle';
+        }
+        // Save credentials via callback. Callback may return a dict with
+        // next_step info (e.g. GDrive OAuth device code to show in the form).
+        // The per-authorize ``sub`` is threaded through so consumers persist
+        // credentials keyed by subject — subsequently the JWT issued at /token
+        // will carry this same sub, letting tool handlers load the correct
+        // credential set via AsyncLocalStorage.
+        let nextStep = null;
+        if (options.onCredentialsSaved !== undefined) {
+            try {
+                const result = await options.onCredentialsSaved(credentials, { sub: session.sub });
+                if (result !== null && result !== undefined && typeof result === 'object') {
+                    nextStep = result;
+                }
+            }
+            catch {
+                jsonResponse(res, 500, {
+                    error: 'server_error',
+                    error_description: 'Failed to save credentials'
+                });
+                return;
+            }
+        }
+        // Issue #682: a failing save callback must not yield an auth code. The
+        // response used to carry both ``redirect_url`` (with a usable code) and
+        // ``next_step: {type: 'error'}``, so a client reading only the redirect
+        // exchanged the code for a token bound to credentials that were never
+        // persisted. Short-circuit here, before the code is minted. Other
+        // next_step types are legitimate continuations of a successful save and
+        // keep the redirect.
+        if (nextStep !== null && nextStep.type === 'error') {
+            const errText = typeof nextStep.text === 'string' ? nextStep.text : 'credential save failed';
+            jsonResponse(res, 400, { ok: false, error: errText });
+            return;
+        }
+        // Mark the persistent ``_setup_complete`` flag once the user submits
+        // successfully. Multi-step flows (OTP / 2FA) defer marking until the
+        // final step in ``otpHandler`` — see core-py parity. Best-effort: any
+        // storage error is logged via warning rather than failing the response.
+        const isMultiStep = nextStep !== null && (nextStep.type === 'otp_required' || nextStep.type === 'password_required');
+        if (!isMultiStep) {
+            try {
+                await markConfigSetupComplete(options.serverName);
+            }
+            catch (err) {
+                console.warn('Failed to mark _setup_complete=true for %s: %s', options.serverName, err instanceof Error ? err.message : String(err));
+            }
+        }
+        // Generate auth code. Carry ``sub`` so /token can issue JWT with the
+        // same subject the credentials were saved under.
+        const authCode = randomBytes(32).toString('base64url');
+        authCodes.set(authCode, {
+            codeChallenge: session.codeChallenge,
+            codeChallengeMethod: session.codeChallengeMethod,
+            createdAt: Date.now(),
+            sub: session.sub
+        });
+        pruneExpired(authCodes, AUTH_CODE_TTL_S * 1000);
+        // RFC 9207 / SEP-2468: carry ``iss`` (this AS's issuer) in the
+        // authorization response so the client can verify the response came from
+        // the AS it started the flow with (mix-up defence).
+        const base = getBaseUrl(req);
+        const separator = session.redirectUri.includes('?') ? '&' : '?';
+        const redirectUrl = `${session.redirectUri}${separator}code=${authCode}&state=${session.state}` + `&iss=${encodeURIComponent(base)}`;
+        const body = { ok: true, redirect_url: redirectUrl };
+        if (nextStep !== null) {
+            body.next_step = nextStep;
+            // If next_step requires additional input (OTP or 2FA password),
+            // activate pending step session so /otp endpoint accepts input.
+            // Capture the authorize-session sub so /otp can thread the correct
+            // SubjectContext into onStepSubmitted (the browser POSTs to /otp
+            // with step data only — no sub in body).
+            const stepType = nextStep.type;
+            if (stepType === 'otp_required' || stepType === 'password_required') {
+                markPendingStep(session.sub);
+            }
+        }
+        jsonResponse(res, 200, body);
+    }
+    async function authorize(req, res) {
+        if (req.method === 'GET') {
+            await authorizeGet(req, res);
+            return;
+        }
+        await authorizePost(req, res);
+    }
+    async function authorizePrefill(req, res) {
+        // Driver-only side-channel: store form prefill values keyed by the OAuth
+        // ``state`` token chosen by the client. ``GET /authorize?state=<X>`` then
+        // hydrates the form on render — credentials never appear in the URL.
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const state = url.searchParams.get('state');
+        if (!state) {
+            jsonResponse(res, 400, { error: 'invalid_request', error_description: 'Missing state' });
+            return;
+        }
+        let body;
+        try {
+            body = await parseJsonBody(req);
+        }
+        catch {
+            jsonResponse(res, 400, { error: 'invalid_request', error_description: 'Body must be JSON object' });
+            return;
+        }
+        if (!body || typeof body !== 'object' || Array.isArray(body)) {
+            jsonResponse(res, 400, { error: 'invalid_request', error_description: 'Body must be JSON object' });
+            return;
+        }
+        // Coerce all values to string + drop empties so blank ``value=""`` attrs
+        // don't shadow the placeholder text in the rendered form.
+        const data = {};
+        for (const [k, v] of Object.entries(body)) {
+            if (v != null && String(v).length > 0) {
+                data[k] = String(v);
+            }
+        }
+        pendingPrefills.set(state, { data, createdAt: Date.now() });
+        pruneExpired(pendingPrefills, PREFILL_TTL_S * 1000);
+        jsonResponse(res, 204, {});
+    }
+    /**
+     * Build and write the standard /token success body for ``sub``.
+     *
+     * Issues a fresh access token AND a fresh refresh token. The refresh token
+     * lets long-running MCP clients renew the 1h access token without re-running
+     * the browser PKCE flow (issue #261). ``scope`` advertises ``offline_access``
+     * so clients know a refresh token was granted.
+     */
+    async function issueTokenResponse(res, sub) {
+        const accessToken = await jwtIssuer.issueAccessToken(sub);
+        const refreshToken = await jwtIssuer.issueRefreshToken(sub);
+        jsonResponse(res, 200, {
+            access_token: accessToken,
+            token_type: 'Bearer',
+            expires_in: 3600,
+            refresh_token: refreshToken,
+            scope: 'offline_access'
+        });
+    }
+    /**
+     * Handle ``grant_type=refresh_token`` (RFC 6749 §6) statelessly. Verifies the
+     * presented refresh token's signature / iss / aud / exp / ``typ`` via the JWT
+     * issuer (no server-side store), extracts ``sub``, and issues a NEW access
+     * token AND a NEW refresh token (rotation). The refresh token is
+     * self-contained, so rotation here is stateless: the old refresh token simply
+     * expires on its own 30-day clock; clients replace it with the rotated one.
+     */
+    async function handleRefreshToken(res, form) {
+        const refreshToken = form.refresh_token;
+        if (!refreshToken) {
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Missing refresh_token'
+            });
+            return;
+        }
+        let sub;
+        try {
+            const claims = await jwtIssuer.verifyRefreshToken(refreshToken);
+            sub = claims.sub;
+        }
+        catch {
+            jsonResponse(res, 400, { error: 'invalid_grant' });
+            return;
+        }
+        await issueTokenResponse(res, sub);
+    }
+    async function token(req, res) {
+        let form;
+        try {
+            form = await parseFormBody(req);
+        }
+        catch {
+            jsonResponse(res, 400, { error: 'invalid_request' });
+            return;
+        }
+        const grantType = form.grant_type;
+        if (grantType === 'refresh_token') {
+            await handleRefreshToken(res, form);
+            return;
+        }
+        if (grantType !== 'authorization_code') {
+            jsonResponse(res, 400, { error: 'unsupported_grant_type' });
+            return;
+        }
+        const code = form.code;
+        const codeVerifier = form.code_verifier;
+        if (!code || !codeVerifier) {
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Missing code or code_verifier'
+            });
+            return;
+        }
+        const entry = authCodes.get(code);
+        if (entry === undefined) {
+            jsonResponse(res, 400, { error: 'invalid_grant' });
+            return;
+        }
+        authCodes.delete(code);
+        if (Date.now() - entry.createdAt > AUTH_CODE_TTL_S * 1000) {
+            jsonResponse(res, 400, { error: 'invalid_grant' });
+            return;
+        }
+        if (entry.codeChallengeMethod !== 'S256') {
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Only S256 is supported'
+            });
+            return;
+        }
+        if (!s256Verify(codeVerifier, entry.codeChallenge)) {
+            jsonResponse(res, 400, { error: 'invalid_grant' });
+            return;
+        }
+        // Issue JWT with the subject bound to this authorize session. Historically
+        // this was the static string 'local-user' — that collapsed every concurrent
+        // browser into one subject and made credential isolation impossible. The
+        // new flow mints a fresh UUID in authorizeGet (PendingSession.sub), carries
+        // it through onCredentialsSaved, and issues it here so the Bearer returned
+        // to the client scopes future /mcp calls to this user's credentials.
+        await issueTokenResponse(res, entry.sub);
+    }
+    async function otpHandler(req, res) {
+        // 1. Active session check.
+        if (pendingStep === null || !pendingStep.active) {
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'No active step session'
+            });
+            return;
+        }
+        // 2. Timeout check.
+        if (Date.now() - pendingStep.createdAt > OTP_TIMEOUT_S * 1000) {
+            clearPendingStep();
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Step session expired'
+            });
+            return;
+        }
+        // 3. Parse JSON body BEFORE incrementing attempts. Malformed input
+        // must not consume the user's retry quota nor clear the session.
+        let stepData;
+        try {
+            stepData = await parseJsonBody(req);
+        }
+        catch {
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Invalid JSON body'
+            });
+            return;
+        }
+        // 4. Increment attempts counter (count every valid-JSON submit).
+        pendingStep.attempts += 1;
+        // 5. Attempt limit check.
+        if (pendingStep.attempts > OTP_MAX_ATTEMPTS) {
+            clearPendingStep();
+            jsonResponse(res, 400, {
+                error: 'invalid_request',
+                error_description: 'Too many attempts'
+            });
+            return;
+        }
+        // 6. Dispatch to step callback with the authorize-session sub so
+        // consumers (telegram Telethon multi-user) can route to the correct
+        // per-user state.
+        const stepContext = { sub: pendingStep.sub };
+        const stepSub = pendingStep.sub;
+        let nextStep = null;
+        if (options.onStepSubmitted !== undefined) {
+            try {
+                const result = await options.onStepSubmitted(stepData, stepContext);
+                if (result !== null && result !== undefined && typeof result === 'object') {
+                    nextStep = result;
+                }
+            }
+            catch {
+                jsonResponse(res, 500, {
+                    error: 'server_error',
+                    error_description: 'Failed to process step input'
+                });
+                return;
+            }
+        }
+        // Error from callback: keep pending session, allow retry.
+        if (nextStep !== null && nextStep.type === 'error') {
+            const errText = typeof nextStep.text === 'string' ? nextStep.text : 'Invalid input';
+            jsonResponse(res, 200, { ok: false, error: errText });
+            return;
+        }
+        // Chain to next step: reset counters so the new step gets its own quota.
+        // Preserve the original sub so the whole multi-step chain belongs to the
+        // same user.
+        if (nextStep !== null && (nextStep.type === 'otp_required' || nextStep.type === 'password_required')) {
+            markPendingStep(stepSub);
+            jsonResponse(res, 200, { ok: true, next_step: nextStep });
+            return;
+        }
+        // Completion (callback returned null / undefined or unknown dict type).
+        // Mark persistent _setup_complete flag now that the multi-step chain has
+        // finished — single-step counterpart lives in authorizePost.
+        try {
+            await markConfigSetupComplete(options.serverName);
+        }
+        catch (err) {
+            console.warn('Failed to mark _setup_complete=true for %s: %s', options.serverName, err instanceof Error ? err.message : String(err));
+        }
+        clearPendingStep();
+        jsonResponse(res, 200, { ok: true });
+    }
+    async function setupStatusHandler(_req, res) {
+        jsonResponse(res, 200, setupStatus);
+    }
+    async function wellKnownAs(req, res) {
+        const base = getBaseUrl(req);
+        jsonResponse(res, 200, authorizationServerMetadata(base));
+    }
+    async function wellKnownPr(req, res) {
+        const base = getBaseUrl(req);
+        jsonResponse(res, 200, protectedResourceMetadata(base, [base]));
+    }
+    async function wellKnownJwks(_req, res) {
+        jsonResponse(res, 200, await jwtIssuer.getJwks());
+    }
+    /**
+     * RFC 7591 Dynamic Client Registration.
+     *
+     * Local OAuth server uses a fixed public client id (`local-browser`).
+     * DCR is echo-style — mirror the client's submitted metadata back with
+     * the fixed id so MCP clients (Python SDK OAuthClientProvider, etc.)
+     * can bootstrap OAuth without failing at the registration step.
+     */
+    async function registerHandler(req, res) {
+        let body = {};
+        try {
+            const raw = await parseJsonBody(req);
+            body = raw;
+        }
+        catch {
+            // fall through with empty body
+        }
+        const redirectUris = Array.isArray(body.redirect_uris) ? body.redirect_uris : [];
+        const grantTypes = Array.isArray(body.grant_types) ? body.grant_types : ['authorization_code'];
+        const responseTypes = Array.isArray(body.response_types) ? body.response_types : ['code'];
+        const clientName = typeof body.client_name === 'string' ? body.client_name : 'mcp-client';
+        jsonResponse(res, 201, {
+            client_id: 'local-browser',
+            client_name: clientName,
+            redirect_uris: redirectUris,
+            grant_types: grantTypes,
+            response_types: responseTypes,
+            token_endpoint_auth_method: 'none'
+        });
+    }
+    function markSetupComplete(key = 'gdrive') {
+        setupStatus[key] = 'complete';
+    }
+    /**
+     * Mark a background setup step as failed. The status becomes
+     * ``"error:<message>"`` so the frontend poll handler can surface the
+     * message and stop spinning. Whitespace is collapsed to keep the value
+     * single-line (the frontend inlines it verbatim).
+     */
+    function markSetupFailed(key = 'gdrive', error = 'unknown error') {
+        // Replace multiple array allocations (.split.filter.join) with regex replace for faster whitespace collapsing
+        const collapsed = String(error).replace(/\s+/g, ' ').trim();
+        const message = collapsed.length > 0 ? collapsed : 'unknown error';
+        setupStatus[key] = `error:${message}`;
+    }
+    /**
+     * GET / -- auto-generate PKCE and redirect to /authorize.
+     *
+     * The ``/authorize`` endpoint requires 4 PKCE parameters; users arriving
+     * from a log line / bookmark have no way to construct them. Bootstrap a
+     * default ``local-browser`` client here: generate random state + S256
+     * challenge, redirect to ``/authorize``, and on success return to
+     * ``/callback-done`` for a friendly close message. Keeps the one-URL UX
+     * ("open http://... in browser") working without exposing the raw OAuth
+     * machinery to end users.
+     */
+    async function rootHandler(req, res) {
+        const base = getBaseUrl(req);
+        const codeVerifier = randomBytes(64).toString('base64url');
+        const codeChallenge = createHash('sha256').update(codeVerifier, 'ascii').digest('base64url');
+        const state = randomBytes(16).toString('base64url');
+        const params = new URLSearchParams({
+            client_id: 'local-browser',
+            redirect_uri: `${base}/callback-done`,
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256'
+        });
+        res.writeHead(302, { Location: `/authorize?${params.toString()}` });
+        res.end();
+    }
+    /**
+     * GET /callback-done -- terminal "tab can be closed" landing page.
+     *
+     * Users redirected from the bootstrap flow land here on success. Exists
+     * purely so the bare URL doesn't 404 after the PKCE redirect completes.
+     */
+    async function callbackDoneHandler(_req, res) {
+        const html = "<!DOCTYPE html><html><head><meta charset='utf-8'>" +
+            '<title>Setup complete</title>' +
+            '<style>body{font-family:-apple-system,Segoe UI,sans-serif;' +
+            'background:#111;color:#eee;display:flex;align-items:center;' +
+            'justify-content:center;height:100vh;margin:0}' +
+            '.box{text-align:center;padding:2rem;border:1px solid #333;' +
+            'border-radius:8px;background:#1a1a1a}' +
+            'h1{color:#34c759;margin:0 0 0.5rem}p{color:#aaa;margin:0}' +
+            '</style></head><body><div class="box">' +
+            '<h1>Setup complete</h1>' +
+            '<p>You can close this tab.</p>' +
+            '</div></body></html>';
+        htmlResponse(res, 200, html);
+    }
+    // ------------------------------------------------------------------
+    // Relay password gate adapters.
+    //
+    // The relay-login module exposes Express-style handlers (``req.body``,
+    // ``res.status().send()`` etc) so the same logic can be unit-tested
+    // without a live HTTP server. Here we adapt them onto the project's
+    // ``IncomingMessage`` / ``ServerResponse`` router. Each adapter:
+    //   1. Parses ``Cookie`` into ``req.cookies``,
+    //   2. Mounts ``res.status / res.send / res.cookie / res.redirect /
+    //      res.header / res.set`` on top of ``res.writeHead`` / ``res.end``,
+    //   3. Lets the relay-login handler do the work.
+    //
+    // Only ``/authorize`` GET + POST + ``/authorize/prefill`` go through
+    // ``relayMw``; ``/token``, ``/register``, ``/otp``, ``/setup-status``,
+    // ``/.well-known/*``, ``/`` and ``/callback-done`` are intentionally NOT
+    // gated — they're machine endpoints (DCR / token exchange / metadata) or
+    // auto-bootstrap helpers that must remain accessible without the cookie.
+    // ------------------------------------------------------------------
+    function parseCookies(req) {
+        const header = req.headers.cookie;
+        if (!header)
+            return {};
+        const out = {};
+        // Use a single-pass loop instead of `split(';')` to avoid array
+        // allocations and intermediate string objects in this hot path.
+        let pos = 0;
+        while (pos < header.length) {
+            let nextSemi = header.indexOf(';', pos);
+            if (nextSemi < 0)
+                nextSemi = header.length;
+            const eq = header.indexOf('=', pos);
+            if (eq >= 0 && eq < nextSemi) {
+                const k = header.substring(pos, eq).trim();
+                const v = header.substring(eq + 1, nextSemi).trim();
+                if (k.length > 0)
+                    out[k] = decodeURIComponent(v);
+            }
+            pos = nextSemi + 1;
+        }
+        return out;
+    }
+    function clientIp(req) {
+        const fwd = req.headers['x-forwarded-for'];
+        if (typeof fwd === 'string' && fwd.length > 0) {
+            const idx = fwd.indexOf(',');
+            return (idx !== -1 ? fwd.substring(0, idx) : fwd).trim();
+        }
+        return req.socket.remoteAddress ?? 'unknown';
+    }
+    function buildResAdapter(res) {
+        let statusCode = 200;
+        const headers = {};
+        let completed = false;
+        const setHeader = (name, value) => {
+            headers[name] = value;
+        };
+        const adapter = {
+            status: (code) => {
+                statusCode = Number(code);
+                return adapter;
+            },
+            header: (name, value) => {
+                setHeader(String(name), String(value));
+                return adapter;
+            },
+            set: (name, value) => {
+                setHeader(String(name), String(value));
+                return adapter;
+            },
+            cookie: (name, value, options) => {
+                const opts = (options ?? {});
+                const parts = [`${String(name)}=${String(value)}`];
+                if (opts.maxAge !== undefined) {
+                    parts.push(`Max-Age=${Math.floor(Number(opts.maxAge) / 1000)}`);
+                }
+                if (opts.httpOnly === true)
+                    parts.push('HttpOnly');
+                if (opts.secure === true)
+                    parts.push('Secure');
+                if (typeof opts.sameSite === 'string') {
+                    // Capitalise SameSite values (lax → Lax, strict → Strict).
+                    const v = opts.sameSite;
+                    parts.push(`SameSite=${v.charAt(0).toUpperCase() + v.slice(1)}`);
+                }
+                parts.push('Path=/');
+                const existing = headers['Set-Cookie'];
+                const next = parts.join('; ');
+                headers['Set-Cookie'] = existing !== undefined ? `${existing}, ${next}` : next;
+                return adapter;
+            },
+            send: (body) => {
+                if (completed)
+                    return adapter;
+                completed = true;
+                if (!('Content-Type' in headers)) {
+                    headers['Content-Type'] = 'text/html; charset=utf-8';
+                }
+                // Anti-clickjacking for HTML responses
+                const ctype = headers['Content-Type'];
+                if (ctype && ctype.toLowerCase().includes('text/html')) {
+                    headers['X-Frame-Options'] = 'DENY';
+                }
+                res.writeHead(statusCode, headers);
+                res.end(body === undefined ? '' : String(body));
+                return adapter;
+            },
+            redirect: (url) => {
+                if (completed)
+                    return adapter;
+                completed = true;
+                headers.Location = String(url);
+                res.writeHead(302, headers);
+                res.end();
+                return adapter;
+            }
+        };
+        return { adapter, isComplete: () => completed };
+    }
+    /**
+     * Wrap a router handler with the relay-login middleware. If the cookie
+     * gate redirects, the inner handler is never called; otherwise the inner
+     * handler runs against the original ``req`` / ``res``.
+     */
+    function withRelayGate(inner) {
+        return async (req, res) => {
+            if (!relayPassword) {
+                await inner(req, res);
+                return;
+            }
+            const cookies = parseCookies(req);
+            const expressReq = {
+                cookies,
+                originalUrl: req.url ?? '/'
+            };
+            const { adapter, isComplete } = buildResAdapter(res);
+            let proceed = false;
+            await relayMw(expressReq, adapter, () => {
+                proceed = true;
+            });
+            if (proceed && !isComplete()) {
+                await inner(req, res);
+            }
+        };
+    }
+    /**
+     * Adapter: bind ``loginGetHandler`` / ``loginPostHandler`` (Express-style)
+     * onto IncomingMessage / ServerResponse routes.
+     */
+    async function loginGetRoute(req, res) {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const expressReq = { query: { next: url.searchParams.get('next') ?? '/authorize' } };
+        const { adapter } = buildResAdapter(res);
+        await loginGetHandler(expressReq, adapter);
+    }
+    async function loginPostRoute(req, res) {
+        let body = {};
+        try {
+            body = await parseFormBody(req);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'invalid_request' }));
+            return;
+        }
+        const expressReq = { body, ip: clientIp(req) };
+        const { adapter } = buildResAdapter(res);
+        await loginPostHandler(expressReq, adapter);
+    }
+    const handler = createRouter([
+        { method: 'GET', path: '/', handler: rootHandler },
+        { method: 'GET', path: '/login', handler: loginGetRoute },
+        { method: 'POST', path: '/login', handler: loginPostRoute },
+        { method: 'GET', path: '/authorize', handler: withRelayGate(authorize) },
+        { method: 'POST', path: '/authorize', handler: withRelayGate(authorize) },
+        { method: 'POST', path: '/authorize/prefill', handler: withRelayGate(authorizePrefill) },
+        { method: 'POST', path: '/token', handler: token },
+        { method: 'POST', path: '/register', handler: registerHandler },
+        { method: 'POST', path: '/otp', handler: otpHandler },
+        { method: 'GET', path: '/setup-status', handler: setupStatusHandler },
+        { method: 'GET', path: '/callback-done', handler: callbackDoneHandler },
+        { method: 'GET', path: '/.well-known/oauth-authorization-server', handler: wellKnownAs },
+        { method: 'GET', path: '/.well-known/oauth-protected-resource', handler: wellKnownPr },
+        { method: 'GET', path: '/.well-known/jwks.json', handler: wellKnownJwks }
+    ]);
+    return { handler, jwtIssuer, markSetupComplete, markSetupFailed };
+}
+// ---------------------------------------------------------------------------
+// D7 — Pre-fill renderer + form-submission merger.
+//
+// These helpers mirror the core-py exports of the same names. They are
+// intentionally NOT wired into the default ``authorizeGet`` / ``authorizePost``
+// above — that path stays on ``renderCredentialForm`` for legacy parity. New
+// consumers (transparent-bridge Wave 1) compose ``renderField`` per field for
+// secret-aware rendering, then call ``mergeSubmission`` to merge the POST body
+// with their stored ``config.enc`` so a missing secret in the body preserves
+// the previously stored value instead of clearing it.
+// ---------------------------------------------------------------------------
+const SECRET_PLACEHOLDER = '••••••••(configured)';
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Resolve the canonical config key for a relay field.
+ *
+ * Two schema styles coexist in the codebase: D7 ``RelayConfigField`` uses
+ * ``name``; legacy ``ConfigField`` (consumed by ``renderCredentialForm``)
+ * uses ``key``. ``renderField`` and ``mergeSubmission`` accept both so a
+ * consumer can mix or migrate without rewriting field dicts. ``name`` wins
+ * when both are present.
+ */
+function fieldName(field) {
+    const raw = field;
+    const name = typeof raw.name === 'string' ? raw.name : '';
+    if (name.length > 0)
+        return name;
+    const key = typeof raw.key === 'string' ? raw.key : '';
+    return key;
+}
+/**
+ * Render an HTML ``<label>+<input>`` for a single relay field.
+ *
+ * Rules per D7:
+ *  - oauth_field: render Re-authorize button (no plaintext exposed)
+ *  - secret + value present: placeholder, empty input, "Replace" checkbox
+ *  - secret + no value: empty input with field label as placeholder
+ *  - non-secret: pre-fill with ``currentValue`` as input ``value`` attr
+ */
+export function renderField(field, currentValue) {
+    const name = fieldName(field);
+    const label = field.label ?? name;
+    const fieldType = field.type ?? 'text';
+    if (isOAuthField(field)) {
+        const status = currentValue ? 'Connected' : 'Not connected';
+        return (`<div class="field oauth-field"><label>${escapeHtml(label)}</label> ` +
+            `<span class="oauth-status">${status}</span> ` +
+            `<button type="button" class="oauth-reauth" data-field="${escapeHtml(name)}" aria-label="Re-authorize ${escapeHtml(label)}">` +
+            `Re-authorize</button></div>`);
+    }
+    if (isSecretField(field)) {
+        if (currentValue) {
+            return (`<div class="field secret-field"><label for="field-${escapeHtml(name)}">${escapeHtml(label)}</label> ` +
+                `<input id="field-${escapeHtml(name)}" type="password" name="${escapeHtml(name)}" value="" ` +
+                `placeholder="${escapeHtml(SECRET_PLACEHOLDER)}" ` +
+                `data-secret-configured="true"> ` +
+                `<label for="replace-${escapeHtml(name)}" class="replace-toggle"><input id="replace-${escapeHtml(name)}" type="checkbox" ` +
+                `name="__replace_${escapeHtml(name)}" value="1"> Replace this credential</label>` +
+                `</div>`);
+        }
+        return (`<div class="field secret-field"><label for="field-${escapeHtml(name)}">${escapeHtml(label)}</label> ` +
+            `<input id="field-${escapeHtml(name)}" type="password" name="${escapeHtml(name)}" value="" ` +
+            `placeholder="${escapeHtml(label)}"></div>`);
+    }
+    const valueAttr = currentValue !== null && currentValue !== undefined ? escapeHtml(String(currentValue)) : '';
+    return (`<div class="field"><label for="field-${escapeHtml(name)}">${escapeHtml(label)}</label> ` +
+        `<input id="field-${escapeHtml(name)}" type="${escapeHtml(fieldType)}" name="${escapeHtml(name)}" ` +
+        `value="${valueAttr}"></div>`);
+}
+/**
+ * Merge a form submission into the current config per D7 rules.
+ *
+ * Behavior:
+ *  - Empty secret -> preserve the existing value (avoid clearing on a
+ *    re-submit where the user did not retype the credential).
+ *  - Non-empty secret -> replace.
+ *  - Non-secret -> always replace (including with an empty string, so the
+ *    user can intentionally blank a field).
+ *  - oauth_field -> ignored here; OAuth fields are managed by their own
+ *    Re-authorize flow, never by raw form input.
+ */
+export function mergeSubmission(current, submitted, schemaFields) {
+    const result = { ...current };
+    for (const field of schemaFields) {
+        const name = fieldName(field);
+        if (!name)
+            continue;
+        if (isOAuthField(field))
+            continue;
+        const newValue = submitted[name] ?? '';
+        if (isSecretField(field)) {
+            if (newValue === '' || newValue === null || newValue === undefined) {
+                continue;
+            }
+            result[name] = newValue;
+        }
+        else {
+            result[name] = newValue;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=local-oauth-app.js.map