trackqa 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# TrackQA Universal Connector — Windows MVP release candidate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect an existing AI coding client to TrackQA's remote MCP server without copying
+bearer tokens or editing MCP configuration manually. Codex CLI is the MVP-supported
+candidate. Setup is Owner-operated, with explicit project approval and session-based
+credentials. The connector does not install or authenticate the AI client itself.
+
+## Package status and installation
+
+**trackqa@0.1.0** was published and independently verified on November 4, 2026.
+The locally prepared **v0.1.1 candidate** removes manual public-key setup for the
+official hosted TrackQA service. **v0.1.1 is not published; publication requires
+separate approval.** The original v0.1.0 artifact is retained unchanged.
+
+To verify an approved local tarball in a disposable directory:
+
+```powershell
+npm install --ignore-scripts --no-audit --no-fund <absolute-path-to-trackqa-0.1.1.tgz>
+npm exec --offline -- trackqa --help
+```
+
+After v0.1.1 is approved and published, the official hosted workflow is:
+
+```powershell
+npx trackqa connect
+# Explicit client selection is also supported:
+npx trackqa connect --client codex
+npx trackqa status --client codex
+npx trackqa disconnect --client codex --project <project-UUID>
+```
+
+Until v0.1.1 is published, the bare registry command still resolves to v0.1.0 and
+retains that version's manual public-key requirement. Validate this candidate
+through a local tarball installation and `npm exec --offline -- trackqa ...`.
+Bare `connect` prompts for a client; `--client codex` is optional. No client is
+selected by default.
+
+## Requirements and first use
+
+- Windows, Node.js **22.19 or newer**, npm and an interactive terminal.
+- An independently installed, compatible Codex CLI and its own account access.
+  The connector never installs, upgrades or signs into an AI client automatically.
+- A TrackQA account with a profile and **OWNER** membership in the selected project.
+  Google PKCE sign-in is interactive in the system browser. Accounts with verified
+  MFA factors are currently refused as unsupported.
+- Free callback port **5173** on localhost. Stop a conflicting development server
+  through its own terminal before setup; the connector never terminates it.
+- Official hosted TrackQA's validated **public anon key is included**. No manual
+  `TRACKQA_PUBLIC_KEY` setup, application checkout or `.env` file is required.
+
+```powershell
+npm exec --offline -- trackqa connect --client codex
+```
+
+The installed package uses its included shared runtime helpers; it does not need
+the application checkout or its environment files. Source-checkout fallback to the
+app's public-key setting is development-only. No `.env` file is packaged or created.
+
+### Advanced: custom public configuration
+
+The connector continues to pin its backend URL. A custom deployment uses a custom
+build pinned to its own backend, with a matching public key supplied through
+`TRACKQA_PUBLIC_KEY` or, alternatively, `VITE_SUPABASE_ANON_KEY`. A key override
+alone does not change the destination. No runtime URL override was added.
+
+```powershell
+$env:TRACKQA_PUBLIC_KEY = '<matching-deployment-public-anon-or-publishable-key>'
+```
+
+Explicit environment values take precedence over the development-file fallback
+and official default. Invalid explicit values fail closed. Legacy anon JWTs with
+a different project reference are rejected; opaque publishable keys cannot be
+associated with a deployment offline and must be validated by that backend.
+The official default is never used for a different pinned deployment. Never use
+a secret/service-role key, database password, Owner session or MCP bearer token.
+
+Select one client and one project, inspect the token-free preview, and approve
+installation, project MCP enablement if needed, and one scoped connection. The
+connector launches the client with the credential only in the child environment.
+TrackQA Owner sign-in and any Codex/GitHub/Google/Claude AI-account sign-in are
+separate. Normal interactive tool approvals remain in effect.
+
+## Support and validation limits
+
+| Client | Status |
+| --- | --- |
+| Codex CLI | **MVP-supported candidate**, Windows and Owner-operated. Hosted initialization, five tools, scoped reads, foreground launch, revocation and cleanup passed. |
+| VS Code Local (`vscode`) | **Experimental**. Windows hosted read-only acceptance passed. Manual MCP activation and same-session model access are required. |
+| VS Code Copilot (`vscode-copilot`) | **Experimental and guarded**. Hosted read-only acceptance passed through the separate fixture-pinned test entry. Ordinary `connect` still stops before Owner authentication, issuance or launch. |
+| Gemini CLI | **Experimental; hosted validation deferred**. Local/native configuration checks passed; native Google authentication remains blocked. |
+| Claude Code | **Experimental; hosted validation deferred**. Native installation/configuration flags checked; test-account eligibility blocked authenticated acceptance. |
+| Antigravity | **Deferred**; no adapter. Safe isolation remains unverified. |
+
+VS Code detection currently supports Windows stable 1.143.x. Other platforms,
+portable/forked clients, additional providers and parallel multi-client sessions
+are outside this MVP. Use `trackqa --help` for supported executable-path flags.
+Claims about a client apply only to the validated scope above.
+
+On **November 4, 2026**, the isolated Copilot run against MCP Synthetic Pilot reached
+Running, discovered five tools and successfully called `trackqa_connection_status`,
+`trackqa_list_projects`, `trackqa_list_issues` and `trackqa_get_issue` once each. Four
+native Search Tools operations were permitted; no unrelated application tools,
+delegated agents or `trackqa_submit_finding` invocation were recorded. Project
+isolation, revocation, fixture restoration, unchanged inventories and owned MCP
+configuration removal were verified. The credential-pattern scan covered 166 files
+with zero matches or exclusions.
+
+Write-tool execution, authentication persistence, normal editor exit and complete
+detached Agent Host/SDK termination remain unvalidated. The status response reported
+`read_only=false` and `issue_writes_allowed=false`: the acceptance procedure used
+only reads; the existing token's finding capability was not removed. Findings still
+follow TrackQA's existing human QA review workflow. Ordinary Copilot activation is
+not enabled by these results. Hosted acceptance scripts are not shipped.
+
+## Credentials, disconnect and recovery
+
+Owner PKCE/session credentials remain in memory and local sign-out is attempted on
+exit. MCP tokens are never placed in arguments, configuration, logs or recovery
+records. Configuration contains only the literal environment reference. Other
+trusted processes on the same OS account may inspect a child's environment.
+
+**The existing 90-day token expiry is unchanged.** This is session-based delivery,
+not a short-lived token guarantee. Normal exit, handled interruption or explicit
+Disconnect attempts revocation and independently checks the server record. A hard
+kill, power loss or network failure can prevent cleanup; local configuration removal
+alone does not revoke access.
+
+Recovery metadata is stored in `%LOCALAPPDATA%\TrackQA-Connect`, outside the checkout.
+After an interrupted session:
+
+```powershell
+npm exec --offline -- trackqa status --client codex
+npm exec --offline -- trackqa disconnect --client codex --project <project-UUID>
+```
+
+`status` is local-only and does not prove authorization or connectivity. Disconnect
+may require fresh Google Owner sign-in. Failed or uncertain issuance/revocation
+retains actionable recovery metadata; do not bypass it or issue another connection
+automatically. An Owner can also revoke the labeled connection in TrackQA's existing
+AI Integrations → Manage Connections controls.
+
+Only unchanged connector-owned configuration is removed. Edited entries and
+unexpected files are preserved. Remove a stale `connector.lock` only after confirming
+its recorded process has exited. Do not delete pending recovery evidence.
+
+Normal session cleanup does **not** silently disable project-wide MCP or revoke
+other users' connections. Any project enablement is persistent and explicitly
+approved. Synthetic acceptance restoration was a separate, authorized Owner action.
+
+## Package contents and source development
+
+The artifact contains this README, package metadata and the exact compiled runtime
+dependency closure. It includes the existing PKCE/shared MCP helper and the internal
+acceptance-capability guard required by authentication/workflow imports. That guard
+is not an acceptance runner or a synthetic server. Its behavior is unchanged.
+
+Source, tests, hosted/synthetic runners, fixture servers, development tooling,
+obsolete WMI supervision modules, environment files and runtime profiles are excluded.
+No install scripts run on consumers. The declared runtime dependency is
+`@supabase/supabase-js@2.113.0`; build tooling stays in the source checkout.
+
+Source developers use the repository's existing dependencies:
+
+```powershell
+npm --prefix tools/trackqa-connect run check
+npm --prefix tools/trackqa-connect run lint
+npm --prefix tools/trackqa-connect run build
+npm --prefix tools/trackqa-connect test
+```
+
+Build clears only the verified owned `dist` directory, compiles the CLI and shared
+dependencies, and checks the exact runtime allowlist. `prepack` repeats that clean
+build when packing from the source checkout. Preserve generated tarballs/checksums
+under the ignored `artifacts/` directory. Historical implementation and supervised
+acceptance procedures remain in source-only `DEVELOPMENT.md`; no new hosted run or
+publication is authorized by this documentation.

package/dist/src/lib/mcpOnboarding.js

@@ -0,0 +1,143 @@
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export const connectionFields = 'id,project_id,user_id,approved_by,client_label,token_expires_at,created_at,updated_at,revoked_at';
+export const mcpTools = [
+    { name: 'trackqa_connection_status', description: 'Check the authorized connection and project.' },
+    { name: 'trackqa_list_projects', description: 'Show the single approved project.' },
+    { name: 'trackqa_list_issues', description: 'List issues in that project.' },
+    { name: 'trackqa_get_issue', description: 'Read an issue in that project.' },
+    { name: 'trackqa_submit_finding', description: 'Submit a potential bug for human QA/Owner review.' },
+];
+export const clientDocs = {
+    codex: 'https://developers.openai.com/codex/mcp/',
+    claude: 'https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcpjson',
+};
+// These builders never accept a token. UUID-derived identifiers avoid project
+// name/key injection and keep credentials for different projects independent.
+export function mcpSetup(supabaseUrl, projectId) {
+    let url;
+    try {
+        url = new URL(supabaseUrl);
+    }
+    catch {
+        throw new Error('MCP endpoint configuration is unavailable.');
+    }
+    if (url.protocol !== 'https:' || url.username || url.password || url.pathname !== '/'
+        || url.search || url.hash || url.port || !uuid.test(projectId)) {
+        throw new Error('MCP endpoint configuration is unavailable.');
+    }
+    const id = projectId.replaceAll('-', '').toLowerCase();
+    return { endpoint: `${url.origin}/functions/v1/trackqa-mcp`, serverName: `trackqa_${id}`,
+        envVar: `TRACKQA_MCP_${id.toUpperCase()}_TOKEN`, projectId: projectId.toLowerCase() };
+}
+function verifySetup(setup) {
+    try {
+        const expected = mcpSetup(new URL(setup.endpoint).origin, setup.projectId);
+        if (setup.endpoint === expected.endpoint && setup.serverName === expected.serverName && setup.envVar === expected.envVar)
+            return;
+    }
+    catch { /* Return only a fixed configuration error. */ }
+    throw new Error('Client setup is unavailable.');
+}
+export function clientConfig(setup, client) {
+    verifySetup(setup);
+    if (!['codex', 'claude', 'generic'].includes(client))
+        throw new Error('Client setup is unavailable.');
+    if (client === 'generic')
+        return null; // There is no universal client config schema.
+    if (client === 'claude')
+        return JSON.stringify({ mcpServers: { [setup.serverName]: {
+                    type: 'http', url: setup.endpoint, headers: { Authorization: 'Bearer ${' + setup.envVar + '}' },
+                } } }, null, 2);
+    return `[mcp_servers.${setup.serverName}]\nurl = ${JSON.stringify(setup.endpoint)}\nbearer_token_env_var = ${JSON.stringify(setup.envVar)}\nenabled_tools = [${mcpTools.map(tool => JSON.stringify(tool.name)).join(', ')}]`;
+}
+export function clientLaunch(setup, client, terminal) {
+    verifySetup(setup);
+    // Only fixed executable names and validated variable identifiers enter code.
+    if (!/^TRACKQA_MCP_[0-9A-F]{32}_TOKEN$/.test(setup.envVar)
+        || !['codex', 'claude'].includes(client) || !['powershell', 'bash'].includes(terminal)) {
+        throw new Error('Client setup is unavailable.');
+    }
+    const variable = setup.envVar;
+    if (terminal === 'bash')
+        return `(
+  set +x
+  trap 'unset ${variable}' EXIT
+  if ! read -r -s -p 'TrackQA token (hidden): ' ${variable}; then exit 1; fi
+  printf '\\n'
+  if [[ ! "$${variable}" =~ ^tqm_[0-9a-f]{64}$ ]]; then printf 'Invalid TrackQA token format.\\n' >&2; exit 1; fi
+  export ${variable}
+  ${client}
+)`;
+    return `& {
+  $ErrorActionPreference = 'Stop'
+  $secureToken = Read-Host 'TrackQA token (hidden)' -AsSecureString
+  $tokenPointer = [IntPtr]::Zero
+  try {
+    $tokenPointer = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureToken)
+    $env:${variable} = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($tokenPointer)
+    if ($env:${variable} -notmatch '^tqm_[0-9a-f]{64}$') { throw 'Invalid TrackQA token format.' }
+    ${client}
+  } finally {
+    Remove-Item Env:${variable} -ErrorAction SilentlyContinue
+    if ($tokenPointer -ne [IntPtr]::Zero) { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($tokenPointer) }
+    $secureToken.Dispose()
+  }
+}`;
+}
+export function connectionStatus(connection, enabled, archived, memberPresent, now) {
+    if (connection.revoked_at)
+        return 'Revoked';
+    const expires = Date.parse(connection.token_expires_at);
+    if (!Number.isFinite(expires) || expires <= now)
+        return 'Expired';
+    if (!connection.user_id || !connection.approved_by || !memberPresent)
+        return 'Unavailable';
+    if (archived)
+        return 'Project archived';
+    if (!enabled)
+        return 'Project disabled';
+    return 'Ready to connect';
+}
+export function watchTokenReveal(clear, documentTarget, windowTarget) {
+    const hide = () => { if (documentTarget.hidden)
+        clear(); };
+    const timer = windowTarget.setTimeout(clear, 120_000);
+    documentTarget.addEventListener('visibilitychange', hide);
+    windowTarget.addEventListener('pagehide', clear);
+    return () => {
+        windowTarget.clearTimeout(timer);
+        documentTarget.removeEventListener('visibilitychange', hide);
+        windowTarget.removeEventListener('pagehide', clear);
+    };
+}
+const issuanceError = () => new Error('Token issuance could not be completed. Refresh connections and revoke any new entry before trying again.');
+// The existing human-authenticated RPC remains authoritative. No retry, cache,
+// persistence, diagnostics, or token-bearing return value is introduced here.
+export async function issueConnectionToken(call, scope, label, reveal) {
+    let rows = null;
+    try {
+        if (!scope.isOwner || !scope.enabled || scope.archived || !uuid.test(scope.projectId)
+            || !uuid.test(scope.userId) || !scope.memberIds.includes(scope.userId)
+            || !label.trim() || label.trim().length > 120)
+            throw issuanceError();
+        const result = await call({ p_project_id: scope.projectId, p_user_id: scope.userId, p_client_label: label.trim() });
+        rows = result.data;
+        if (result.error || !Array.isArray(rows) || rows.length !== 1 || !uuid.test(rows[0]?.connection_id)
+            || !/^tqm_[0-9a-f]{64}$/.test(rows[0]?.access_token))
+            throw issuanceError();
+        const connectionId = rows[0].connection_id;
+        const displayed = reveal({ connectionId, token: rows[0].access_token });
+        return { connectionId, displayed };
+    }
+    catch {
+        throw issuanceError();
+    }
+    finally {
+        // Discard the SDK response's one-time secret after handing it to the local
+        // reveal dialog. It must never enter connection metadata or a query cache.
+        if (Array.isArray(rows))
+            for (const row of rows)
+                if (row && typeof row === 'object')
+                    row.access_token = '';
+    }
+}

package/dist/tools/mcp-pilot/google-pkce.mjs

@@ -0,0 +1,244 @@
+import { createServer } from 'node:http';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+export const GOOGLE_REDIRECT = 'http://localhost:5173/mcp-pilot/callback';
+export const GOOGLE_CODES = Object.freeze(['callback_port_in_use', 'callback_unavailable',
+    'callback_timeout', 'callback_rejected', 'oauth_denied', 'oauth_failed',
+    'browser_open_failed', 'interrupted']);
+const HOST = 'localhost:5173';
+const CALLBACK = '/mcp-pilot/callback';
+const COOKIE = 'trackqa_mcp_pilot_flow';
+const START = '/mcp-pilot/start';
+export class GooglePkceError extends Error {
+    constructor(code) {
+        super('Google authorization did not complete.');
+        this.code = GOOGLE_CODES.includes(code) ? code : 'oauth_failed';
+    }
+}
+const failure = code => new GooglePkceError(code);
+// Only this local, one-time bootstrap URL reaches the default browser launcher.
+// It contains no authorization code, access/refresh token or PKCE verifier.
+export function openSystemBrowser(url) {
+    const u = new URL(url);
+    if (process.platform !== 'win32' || u.origin !== 'http://' + HOST || u.pathname !== START
+        || !/^[0-9a-f]{64}$/.test(u.searchParams.get('nonce') ?? ''))
+        throw failure('browser_open_failed');
+    return new Promise((resolve, reject) => {
+        execFile(path.join(process.env.SystemRoot ?? 'C:/Windows', 'System32/rundll32.exe'), ['url.dll,FileProtocolHandler', u.href], { windowsHide: true, timeout: 5000, maxBuffer: 1024 }, error => error ? reject(failure('browser_open_failed')) : resolve());
+    });
+}
+// No request logger. Two fixed loopback bindings prevent localhost resolving to
+// a different application's IPv4/IPv6 listener. Never use 0.0.0.0 or :: here.
+export async function createGoogleCallback({ timeoutMs = 300_000, signal, serverFactory = createServer } = {}) {
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000)
+        throw failure('callback_unavailable');
+    const nonce = randomBytes(32).toString('hex');
+    const servers = [];
+    let authorizationUrl;
+    let flowId;
+    let started = false;
+    let settled = false;
+    let closed = false;
+    let timer;
+    let resolveCode, rejectCode;
+    const code = new Promise((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
+    // A failure can occur while opening the browser, before the caller awaits it.
+    void code.catch(() => { });
+    function finish(error, value) {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        error ? rejectCode(error) : resolveCode(value);
+    }
+    const abort = () => finish(failure('interrupted'));
+    async function close() {
+        if (closed)
+            return;
+        closed = true;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+        if (!settled)
+            finish(failure('interrupted'));
+        await Promise.all(servers.map(server => new Promise(resolve => {
+            const force = setTimeout(() => server.closeAllConnections?.(), 250);
+            try {
+                server.close(() => { clearTimeout(force); resolve(); });
+                server.closeIdleConnections?.();
+            }
+            catch {
+                clearTimeout(force);
+                resolve();
+            }
+        })));
+        authorizationUrl = undefined;
+        flowId = undefined;
+    }
+    function respond(response, status, message, extra = {}) {
+        response.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8',
+            'Cache-Control': 'no-store', 'Pragma': 'no-cache', 'Referrer-Policy': 'no-referrer',
+            'Content-Security-Policy': "default-src 'none'; frame-ancestors 'none'", Connection: 'close', ...extra });
+        response.end(message);
+    }
+    const clearCookie = `${COOKIE}=; Path=${CALLBACK}; HttpOnly; SameSite=Lax; Max-Age=0`;
+    function handler(request, response) {
+        try {
+            const remote = request.socket.remoteAddress;
+            if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(remote)
+                || request.headers.host !== HOST || (request.headers.origin && request.headers.origin !== 'http://' + HOST)) {
+                respond(response, 403, 'Request rejected.');
+                return;
+            }
+            if (request.method !== 'GET') {
+                respond(response, 405, 'Request rejected.');
+                return;
+            }
+            const raw = request.url ?? '';
+            if (!raw.startsWith('/') || raw.startsWith('//') || raw.length > 8192) {
+                respond(response, 400, 'Request rejected.');
+                return;
+            }
+            if (![START, CALLBACK].includes(raw.split('?')[0])) {
+                respond(response, 404, 'Not found.');
+                return;
+            }
+            const url = new URL(raw, 'http://' + HOST);
+            if (url.hash) {
+                respond(response, 400, 'Request rejected.');
+                return;
+            }
+            if (url.pathname === START) {
+                if (settled || started || !authorizationUrl || url.searchParams.getAll('nonce').length !== 1
+                    || url.searchParams.get('nonce') !== nonce || [...url.searchParams.keys()].some(k => k !== 'nonce')) {
+                    respond(response, 403, 'Request rejected.');
+                    return;
+                }
+                started = true;
+                // Session cookie: no OAuth credentials and no persistent expiry. It is
+                // only a browser-to-attempt correlation value for this loopback origin.
+                respond(response, 302, 'Continue authorization in the browser.', {
+                    Location: authorizationUrl,
+                    'Set-Cookie': `${COOKIE}=${nonce}; Path=${CALLBACK}; HttpOnly; SameSite=Lax`,
+                });
+                return;
+            }
+            if (url.pathname !== CALLBACK) {
+                respond(response, 404, 'Not found.');
+                return;
+            }
+            if (settled) {
+                respond(response, 410, 'Authorization response already handled.');
+                return;
+            }
+            const cookies = String(request.headers.cookie ?? '').split(';').map(v => v.trim())
+                .filter(v => v.startsWith(COOKIE + '=')).map(v => v.slice(COOKIE.length + 1));
+            const matched = cookies.length === 1 && /^[0-9a-f]{64}$/.test(cookies[0])
+                && timingSafeEqual(Buffer.from(cookies[0]), Buffer.from(nonce));
+            const returnedFlow = url.searchParams.getAll('sb_flow_id');
+            if (!started || !matched || returnedFlow.length > 1 || (returnedFlow.length === 1 && returnedFlow[0] !== flowId)) {
+                respond(response, 400, 'Authorization response rejected.', { 'Set-Cookie': clearCookie });
+                finish(failure('callback_rejected'));
+                return;
+            }
+            const allowed = ['code', 'sb_flow_id', 'error', 'error_code', 'error_description'];
+            const codes = url.searchParams.getAll('code');
+            const hasError = ['error', 'error_code', 'error_description'].some(k => url.searchParams.has(k));
+            if ([...url.searchParams.keys()].some(k => !allowed.includes(k) || url.searchParams.getAll(k).length !== 1)
+                || codes.length > 1 || (hasError && codes.length !== 0)) {
+                respond(response, 400, 'Authorization response rejected.', { 'Set-Cookie': clearCookie });
+                finish(failure('callback_rejected'));
+                return;
+            }
+            if (hasError) {
+                respond(response, 400, 'Authorization did not complete. Return to the helper.', { 'Set-Cookie': clearCookie });
+                finish(failure('oauth_denied'));
+                return;
+            }
+            const value = codes[0];
+            if (!value || !/^[A-Za-z0-9._~-]{1,2048}$/.test(value)) {
+                respond(response, 400, 'Authorization response rejected.', { 'Set-Cookie': clearCookie });
+                finish(failure('callback_rejected'));
+                return;
+            }
+            respond(response, 200, 'Authorization response received. Return to the helper for verification.', { 'Set-Cookie': clearCookie });
+            finish(null, value);
+        }
+        catch {
+            try {
+                respond(response, 400, 'Authorization response rejected.');
+            }
+            catch { /* No request/error details logged. */ }
+            finish(failure('callback_rejected'));
+        }
+    }
+    try {
+        if (signal?.aborted)
+            throw failure('interrupted');
+        signal?.addEventListener('abort', abort, { once: true });
+        for (const host of ['127.0.0.1', '::1']) {
+            const server = serverFactory({ maxHeaderSize: 8192, headersTimeout: 5000, requestTimeout: 5000 }, handler);
+            server.maxConnections = 4;
+            server.keepAliveTimeout = 1000;
+            server.on('clientError', (_error, socket) => socket.destroy());
+            servers.push(server);
+            await new Promise((resolve, reject) => {
+                const onError = error => reject(failure(error.code === 'EADDRINUSE' ? 'callback_port_in_use' : 'callback_unavailable'));
+                server.once('error', onError);
+                server.listen({ host, port: 5173, ipv6Only: true, exclusive: true }, () => {
+                    server.removeListener('error', onError);
+                    server.on('error', () => finish(failure('callback_unavailable')));
+                    resolve();
+                });
+            });
+        }
+        if (signal?.aborted)
+            throw failure('interrupted');
+        timer = setTimeout(() => finish(failure('callback_timeout')), timeoutMs);
+        return {
+            code, close,
+            configure(url, expectedFlow) {
+                const u = new URL(url);
+                if (authorizationUrl || settled || !/^[A-Za-z0-9_-]{8,64}$/.test(expectedFlow)
+                    || u.origin !== 'https://mzeuimqfrswrwoaqjdmp.supabase.co' || u.pathname !== '/auth/v1/authorize'
+                    || u.searchParams.get('provider') !== 'google' || u.searchParams.get('redirect_to') !== GOOGLE_REDIRECT
+                    || u.searchParams.get('code_challenge_method') !== 's256'
+                    || !/^[A-Za-z0-9_-]{43}$/.test(u.searchParams.get('code_challenge') ?? ''))
+                    throw failure('oauth_failed');
+                authorizationUrl = u.href;
+                flowId = expectedFlow;
+            },
+            startUrl: 'http://' + HOST + START + '?nonce=' + nonce,
+        };
+    }
+    catch (error) {
+        await close();
+        throw error instanceof GooglePkceError ? error : failure('callback_unavailable');
+    }
+}
+export async function googlePkceSignIn(client, options = {}) {
+    const callback = await createGoogleCallback({ timeoutMs: options.oauthTimeoutMs,
+        signal: options.signal, serverFactory: options.serverFactory });
+    let value, flowId;
+    try {
+        const start = await client.auth.signInWithOAuth({ provider: 'google',
+            options: { redirectTo: GOOGLE_REDIRECT, skipBrowserRedirect: true, queryParams: { prompt: 'select_account' } } });
+        if (start.error)
+            throw failure('oauth_failed');
+        flowId = start.data.flowId;
+        callback.configure(start.data.url, flowId);
+        const opening = Promise.resolve().then(() => (options.openBrowser ?? openSystemBrowser)(callback.startUrl));
+        await Promise.race([opening, callback.code.then(() => undefined)]);
+        value = await callback.code;
+    }
+    catch (error) {
+        throw error instanceof GooglePkceError ? error : failure('browser_open_failed');
+    }
+    finally {
+        await callback.close();
+    }
+    if (options.signal?.aborted)
+        throw failure('interrupted');
+    // Always select the retained flow's verifier, never a callback-selected slot.
+    return client.auth.exchangeCodeForSession(value, { flowId });
+}