@avi770/testteam 3.0.0 → 3.2.0

package/dist/agents/88-localhost-walkthrough.js

@@ -0,0 +1,1203 @@
+/**
+ * Localhost Walkthrough Agent — autonomously exercises the target app on
+ * localhost using the connection map produced by Agent #87.
+ *
+ * For every HTTP route discovered, sends a request through a native fetch
+ * client and surfaces any 5xx, network error, or unexpected status as a
+ * finding. For every UI module declared in the user's config, opens it in
+ * Playwright, captures console errors, and (where forms are detected) fills
+ * them with helpers/form-filler.ts test values and submits.
+ *
+ * Dev-server lifecycle: tries `config.devServer.command` first; falls back
+ * to `npm run dev` if the target project's package.json has that script.
+ * Waits for `config.devServer.healthUrl` (or `http://localhost:<port>/`)
+ * to return any 2xx/3xx/4xx response. The server process is torn down in
+ * a finally block so we never leak it.
+ *
+ * Stagehand (#85) fallback: when a UI route fails the deterministic walk
+ * AND the @browserbasehq/stagehand dep is reachable, attempt a single
+ * Stagehand-driven retry under the existing $0.10/test cost cap. If the
+ * dep is absent, surface that a fallback would have engaged.
+ */
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { BaseAgent } from './base-agent.js';
+import { launchOptions, startScreencast } from '../core/run-mode/index.js';
+import { fillForm } from '../helpers/form-filler.js';
+import { inferShape } from '../helpers/shape-fingerprint.js';
+const DEFAULT_READY_TIMEOUT_MS = 60_000;
+const ROUTE_REQUEST_TIMEOUT_MS = 8_000;
+const MAX_ROUTES_PER_RUN = 60;
+const MAX_UI_MODULES_PER_RUN = 20;
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve a dev-server descriptor from explicit config first, npm script second. */
+export function resolveDevServer(projectRoot, devServer) {
+    if (devServer?.command) {
+        const port = devServer.port;
+        return {
+            command: devServer.command,
+            cwd: devServer.cwd ?? projectRoot,
+            port,
+            healthUrl: devServer.healthUrl ?? `http://localhost:${port}/`,
+            readyText: devServer.readyText,
+            readyTimeoutMs: devServer.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+            source: 'config',
+        };
+    }
+    const pkg = readJson(path.join(projectRoot, 'package.json'));
+    if (!pkg?.scripts?.['dev']) {
+        return { error: 'No devServer config and no `dev` script in package.json' };
+    }
+    const port = devServer?.port ?? 3000;
+    return {
+        command: 'npm run dev',
+        cwd: devServer?.cwd ?? projectRoot,
+        port,
+        healthUrl: devServer?.healthUrl ?? `http://localhost:${port}/`,
+        readyText: devServer?.readyText,
+        readyTimeoutMs: devServer?.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+        source: 'autodetect',
+    };
+}
+async function waitForReady(url, timeoutMs, child, hasErrored) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (hasErrored?.())
+            return false; // spawn failed (ENOENT/EACCES) — stop polling now
+        if (child.exitCode !== null)
+            return false;
+        try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(2_000) });
+            // Any HTTP response means the server is listening (even 404).
+            if (res.status > 0)
+                return true;
+        }
+        catch {
+            // Connection refused / abort — keep polling.
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return false;
+}
+function killTree(child) {
+    if (child.exitCode !== null || child.killed)
+        return;
+    try {
+        // Negative PID kills the whole process group on POSIX (we spawned with detached:true).
+        if (process.platform !== 'win32' && child.pid) {
+            process.kill(-child.pid, 'SIGTERM');
+        }
+        else {
+            child.kill('SIGTERM');
+        }
+    }
+    catch {
+        // best effort
+    }
+}
+/**
+ * Common login route paths searched when `config.auth.loginUrl` is absent.
+ * Order matters — more specific patterns first.
+ */
+const LOGIN_PATH_PATTERNS = [
+    /^\/api\/auth\/(?:login|sign[-_]?in|session)s?$/i,
+    /^\/api\/(?:login|sign[-_]?in|sessions?)$/i,
+    /^\/auth\/(?:login|sign[-_]?in|session)s?$/i,
+    /^\/(?:login|sign[-_]?in)$/i,
+    /^\/sessions?$/i,
+];
+/**
+ * Common logout route paths searched when `config.auth.logoutUrl` is absent.
+ * Mirrors the login-path list — logout endpoints almost always live under
+ * the same prefix as their login counterpart.
+ */
+const LOGOUT_PATH_PATTERNS = [
+    /^\/api\/auth\/(?:logout|sign[-_]?out|session)s?$/i,
+    /^\/api\/(?:logout|sign[-_]?out|sessions?)$/i,
+    /^\/auth\/(?:logout|sign[-_]?out|session)s?$/i,
+    /^\/(?:logout|sign[-_]?out)$/i,
+    /^\/sessions?$/i,
+];
+/**
+ * Common refresh-token route paths searched when `config.auth.refreshUrl`
+ * is absent. Refresh endpoints usually sit next to login under the same
+ * prefix.
+ */
+const REFRESH_PATH_PATTERNS = [
+    /^\/api\/auth\/(?:refresh|refresh[-_]?token|token\/refresh)\/?$/i,
+    /^\/api\/(?:refresh|refresh[-_]?token|token\/refresh|token)\/?$/i,
+    /^\/auth\/(?:refresh|refresh[-_]?token|token\/refresh)\/?$/i,
+    /^\/(?:refresh|refresh[-_]?token)\/?$/i,
+];
+const JSON_BEARER_KEYS = [
+    'token',
+    'accessToken',
+    'access_token',
+    'jwt',
+    'authToken',
+    'auth_token',
+    'idToken',
+    'id_token',
+];
+const JSON_REFRESH_KEYS = [
+    'refreshToken',
+    'refresh_token',
+    'refresh',
+];
+/** Pull a refresh token from common locations in a login response body. */
+export function extractRefreshToken(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const obj = body;
+    for (const key of JSON_REFRESH_KEYS) {
+        const v = obj[key];
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+    }
+    if (obj.data && typeof obj.data === 'object') {
+        const nested = extractRefreshToken(obj.data);
+        if (nested)
+            return nested;
+    }
+    return null;
+}
+/** Pull the bearer token from any common location in a login response body. */
+export function extractBearer(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const obj = body;
+    for (const key of JSON_BEARER_KEYS) {
+        const v = obj[key];
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+    }
+    // Nested under .data — common in Rails/Laravel/NestJS responses.
+    if (obj.data && typeof obj.data === 'object') {
+        const nested = extractBearer(obj.data);
+        if (nested)
+            return nested;
+    }
+    return null;
+}
+/** Parse a single Set-Cookie header value into { name, value }, stripping attributes. */
+export function parseSetCookie(header) {
+    const first = header.split(';', 1)[0]?.trim();
+    if (!first)
+        return null;
+    const eq = first.indexOf('=');
+    if (eq <= 0)
+        return null;
+    return { name: first.slice(0, eq).trim(), value: first.slice(eq + 1).trim() };
+}
+function pickFirstCredential(credentials) {
+    if (!credentials)
+        return null;
+    for (const [role, entry] of Object.entries(credentials)) {
+        if (entry.email && entry.password)
+            return { role, email: entry.email, password: entry.password };
+    }
+    return null;
+}
+/** Enumerate every credential entry that has both an email and a password. */
+export function listAllCredentials(credentials) {
+    if (!credentials)
+        return [];
+    const out = [];
+    for (const [role, entry] of Object.entries(credentials)) {
+        if (entry.email && entry.password)
+            out.push({ role, email: entry.email, password: entry.password });
+    }
+    return out;
+}
+/**
+ * Path patterns that indicate a route is intended for elevated access only.
+ * If a non-first role can hit a 2xx response on one of these, that's a likely
+ * authorization-bypass bug.
+ */
+export const ADMIN_PATH_PATTERNS = [
+    /\/admin(?:\/|$|\?)/i,
+    /\/internal(?:\/|$|\?)/i,
+    /\/staff(?:\/|$|\?)/i,
+    /\/management(?:\/|$|\?)/i,
+    /\/manage(?:\/|$|\?)/i,
+    /\/control[-_]?panel(?:\/|$|\?)/i,
+    /\/superuser(?:\/|$|\?)/i,
+    /\/sudo(?:\/|$|\?)/i,
+];
+export function isAdminPath(routePath) {
+    return ADMIN_PATH_PATTERNS.some((p) => p.test(routePath));
+}
+/** Find the logout URL by config first, then by scanning connection-map routes. */
+export function findLogoutUrl(configuredUrl, routes, baseUrl) {
+    if (configuredUrl) {
+        if (configuredUrl.startsWith('http://') || configuredUrl.startsWith('https://'))
+            return configuredUrl;
+        return baseUrl + (configuredUrl.startsWith('/') ? configuredUrl : `/${configuredUrl}`);
+    }
+    // Most logout endpoints accept POST or GET; some are DELETE on /sessions.
+    const candidates = routes.filter((r) => (r.method === 'POST' || r.method === 'GET' || r.method === 'DELETE' || r.method === 'ALL') &&
+        LOGOUT_PATH_PATTERNS.some((p) => p.test(r.path)));
+    if (candidates.length === 0)
+        return null;
+    for (const pat of LOGOUT_PATH_PATTERNS) {
+        const hit = candidates.find((r) => pat.test(r.path));
+        if (hit)
+            return baseUrl + (hit.path.startsWith('/') ? hit.path : `/${hit.path}`);
+    }
+    return null;
+}
+/** Find the refresh-token URL by config first, then connection-map scan. */
+export function findRefreshUrl(configuredUrl, routes, baseUrl) {
+    if (configuredUrl) {
+        if (configuredUrl.startsWith('http://') || configuredUrl.startsWith('https://'))
+            return configuredUrl;
+        return baseUrl + (configuredUrl.startsWith('/') ? configuredUrl : `/${configuredUrl}`);
+    }
+    const candidates = routes.filter((r) => (r.method === 'POST' || r.method === 'ALL') && REFRESH_PATH_PATTERNS.some((p) => p.test(r.path)));
+    if (candidates.length === 0)
+        return null;
+    for (const pat of REFRESH_PATH_PATTERNS) {
+        const hit = candidates.find((r) => pat.test(r.path));
+        if (hit)
+            return baseUrl + (hit.path.startsWith('/') ? hit.path : `/${hit.path}`);
+    }
+    return null;
+}
+/**
+ * POST to the refresh URL with the captured refresh token (sent both as a
+ * JSON body field and via the session cookies, covering body-based and
+ * cookie-based refresh schemes). Returns the status and whether a NEW
+ * access token / session cookie came back. null on network error.
+ */
+/**
+ * Validate that a fetch target is an http(s) URL before issuing an outbound
+ * request. Auth-flow URLs are built from discovered/config data, so this barrier
+ * keeps requests on http(s) and rejects malformed or other-scheme URLs. Throws
+ * on a bad URL; call sites treat a throw as a failed/aborted request.
+ */
+function assertSafeFetchUrl(raw) {
+    const parsed = new URL(raw);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`unsupported URL scheme: ${parsed.protocol}`);
+    }
+    return parsed;
+}
+export async function attemptRefresh(refreshUrl, session) {
+    const headers = { 'Content-Type': 'application/json', Accept: 'application/json' };
+    const cookieHeader = session.cookies.map((c) => `${c.name}=${c.value}`).join('; ');
+    if (cookieHeader)
+        headers.Cookie = cookieHeader;
+    if (session.bearerToken)
+        headers.Authorization = `Bearer ${session.bearerToken}`;
+    try {
+        const res = await fetch(assertSafeFetchUrl(refreshUrl), {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                refreshToken: session.refreshToken ?? undefined,
+                refresh_token: session.refreshToken ?? undefined,
+            }),
+            redirect: 'manual',
+            signal: AbortSignal.timeout(8_000),
+        });
+        let gotNewToken = false;
+        const setCookies = typeof res.headers.getSetCookie === 'function' ? res.headers.getSetCookie() : [];
+        if (setCookies.length > 0)
+            gotNewToken = true;
+        if ((res.headers.get('content-type') ?? '').includes('application/json')) {
+            try {
+                const body = await res.clone().json();
+                if (extractBearer(body))
+                    gotNewToken = true;
+            }
+            catch {
+                // not JSON — rely on cookies
+            }
+        }
+        return { status: res.status, gotNewToken };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * POST to the logout URL with the live session attached. Returns the HTTP
+ * status (or null on network error). Some apps respond 200, some 204, some
+ * 302 — any 2xx/302 counts as accepted; the actual invalidation check is
+ * separate.
+ */
+export async function attemptLogout(logoutUrl, session) {
+    const headers = { ...sessionHeaders(session) };
+    try {
+        const res = await fetch(assertSafeFetchUrl(logoutUrl), {
+            method: 'POST',
+            headers,
+            redirect: 'manual',
+            signal: AbortSignal.timeout(8_000),
+        });
+        return { status: res.status };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * After logout, re-attempt the login URL with the OLD session cookie still
+ * attached. Many servers reject by responding 401/403 with the now-invalid
+ * cookie — that's the "invalidated" case. If the server returns 2xx or
+ * keeps issuing a fresh session for the old cookie, the session wasn't
+ * properly destroyed.
+ *
+ * Returns true if the session appears invalidated (4xx or no cookies in
+ * response), false if it still works.
+ */
+export async function verifySessionInvalidated(loginUrl, session) {
+    try {
+        const res = await fetch(loginUrl, {
+            method: 'GET',
+            headers: sessionHeaders(session),
+            redirect: 'manual',
+            signal: AbortSignal.timeout(5_000),
+        });
+        // 4xx with an authenticated cookie attached = server is correctly rejecting
+        if (res.status >= 400 && res.status < 500)
+            return true;
+        // 2xx = session might still be valid; treat as not invalidated
+        return false;
+    }
+    catch {
+        return null;
+    }
+}
+/** Find the login URL by config first, then by scanning connection-map routes. */
+export function findLoginUrl(configuredUrl, routes, baseUrl) {
+    if (configuredUrl) {
+        if (configuredUrl.startsWith('http://') || configuredUrl.startsWith('https://'))
+            return configuredUrl;
+        return baseUrl + (configuredUrl.startsWith('/') ? configuredUrl : `/${configuredUrl}`);
+    }
+    const candidates = routes.filter((r) => (r.method === 'POST' || r.method === 'ALL') && LOGIN_PATH_PATTERNS.some((p) => p.test(r.path)));
+    if (candidates.length === 0)
+        return null;
+    // Prefer the most specific match: pick by pattern order, not route order.
+    for (const pat of LOGIN_PATH_PATTERNS) {
+        const hit = candidates.find((r) => pat.test(r.path));
+        if (hit)
+            return baseUrl + (hit.path.startsWith('/') ? hit.path : `/${hit.path}`);
+    }
+    return null;
+}
+/** Attempt login; returns a session on success, null on failure. */
+async function attemptLogin(loginUrl, role, email, password) {
+    const tryBody = async (kind) => {
+        try {
+            const body = kind === 'json'
+                ? JSON.stringify({ email, password, username: email })
+                : new URLSearchParams({ email, password, username: email }).toString();
+            const headers = kind === 'json'
+                ? { 'Content-Type': 'application/json', Accept: 'application/json' }
+                : { 'Content-Type': 'application/x-www-form-urlencoded' };
+            return await fetch(assertSafeFetchUrl(loginUrl), {
+                method: 'POST',
+                headers,
+                body,
+                redirect: 'manual',
+                signal: AbortSignal.timeout(8_000),
+            });
+        }
+        catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
+        }
+    };
+    for (const kind of ['json', 'form']) {
+        const res = await tryBody(kind);
+        if ('error' in res)
+            continue;
+        // 2xx, or 302 redirect (common for form login) — both can carry a session cookie.
+        if ((res.status >= 200 && res.status < 300) || res.status === 302) {
+            const setCookies = typeof res.headers.getSetCookie === 'function' ? res.headers.getSetCookie() : [];
+            const cookies = setCookies
+                .map(parseSetCookie)
+                .filter((c) => c !== null);
+            let bearer = null;
+            let refresh = null;
+            try {
+                const ct = res.headers.get('content-type') ?? '';
+                if (ct.includes('application/json')) {
+                    const body = await res.clone().json();
+                    bearer = extractBearer(body);
+                    refresh = extractRefreshToken(body);
+                }
+            }
+            catch {
+                // body wasn't JSON — that's fine, cookies may carry the session
+            }
+            if (cookies.length === 0 && !bearer) {
+                // No session captured even though response was 2xx — treat as failure.
+                return { error: `login ${kind} returned ${res.status} but no session cookie or token` };
+            }
+            return {
+                session: {
+                    asRole: role,
+                    loginUrl,
+                    bodyKind: kind,
+                    cookies,
+                    bearerToken: bearer,
+                    refreshToken: refresh,
+                },
+            };
+        }
+    }
+    return { error: 'login attempted with both JSON and form bodies; neither succeeded' };
+}
+/**
+ * Probe the login endpoint with a deliberately wrong password. After a real
+ * login has already worked we know the endpoint is reachable and the body
+ * kind that the app expects, so we can fire a single targeted request and
+ * inspect the outcome. A 2xx with a session cookie/token = auth fail-open
+ * (critical). 4xx = correctly rejected (silent pass).
+ *
+ * Returns null if the probe couldn't be run (network error / unsupported
+ * scheme); the caller treats null as "inconclusive, no finding".
+ */
+export async function probeBadCredentials(loginUrl, email, bodyKind) {
+    // Use a CSPRNG (not Math.random) so the throwaway credential is unpredictable
+    // in this security-sensitive auth probe (CodeQL js/insecure-randomness).
+    const wrongPassword = '__testteam_definitely_wrong_password_' + randomBytes(6).toString('hex');
+    try {
+        const body = bodyKind === 'json'
+            ? JSON.stringify({ email, password: wrongPassword, username: email })
+            : new URLSearchParams({ email, password: wrongPassword, username: email }).toString();
+        const headers = bodyKind === 'json'
+            ? { 'Content-Type': 'application/json', Accept: 'application/json' }
+            : { 'Content-Type': 'application/x-www-form-urlencoded' };
+        const res = await fetch(loginUrl, {
+            method: 'POST',
+            headers,
+            body,
+            redirect: 'manual',
+            signal: AbortSignal.timeout(8_000),
+        });
+        const setCookies = typeof res.headers.getSetCookie === 'function' ? res.headers.getSetCookie() : [];
+        const cookies = setCookies.map(parseSetCookie).filter((c) => c !== null);
+        let bearer = null;
+        if ((res.headers.get('content-type') ?? '').includes('application/json')) {
+            try {
+                bearer = extractBearer(await res.clone().json());
+            }
+            catch {
+                // body wasn't JSON despite header — treat as no bearer
+            }
+        }
+        return { status: res.status, capturedSession: cookies.length > 0 || bearer !== null };
+    }
+    catch {
+        return null;
+    }
+}
+function sessionHeaders(session) {
+    if (!session)
+        return {};
+    const headers = {};
+    if (session.cookies.length > 0) {
+        headers.Cookie = session.cookies.map((c) => `${c.name}=${c.value}`).join('; ');
+    }
+    if (session.bearerToken) {
+        headers.Authorization = `Bearer ${session.bearerToken}`;
+    }
+    return headers;
+}
+function apiRoutesHint(routes) {
+    return routes.filter((r) => r.framework !== 'unknown').length;
+}
+export class LocalhostWalkthroughAgent extends BaseAgent {
+    agentId = 88;
+    agentName = 'Localhost Walkthrough';
+    /** Override hook for tests — defaults to real spawn. */
+    spawnImpl = spawn;
+    async preFlight() {
+        const root = this.config.projectRoot ?? process.cwd();
+        if (!fs.existsSync(root)) {
+            throw new Error(`projectRoot does not exist: ${root}`);
+        }
+    }
+    async execute() {
+        const findings = [];
+        const projectRoot = this.config.projectRoot ?? process.cwd();
+        // Load the connection map from #87. Without it the walk has no targets.
+        const mapPath = path.join(this.runDir, 'evidence', 'connection-map.json');
+        const map = readJson(mapPath);
+        if (!map) {
+            findings.push({
+                id: `${this.agentId}-no-map`,
+                type: 'infra-issue',
+                severity: 'high',
+                agentId: this.agentId,
+                module: 'localhost-walkthrough',
+                description: 'connection-map.json not found in run directory. Localhost Walkthrough (#88) requires Connection Mapper (#87) to run first in the same phase.',
+            });
+            return findings;
+        }
+        const resolved = resolveDevServer(projectRoot, this.config.devServer);
+        if ('error' in resolved) {
+            findings.push({
+                id: `${this.agentId}-no-dev-server`,
+                type: 'infra-issue',
+                severity: 'high',
+                agentId: this.agentId,
+                module: 'localhost-walkthrough',
+                description: resolved.error + '. Add a `devServer` block to testteam.config.ts.',
+            });
+            return findings;
+        }
+        const telemetry = {
+            resolvedDevServer: resolved,
+            routesAttempted: 0,
+            routesPassed: 0,
+            routesFailed: 0,
+            uiModulesAttempted: 0,
+            uiModulesPassed: 0,
+            uiModulesFailed: 0,
+            stagehandFallbacks: 0,
+        };
+        let child = null;
+        try {
+            // Split the command into argv to use execFile-style spawn — never shell:true
+            // (a deliberate shell-injection guard). Note: npm-family launchers can't be
+            // started this way on Windows (`spawn('npm')` → ENOENT); that surfaces as a
+            // graceful finding below, and a Windows user can point devServer.command at
+            // a direct binary. We do NOT relax to shell:true (see the 'error' guard).
+            const [bin, ...args] = resolved.command.split(/\s+/);
+            // A spawn failure (ENOENT/EACCES/EINVAL/…) can surface ASYNCHRONOUSLY as an
+            // 'error' event, not a throw — with NO listener, Node crashes the whole
+            // pipeline. Capture it (and any synchronous throw, via the outer try) and
+            // degrade to a finding instead of dying.
+            let spawnError = null;
+            child = this.spawnImpl(bin, args, {
+                cwd: resolved.cwd,
+                env: { ...process.env, BROWSER: 'none', CI: '1' },
+                detached: process.platform !== 'win32',
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            child.on('error', (err) => {
+                spawnError = err;
+            });
+            const ready = await waitForReady(resolved.healthUrl, resolved.readyTimeoutMs, child, () => spawnError !== null);
+            // `spawnError` is assigned in the 'error' callback, which may have fired
+            // during the await above; the cast defeats CFA narrowing-to-null.
+            const failure = spawnError;
+            if (failure) {
+                findings.push({
+                    id: `${this.agentId}-dev-server-spawn-failed`,
+                    type: 'infra-issue',
+                    severity: 'critical',
+                    agentId: this.agentId,
+                    module: 'localhost-walkthrough',
+                    description: `Dev server (${resolved.command}) failed to start: ${failure.message}. Set a valid devServer.command in testteam.config.ts.`,
+                });
+                return findings;
+            }
+            if (!ready) {
+                findings.push({
+                    id: `${this.agentId}-dev-server-not-ready`,
+                    type: 'infra-issue',
+                    severity: 'critical',
+                    agentId: this.agentId,
+                    module: 'localhost-walkthrough',
+                    description: `Dev server (${resolved.command}) did not respond on ${resolved.healthUrl} within ${resolved.readyTimeoutMs}ms.`,
+                });
+                return findings;
+            }
+            // Attempt login before walking — gives downstream requests an authenticated
+            // session so #88 covers more than just public routes.
+            const baseUrl = new URL(resolved.healthUrl).origin;
+            const { session, attempt } = await this.tryLogin(map.routes, baseUrl);
+            this.persistAuthAttempt(attempt);
+            if (session) {
+                findings.push({
+                    id: `${this.agentId}-auth-success`,
+                    type: 'infra-issue',
+                    severity: 'info',
+                    agentId: this.agentId,
+                    module: 'localhost-walkthrough',
+                    description: `Logged in as "${session.asRole}" via ${session.bodyKind} POST to ${session.loginUrl}. Walking ${apiRoutesHint(map.routes)} routes with session attached.`,
+                });
+                // Fail-open probe: now that we know the login endpoint works, fire a
+                // wrong-password POST and verify it's rejected. A 2xx response with a
+                // session cookie/token means auth fails open — critical security bug.
+                const probe = await this.runBadCredentialsProbe(session);
+                if (probe) {
+                    if (probe.capturedSession) {
+                        findings.push({
+                            id: `${this.agentId}-auth-fail-open`,
+                            type: 'code-bug-security',
+                            severity: 'critical',
+                            agentId: this.agentId,
+                            module: 'localhost-walkthrough',
+                            description: `Login endpoint accepted a deliberately wrong password (status ${probe.status}) AND returned a valid session. Authentication is failing open — anyone can log in as "${session.asRole}".`,
+                        });
+                    }
+                    else if (probe.status >= 200 && probe.status < 300) {
+                        // 2xx without a session is suspicious but not conclusively broken —
+                        // many apps return 200 with an error body for "wrong password".
+                        findings.push({
+                            id: `${this.agentId}-auth-soft-reject`,
+                            type: 'code-bug-logic',
+                            severity: 'medium',
+                            agentId: this.agentId,
+                            module: 'localhost-walkthrough',
+                            description: `Login endpoint returned ${probe.status} on wrong password without a session. Convention is 401/403 — using 2xx with an error body breaks standard auth-handling tooling.`,
+                        });
+                    }
+                    // 4xx/5xx/302 on a wrong password = correct behaviour; stay silent.
+                }
+            }
+            else if (attempt.outcome === 'failed') {
+                findings.push({
+                    id: `${this.agentId}-auth-failed`,
+                    type: 'code-bug-logic',
+                    severity: 'high',
+                    agentId: this.agentId,
+                    module: 'localhost-walkthrough',
+                    description: `Login attempt failed: ${attempt.reason}. The walk will continue but authenticated routes will return 401/403.`,
+                });
+            }
+            // Note: 'skipped' (no creds / no login URL) is intentionally silent — the
+            // user may be testing a public-only app.
+            const authHeaders = sessionHeaders(session);
+            // Walk HTTP routes deterministically.
+            const apiRoutes = map.routes
+                .filter((r) => r.framework !== 'unknown')
+                .slice(0, MAX_ROUTES_PER_RUN);
+            const captures = [];
+            for (const route of apiRoutes) {
+                telemetry.routesAttempted++;
+                try {
+                    const url = baseUrl + (route.path.startsWith('/') ? route.path : `/${route.path}`);
+                    const method = (route.method === 'ALL' ? 'GET' : route.method);
+                    const res = await fetch(assertSafeFetchUrl(url), {
+                        method,
+                        headers: authHeaders,
+                        signal: AbortSignal.timeout(ROUTE_REQUEST_TIMEOUT_MS),
+                    });
+                    const contentType = res.headers.get('content-type');
+                    let shape = null;
+                    if (contentType?.includes('application/json')) {
+                        try {
+                            const body = await res.clone().json();
+                            shape = inferShape(body);
+                        }
+                        catch {
+                            // body wasn't valid JSON despite the header — leave shape null
+                        }
+                    }
+                    captures.push({
+                        method: route.method,
+                        path: route.path,
+                        status: res.status,
+                        contentType,
+                        shape,
+                        file: route.file,
+                        line: route.line,
+                    });
+                    if (res.status >= 500) {
+                        telemetry.routesFailed++;
+                        findings.push({
+                            id: `${this.agentId}-route-5xx-${route.method}-${route.path.replace(/[^\w]/g, '_')}`,
+                            type: 'code-bug-logic',
+                            severity: 'high',
+                            agentId: this.agentId,
+                            module: 'localhost-walkthrough',
+                            description: `${route.method} ${route.path} returned ${res.status} (${route.file}:${route.line})`,
+                            file: route.file,
+                            line: route.line,
+                        });
+                    }
+                    else if ((res.status === 401 || res.status === 403) && session) {
+                        // We had a valid session attached but the route still rejected us.
+                        // That's a likely authz bug or a mis-attached session, not a routing failure.
+                        telemetry.routesFailed++;
+                        findings.push({
+                            id: `${this.agentId}-route-unauthorized-${route.method}-${route.path.replace(/[^\w]/g, '_')}`,
+                            type: 'code-bug-logic',
+                            severity: 'medium',
+                            agentId: this.agentId,
+                            module: 'localhost-walkthrough',
+                            description: `${route.method} ${route.path} returned ${res.status} despite a logged-in session — possible authz misconfiguration (${route.file}:${route.line})`,
+                            file: route.file,
+                            line: route.line,
+                        });
+                    }
+                    else {
+                        telemetry.routesPassed++;
+                    }
+                }
+                catch (err) {
+                    telemetry.routesFailed++;
+                    findings.push({
+                        id: `${this.agentId}-route-error-${route.method}-${route.path.replace(/[^\w]/g, '_')}`,
+                        type: 'code-bug-logic',
+                        severity: 'medium',
+                        agentId: this.agentId,
+                        module: 'localhost-walkthrough',
+                        description: `${route.method} ${route.path} failed: ${err instanceof Error ? err.message : String(err)}`,
+                        file: route.file,
+                        line: route.line,
+                    });
+                }
+            }
+            // Persist captures for Agent #90 (Response Shape Validator) to read.
+            try {
+                const evidenceDir = path.join(this.runDir, 'evidence');
+                fs.mkdirSync(evidenceDir, { recursive: true });
+                const responsesFile = {
+                    version: 1,
+                    generatedAt: new Date().toISOString(),
+                    baseUrl,
+                    captures,
+                };
+                fs.writeFileSync(path.join(evidenceDir, 'route-responses.json'), JSON.stringify(responsesFile, null, 2), 'utf-8');
+                this.addEvidence({
+                    type: 'report',
+                    path: 'evidence/route-responses.json',
+                    description: `Route responses captured: ${captures.length} (for #90 drift detection)`,
+                });
+            }
+            catch {
+                // non-fatal — drift detection just won't have new data this run
+            }
+            // Multi-role authz-bypass probe. If more than one credential is
+            // configured, log in as each additional role and probe admin-shaped
+            // routes. A 2xx response from a non-first role is a likely
+            // authorization bypass — one of the OWASP Top 10 bug classes that's
+            // easy to miss because the happy path looks fine.
+            if (session) {
+                await this.runMultiRoleAuthzProbe(session.asRole, map.routes, baseUrl, findings);
+            }
+            // Refresh-token flow: exercise the refresh endpoint and verify a new
+            // access token is issued. Runs BEFORE logout (logout may revoke the
+            // refresh token).
+            if (session) {
+                await this.runRefreshTest(session, map.routes, baseUrl, findings);
+            }
+            // Logout flow: exercise the logout endpoint and verify the session
+            // is actually invalidated. Session-not-invalidated is a real security
+            // bug class — old cookies / tokens continuing to work after logout.
+            if (session) {
+                await this.runLogoutTest(session, map.routes, baseUrl, findings);
+            }
+            // Walk declared UI modules with Playwright if the project has any.
+            const uiModules = (this.config.modules ?? []).slice(0, MAX_UI_MODULES_PER_RUN);
+            if (uiModules.length > 0) {
+                const { chromium } = await import('playwright');
+                let browser = null;
+                let screencast = null;
+                try {
+                    browser = await chromium.launch(launchOptions(this.runMode));
+                    const context = await browser.newContext();
+                    if (session && session.cookies.length > 0) {
+                        const host = new URL(baseUrl).hostname;
+                        await context.addCookies(session.cookies.map((c) => ({
+                            name: c.name,
+                            value: c.value,
+                            domain: host,
+                            path: '/',
+                        })));
+                    }
+                    if (session && session.bearerToken) {
+                        await context.setExtraHTTPHeaders({ Authorization: `Bearer ${session.bearerToken}` });
+                    }
+                    const page = await context.newPage();
+                    screencast = this.frames ? startScreencast(page, this.frames) : null;
+                    const consoleErrors = [];
+                    page.on('console', (msg) => {
+                        if (msg.type() === 'error')
+                            consoleErrors.push(msg.text());
+                    });
+                    page.on('pageerror', (err) => consoleErrors.push(err.message));
+                    for (const mod of uiModules) {
+                        telemetry.uiModulesAttempted++;
+                        const errorsBefore = consoleErrors.length;
+                        const url = baseUrl + (mod.route.startsWith('/') ? mod.route : `/${mod.route}`);
+                        try {
+                            const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10_000 });
+                            if (!response || response.status() >= 500) {
+                                throw new Error(`navigated with status ${response?.status() ?? 'unknown'}`);
+                            }
+                            // Attempt to fill any visible forms — failure here is non-fatal.
+                            try {
+                                await fillForm(page, '');
+                            }
+                            catch {
+                                // form-filler returns false on missing fields; ignore errors here
+                            }
+                            const newErrors = consoleErrors.length - errorsBefore;
+                            if (newErrors > 0) {
+                                findings.push({
+                                    id: `${this.agentId}-console-errors-${mod.id}`,
+                                    type: 'code-bug-logic',
+                                    severity: 'medium',
+                                    agentId: this.agentId,
+                                    module: 'localhost-walkthrough',
+                                    description: `${mod.id} (${mod.route}) produced ${newErrors} console error(s) during walk: ${consoleErrors
+                                        .slice(errorsBefore)
+                                        .slice(0, 3)
+                                        .join('; ')}`,
+                                });
+                                telemetry.uiModulesFailed++;
+                            }
+                            else {
+                                telemetry.uiModulesPassed++;
+                            }
+                        }
+                        catch (err) {
+                            telemetry.uiModulesFailed++;
+                            const stagehandUsed = await this.tryStagehandFallback(url, mod.id);
+                            if (stagehandUsed)
+                                telemetry.stagehandFallbacks++;
+                            findings.push({
+                                id: `${this.agentId}-ui-failed-${mod.id}`,
+                                type: 'code-bug-logic',
+                                severity: 'high',
+                                agentId: this.agentId,
+                                module: 'localhost-walkthrough',
+                                description: `${mod.id} (${mod.route}) failed deterministic walk: ${err instanceof Error ? err.message : String(err)}${stagehandUsed ? ' [Stagehand fallback attempted]' : ' [Stagehand fallback unavailable]'}`,
+                            });
+                        }
+                    }
+                }
+                finally {
+                    screencast?.stop();
+                    if (browser)
+                        await browser.close();
+                }
+            }
+            // Persist telemetry alongside the connection map.
+            const telemetryPath = path.join(this.runDir, 'evidence', 'walkthrough-telemetry.json');
+            try {
+                fs.writeFileSync(telemetryPath, JSON.stringify(telemetry, null, 2), 'utf-8');
+                this.addEvidence({
+                    type: 'report',
+                    path: 'evidence/walkthrough-telemetry.json',
+                    description: `Walkthrough: ${telemetry.routesPassed}/${telemetry.routesAttempted} routes, ${telemetry.uiModulesPassed}/${telemetry.uiModulesAttempted} UI modules`,
+                });
+            }
+            catch {
+                // non-fatal
+            }
+        }
+        finally {
+            if (child)
+                killTree(child);
+        }
+        return findings;
+    }
+    /**
+     * Pre-walk login attempt. Resolves the login URL (config first, then
+     * connection-map detection), picks the first credential entry, and tries
+     * JSON then form bodies. Returns null + an attempt record on every
+     * non-success path so the caller can surface findings consistently.
+     *
+     * Exposed as a protected method so tests can override it without spinning
+     * up a real dev server.
+     */
+    async tryLogin(routes, baseUrl) {
+        const creds = pickFirstCredential(this.config.auth?.credentials);
+        if (!creds) {
+            return {
+                session: null,
+                attempt: {
+                    version: 1,
+                    attemptedAt: new Date().toISOString(),
+                    outcome: 'skipped',
+                    reason: 'no credentials configured under config.auth.credentials',
+                    loginUrl: null,
+                    asRole: null,
+                    bodyKind: null,
+                    sessionCaptured: false,
+                },
+            };
+        }
+        return this.loginAs(creds, routes, baseUrl);
+    }
+    /**
+     * Log in with an explicit credential. Same shape as tryLogin but the
+     * caller picks the role — used by the multi-role authz-bypass probe so
+     * we can drive logins as roles beyond the first.
+     */
+    async loginAs(creds, routes, baseUrl) {
+        const loginUrl = findLoginUrl(this.config.auth?.loginUrl, routes, baseUrl);
+        if (!loginUrl) {
+            return {
+                session: null,
+                attempt: {
+                    version: 1,
+                    attemptedAt: new Date().toISOString(),
+                    outcome: 'skipped',
+                    reason: 'no config.auth.loginUrl and no login-shaped route in connection-map',
+                    loginUrl: null,
+                    asRole: creds.role,
+                    bodyKind: null,
+                    sessionCaptured: false,
+                },
+            };
+        }
+        const result = await attemptLogin(loginUrl, creds.role, creds.email, creds.password);
+        if ('error' in result) {
+            return {
+                session: null,
+                attempt: {
+                    version: 1,
+                    attemptedAt: new Date().toISOString(),
+                    outcome: 'failed',
+                    reason: result.error,
+                    loginUrl,
+                    asRole: creds.role,
+                    bodyKind: null,
+                    sessionCaptured: false,
+                },
+            };
+        }
+        return {
+            session: result.session,
+            attempt: {
+                version: 1,
+                attemptedAt: new Date().toISOString(),
+                outcome: 'success',
+                reason: `logged in via ${result.session.bodyKind} POST`,
+                loginUrl,
+                asRole: creds.role,
+                bodyKind: result.session.bodyKind,
+                sessionCaptured: result.session.cookies.length > 0 || result.session.bearerToken !== null,
+            },
+        };
+    }
+    /**
+     * Log in as every role beyond the one used for the main walk, then hit
+     * any admin-shaped route discovered by #87. A 2xx response from a
+     * non-first role on an admin path = authorization bypass (high,
+     * code-bug-security). Persists `evidence/multi-role-walk.json` with
+     * per-role status per route for human review.
+     *
+     * Costs ~one extra fetch per (additional role × admin route). If no
+     * additional roles are configured or no admin routes were discovered,
+     * exits silently.
+     */
+    async runMultiRoleAuthzProbe(primaryRole, routes, baseUrl, findings) {
+        const allCreds = listAllCredentials(this.config.auth?.credentials);
+        const additionalCreds = allCreds.filter((c) => c.role !== primaryRole);
+        if (additionalCreds.length === 0)
+            return;
+        const adminRoutes = routes
+            .filter((r) => r.framework !== 'unknown' && isAdminPath(r.path))
+            .slice(0, MAX_ROUTES_PER_RUN);
+        if (adminRoutes.length === 0)
+            return;
+        const perRoute = {};
+        for (const cred of additionalCreds) {
+            const { session } = await this.loginAs(cred, routes, baseUrl);
+            if (!session)
+                continue;
+            const headers = sessionHeaders(session);
+            for (const route of adminRoutes) {
+                const url = baseUrl + (route.path.startsWith('/') ? route.path : `/${route.path}`);
+                const method = (route.method === 'ALL' ? 'GET' : route.method);
+                const key = `${route.method} ${route.path}`;
+                try {
+                    const res = await fetch(assertSafeFetchUrl(url), {
+                        method,
+                        headers,
+                        signal: AbortSignal.timeout(ROUTE_REQUEST_TIMEOUT_MS),
+                    });
+                    if (!perRoute[key])
+                        perRoute[key] = {};
+                    perRoute[key][cred.role] = res.status;
+                    if (res.status >= 200 && res.status < 300) {
+                        findings.push({
+                            id: `${this.agentId}-authz-bypass-${cred.role}-${route.method}-${route.path.replace(/[^\w]/g, '_')}`,
+                            type: 'code-bug-security',
+                            severity: 'high',
+                            agentId: this.agentId,
+                            module: 'localhost-walkthrough',
+                            description: `${route.method} ${route.path} returned ${res.status} when logged in as "${cred.role}" — admin-shaped path is accessible to a non-primary role (${route.file}:${route.line})`,
+                            file: route.file,
+                            line: route.line,
+                        });
+                    }
+                }
+                catch {
+                    // network errors on the probe are non-fatal; don't flood findings
+                }
+            }
+        }
+        try {
+            const evidenceDir = path.join(this.runDir, 'evidence');
+            fs.mkdirSync(evidenceDir, { recursive: true });
+            fs.writeFileSync(path.join(evidenceDir, 'multi-role-walk.json'), JSON.stringify({
+                version: 1,
+                generatedAt: new Date().toISOString(),
+                primaryRole,
+                additionalRoles: additionalCreds.map((c) => c.role),
+                adminRoutesProbed: adminRoutes.map((r) => ({ method: r.method, path: r.path })),
+                perRoute,
+            }, null, 2), 'utf-8');
+            this.addEvidence({
+                type: 'report',
+                path: 'evidence/multi-role-walk.json',
+                description: `Multi-role probe: ${additionalCreds.length} additional role(s) × ${adminRoutes.length} admin routes`,
+            });
+        }
+        catch {
+            // non-fatal
+        }
+    }
+    /**
+     * Exercise the refresh-token endpoint and verify a fresh access token /
+     * session is issued. Skipped silently when no refresh URL resolves, or
+     * when no refresh URL was configured AND no refresh token was captured
+     * at login (the common JWT-without-refresh case).
+     *
+     * Findings:
+     *   - 88-refresh-failed (medium, code-bug-logic): the refresh endpoint
+     *     returned non-2xx, or 2xx but issued no new token — the refresh
+     *     flow is broken and sessions can't be extended.
+     */
+    async runRefreshTest(session, routes, baseUrl, findings) {
+        const refreshUrl = findRefreshUrl(this.config.auth?.refreshUrl, routes, baseUrl);
+        if (!refreshUrl)
+            return;
+        // If we're relying on auto-detection (no explicit config) and never
+        // captured a refresh token, don't probe — many apps expose no refresh.
+        if (!this.config.auth?.refreshUrl && !session.refreshToken)
+            return;
+        const result = await attemptRefresh(refreshUrl, session);
+        if (!result)
+            return; // network error — non-fatal
+        const accepted = result.status >= 200 && result.status < 300;
+        if (!accepted || !result.gotNewToken) {
+            findings.push({
+                id: `${this.agentId}-refresh-failed`,
+                type: 'code-bug-logic',
+                severity: 'medium',
+                agentId: this.agentId,
+                module: 'localhost-walkthrough',
+                description: `Token refresh via ${refreshUrl} ${accepted ? `returned ${result.status} but issued no new access token / session cookie` : `failed with status ${result.status}`}. ` +
+                    `Sessions can't be extended — users will be logged out when the access token expires.`,
+            });
+        }
+        // Success (2xx + new token) is the happy path — stay silent.
+    }
+    /**
+     * Exercise the logout endpoint with the live session attached, then
+     * verify the session was actually invalidated. Skipped silently when
+     * no logout URL can be resolved.
+     *
+     * Findings:
+     *   - 88-logout-failed (medium, code-bug-logic): logout endpoint
+     *     returned an unexpected status (anything not 2xx/302).
+     *   - 88-session-not-invalidated (high, code-bug-security): the OLD
+     *     session still works on the login URL after logout — the server
+     *     didn't destroy it. Real session-fixation / sticky-session bug.
+     */
+    async runLogoutTest(session, routes, baseUrl, findings) {
+        const logoutUrl = findLogoutUrl(this.config.auth?.logoutUrl, routes, baseUrl);
+        if (!logoutUrl) {
+            // Silent — the user may not have a logout endpoint at all (token-only auth).
+            return;
+        }
+        const result = await attemptLogout(logoutUrl, session);
+        if (!result) {
+            // Network error — non-fatal, no finding.
+            return;
+        }
+        const accepted = (result.status >= 200 && result.status < 300) || result.status === 302;
+        if (!accepted) {
+            findings.push({
+                id: `${this.agentId}-logout-failed`,
+                type: 'code-bug-logic',
+                severity: 'medium',
+                agentId: this.agentId,
+                module: 'localhost-walkthrough',
+                description: `Logout endpoint (${logoutUrl}) returned ${result.status} — expected 2xx or 302.`,
+            });
+            return;
+        }
+        // Logout was accepted. Re-attempt with the same (now-stale) session and
+        // verify the server rejects it.
+        const invalidated = await verifySessionInvalidated(session.loginUrl, session);
+        if (invalidated === false) {
+            findings.push({
+                id: `${this.agentId}-session-not-invalidated`,
+                type: 'code-bug-security',
+                severity: 'high',
+                agentId: this.agentId,
+                module: 'localhost-walkthrough',
+                description: `After successful logout via ${logoutUrl}, the original session cookie/token still authenticates against ${session.loginUrl}. ` +
+                    `The server isn't destroying sessions on logout — anyone who captured the cookie (logs, browser history, MITM) can keep using it.`,
+            });
+        }
+        // invalidated === true → all good (silent pass)
+        // invalidated === null → network error verifying; don't flood findings
+    }
+    /**
+     * Probe the login endpoint with a wrong password. Wraps the pure
+     * `probeBadCredentials` helper so tests can stub the outcome without
+     * standing up an HTTP server.
+     */
+    async runBadCredentialsProbe(session) {
+        const creds = pickFirstCredential(this.config.auth?.credentials);
+        if (!creds)
+            return null;
+        return probeBadCredentials(session.loginUrl, creds.email, session.bodyKind);
+    }
+    persistAuthAttempt(attempt) {
+        try {
+            const evidenceDir = path.join(this.runDir, 'evidence');
+            fs.mkdirSync(evidenceDir, { recursive: true });
+            fs.writeFileSync(path.join(evidenceDir, 'auth-attempt.json'), JSON.stringify(attempt, null, 2), 'utf-8');
+            this.addEvidence({
+                type: 'report',
+                path: 'evidence/auth-attempt.json',
+                description: `Auth attempt: ${attempt.outcome} (${attempt.reason})`,
+            });
+        }
+        catch {
+            // non-fatal — auth is best-effort
+        }
+    }
+    /**
+     * Attempt a Stagehand-driven retry. Returns true if the runner was reachable,
+     * false if Stagehand isn't installed / configured (the typical case in a
+     * scaffold environment). This stays defensive — we never propagate Stagehand
+     * import failures up to the caller.
+     */
+    async tryStagehandFallback(url, moduleId) {
+        try {
+            const { createStagehandRunner, STAGEHAND_COST_CAP_USD } = await import('./stagehand-runner.js');
+            const runner = await createStagehandRunner({
+                phase: this.phase,
+                costCapUsd: STAGEHAND_COST_CAP_USD,
+            });
+            // Scaffold: we acknowledge the fallback engaged but don't drive a full
+            // act/observe loop here — that's #85's job. This is enough to record
+            // that the dep is reachable for the eventual cutover.
+            void url;
+            void moduleId;
+            void runner;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=88-localhost-walkthrough.js.map