bootproof 0.3.0 → 0.4.1

package/dist/exec.js

@@ -1,26 +1,154 @@
 import { spawn, spawnSync } from "node:child_process";
 import http from "node:http";
-const TAIL = 4000;
-const tail = (s) => (s.length > TAIL ? s.slice(-TAIL) : s);
+import https from "node:https";
+import { redactText } from "./redact.js";
+const EVIDENCE_LIMIT = 4000;
+const head = (s) => (s.length > EVIDENCE_LIMIT ? s.slice(0, EVIDENCE_LIMIT) : s);
+const tail = (s) => (s.length > EVIDENCE_LIMIT ? s.slice(-EVIDENCE_LIMIT) : s);
+function meaningfulLines(evidenceHead, evidenceTail) {
+    return `${evidenceHead}\n${evidenceTail}`
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(line => line.length > 0 &&
+        !/^(?:from\s+)?\S+:\d+(?::in\b|$)/i.test(line) &&
+        !/^at\s+\S+/i.test(line) &&
+        !/^#\d+\s+/i.test(line));
+}
+function detectCause(text) {
+    const checks = [
+        [/(?:missing|no such file|does not exist|could not find)[^\n]*config\/database\.yml|config\/database\.yml[^\n]*(?:missing|no such file|does not exist|could not find)/i, "missing config/database.yml"],
+        [/(?:missing|no such file|does not exist|could not find)[^\n]*config\/gitlab\.yml|config\/gitlab\.yml[^\n]*(?:missing|no such file|does not exist|could not find)/i, "missing config/gitlab.yml"],
+        [/(?:PG::ConnectionBad|postgres(?:ql)?|port 5432)[^\n]*(?:connection refused|could not connect)|(?:connection refused|could not connect)[^\n]*(?:postgres(?:ql)?|port 5432)/i, "PostgreSQL connection refused"],
+        [/(?:postgres(?:ql)?[^\n]*)?role\s+["']?[^"'\n]+["']?\s+does not exist/i, "PostgreSQL role missing"],
+        [/(?:database schema|relation\s+\S+\s+does not exist|no such table|pending migrations?)/i, "database schema missing"],
+        [/(?:unsupported|not supported)[^\n]*(?:postgres(?:ql)?|database)[^\n]*version|(?:postgres(?:ql)?|database)[^\n]*version[^\n]*(?:unsupported|not supported)/i, "unsupported database version"],
+        [/(?:unsupported|not supported)[^\n]*database (?:config|configuration)|database (?:config|configuration)[^\n]*(?:unsupported|not supported)/i, "unsupported database configuration"],
+    ];
+    return checks.find(([pattern]) => pattern.test(text))?.[1];
+}
+export function extractProcessEvidence(evidenceHead, evidenceTail) {
+    const lines = meaningfulLines(evidenceHead, evidenceTail);
+    const firstExceptionLine = lines.find(line => /\b(?:[A-Z]\w*(?:::[A-Z]\w*)*(?:Error|Exception)|PG::\w+|ActiveRecord::\w+|Errno::\w+|RuntimeError|LoadError|NameError|NoMethodError)\b/.test(line));
+    const firstErrorLine = lines.find(line => /\b(?:error|fatal|failed|failure|refused|missing|unsupported|could not|cannot|no such file|does not exist)\b/i.test(line));
+    const combined = `${evidenceHead}\n${evidenceTail}`;
+    const detectedCause = detectCause(combined);
+    return {
+        evidenceHead,
+        evidenceTail,
+        ...(firstErrorLine ? { firstErrorLine: redactText(firstErrorLine).text } : {}),
+        ...(firstExceptionLine ? { firstExceptionLine: redactText(firstExceptionLine).text } : {}),
+        ...(detectedCause ? { detectedCause } : {}),
+    };
+}
+export function execResultEvidence(result) {
+    const evidenceHead = [result.stderrHead, result.stdoutHead].filter(Boolean).join("\n");
+    const evidenceTail = result.stderr || result.stdout;
+    return extractProcessEvidence(evidenceHead, evidenceTail);
+}
+export function processEvidenceText(evidence) {
+    return [
+        evidence.evidenceHead,
+        evidence.evidenceTail,
+        evidence.firstErrorLine ? `First error: ${evidence.firstErrorLine}` : "",
+        evidence.firstExceptionLine ? `First exception: ${evidence.firstExceptionLine}` : "",
+        evidence.detectedCause ? `Detected cause: ${evidence.detectedCause}` : "",
+    ].filter(Boolean).join("\n");
+}
+function setExecutionEnvValue(env, name, value) {
+    for (const existing of Object.keys(env)) {
+        if (existing !== name && existing.toLowerCase() === name.toLowerCase())
+            delete env[existing];
+    }
+    if (value === undefined)
+        delete env[name];
+    else
+        env[name] = value;
+}
+export function buildExecutionEnv(overrides = {}) {
+    const env = { ...process.env };
+    for (const name of ["PATH", "HOME", "SHELL"]) {
+        const inherited = Object.keys(process.env).find(existing => existing.toLowerCase() === name.toLowerCase());
+        if (inherited)
+            setExecutionEnvValue(env, name, process.env[inherited]);
+    }
+    setExecutionEnvValue(env, "CI", "true");
+    setExecutionEnvValue(env, "BOOTPROOF", "1");
+    for (const [name, value] of Object.entries(overrides)) {
+        setExecutionEnvValue(env, name, value);
+    }
+    return env;
+}
+export function extractLeadingEnvironmentAssignments(command) {
+    const environment = {};
+    let remaining = command;
+    while (true) {
+        const match = remaining.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)=(?:"([^"]*)"|'([^']*)'|([^\s;&|<>]+))\s+/);
+        if (!match)
+            break;
+        environment[match[1]] = match[2] ?? match[3] ?? match[4] ?? "";
+        remaining = remaining.slice(match[0].length);
+    }
+    if (!remaining.trim() || Object.keys(environment).length === 0) {
+        return { command, environment: {} };
+    }
+    return { command: remaining, environment };
+}
+function shellInvocation(command, env) {
+    if (process.platform !== "win32")
+        return { command, env: buildExecutionEnv(env) };
+    const extracted = extractLeadingEnvironmentAssignments(command);
+    return {
+        command: extracted.command,
+        env: buildExecutionEnv({ ...env, ...extracted.environment }),
+    };
+}
 export function runToCompletion(command, cwd, timeoutMs, env) {
     return new Promise(resolve => {
-        const child = spawn(command, { cwd, shell: true, detached: process.platform !== "win32", env });
-        let stdout = "", stderr = "", timedOut = false;
-        child.stdout?.on("data", d => (stdout += d));
-        child.stderr?.on("data", d => (stderr += d));
+        const invocation = shellInvocation(command, env);
+        const child = spawn(invocation.command, { cwd, shell: true, detached: process.platform !== "win32", env: invocation.env });
+        let stdoutHead = "", stdout = "", stderrHead = "", stderr = "", timedOut = false;
+        child.stdout?.on("data", d => {
+            const chunk = String(d);
+            stdoutHead = head(stdoutHead + chunk);
+            stdout = tail(stdout + chunk);
+        });
+        child.stderr?.on("data", d => {
+            const chunk = String(d);
+            stderrHead = head(stderrHead + chunk);
+            stderr = tail(stderr + chunk);
+        });
         const timer = setTimeout(() => { timedOut = true; killTree(child.pid); }, timeoutMs);
-        child.on("close", code => { clearTimeout(timer); resolve({ exitCode: code, timedOut, stdout: tail(stdout), stderr: tail(stderr) }); });
-        child.on("error", err => { clearTimeout(timer); resolve({ exitCode: null, timedOut, stdout: tail(stdout), stderr: tail(stderr + String(err)) }); });
+        child.on("close", code => { clearTimeout(timer); resolve({ exitCode: code, timedOut, stdoutHead, stdout, stderrHead, stderr }); });
+        child.on("error", err => {
+            clearTimeout(timer);
+            const error = String(err);
+            resolve({
+                exitCode: null,
+                timedOut,
+                stdoutHead,
+                stdout,
+                stderrHead: head(stderrHead + error),
+                stderr: tail(stderr + error),
+            });
+        });
     });
 }
 export function superviseApp(command, cwd, env) {
-    const child = spawn(command, { cwd, shell: true, detached: process.platform !== "win32", env });
-    let out = "", exit = null;
-    child.stdout?.on("data", d => (out += d));
-    child.stderr?.on("data", d => (out += d));
-    child.on("close", code => { exit = { code, early: true }; });
+    const invocation = shellInvocation(command, env);
+    const child = spawn(invocation.command, { cwd, shell: true, detached: process.platform !== "win32", env: invocation.env });
+    let outHead = "", outTail = "", exit = null;
+    const capture = (data) => {
+        const chunk = String(data);
+        outHead = head(outHead + chunk);
+        outTail = tail(outTail + chunk);
+    };
+    child.stdout?.on("data", capture);
+    child.stderr?.on("data", capture);
+    child.on("exit", code => { exit = { code, early: true }; });
+    child.on("error", () => { exit ??= { code: null, early: true }; });
     return {
-        output: () => tail(out),
+        output: () => outTail,
+        evidence: () => extractProcessEvidence(outHead, outTail),
         exited: () => exit,
         stop: async () => {
             if (exit)
@@ -40,13 +168,39 @@ function killTree(pid, signal = "SIGTERM") {
         return;
     try {
         if (process.platform === "win32") {
-            spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+            spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", env: buildExecutionEnv() });
         }
         else
             process.kill(-pid, signal); // negative pid = whole process group
     }
     catch { /* already gone */ }
 }
+const EXPECTED_REDIRECT_PATHS = ["/users/sign_in", "/login", "/signin", "/auth", "/session/new"];
+const BODY_EXCERPT_LIMIT = 1000;
+function acceptedAsHealthy(statusCode, redirectLocation) {
+    if (statusCode !== null && statusCode >= 200 && statusCode < 300)
+        return true;
+    if (statusCode === null || statusCode < 300 || statusCode >= 400 || !redirectLocation)
+        return false;
+    const normalizedLocation = redirectLocation.toLowerCase();
+    return EXPECTED_REDIRECT_PATHS.some(expected => normalizedLocation.includes(expected));
+}
+function normalizedHeaders(headers) {
+    const normalized = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        if (["authorization", "cookie", "proxy-authorization", "set-cookie"].includes(name.toLowerCase())) {
+            normalized[name] = "[redacted]";
+            continue;
+        }
+        normalized[name] = redactText(Array.isArray(value) ? value.join(", ") : value).text;
+    }
+    return normalized;
+}
+function connectionErrorMessage(error) {
+    return error.message || error.code || "connection failed";
+}
 function cleanUrl(value) {
     return value.replace(/[),.;\]}]+$/, "");
 }
@@ -63,47 +217,141 @@ export function extractHealthCandidates(output) {
     }
     return [...candidates];
 }
-export async function pollHealthCandidates(initialUrls, timeoutMs, output = () => "", intervalMs = 1000) {
+function effectivePort(url) {
+    if (url.port)
+        return url.port;
+    return url.protocol === "https:" ? "443" : url.protocol === "http:" ? "80" : "";
+}
+export function detectHealthCandidatePortMismatch(inferredHealthUrl, advertisedHealthUrls, selectedCommand) {
+    if (!inferredHealthUrl)
+        return null;
+    try {
+        const inferred = new URL(inferredHealthUrl);
+        for (const advertisedHealthUrl of advertisedHealthUrls) {
+            const advertised = new URL(advertisedHealthUrl);
+            const advertisedPort = effectivePort(advertised);
+            if (advertisedPort &&
+                effectivePort(inferred) !== advertisedPort) {
+                return {
+                    inferredHealthUrl,
+                    advertisedHealthUrl,
+                    advertisedPort,
+                    selectedCommand: redactText(selectedCommand).text,
+                };
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function healthCandidatePortMismatchEvidence(mismatch) {
+    if (!mismatch)
+        return "";
+    return [
+        "Health candidate port mismatch",
+        `inferredHealthUrl: ${mismatch.inferredHealthUrl}`,
+        `advertisedHealthUrl: ${mismatch.advertisedHealthUrl}`,
+        `advertisedPort: ${mismatch.advertisedPort}`,
+        `selectedCommand: ${mismatch.selectedCommand}`,
+    ].join("\n");
+}
+export async function pollHealthCandidates(initialUrls, timeoutMs, output = () => "", intervalMs = 1000, shouldStop = () => false) {
     const started = Date.now();
     let attempts = 0;
     const candidates = new Set(initialUrls);
     const discoveredCandidates = new Set();
-    while (Date.now() - started < timeoutMs) {
+    let latestResponse = null;
+    let latestConnectionError = null;
+    while (Date.now() - started < timeoutMs && !shouldStop()) {
         for (const candidate of extractHealthCandidates(output())) {
             if (!candidates.has(candidate))
                 discoveredCandidates.add(candidate);
             candidates.add(candidate);
         }
         for (const url of candidates) {
+            if (shouldStop())
+                break;
             attempts++;
-            const status = await probe(url);
-            if (status !== null) {
+            const evidence = await probe(url);
+            if (evidence.statusCode !== null)
+                latestResponse = evidence;
+            else if (evidence.connectionError || !latestConnectionError)
+                latestConnectionError = evidence;
+            if (evidence.acceptedAsHealthy) {
+                if (shouldStop())
+                    break;
                 return {
                     responded: true,
-                    status,
+                    status: evidence.statusCode,
                     attempts,
                     elapsedMs: Date.now() - started,
                     url,
                     candidates: [...candidates],
                     discoveredCandidates: [...discoveredCandidates],
+                    evidence,
                 };
             }
         }
-        await new Promise(r => setTimeout(r, intervalMs));
+        const waitUntil = Date.now() + intervalMs;
+        while (Date.now() < waitUntil && !shouldStop()) {
+            await new Promise(r => setTimeout(r, Math.min(25, waitUntil - Date.now())));
+        }
     }
     for (const candidate of extractHealthCandidates(output())) {
         if (!candidates.has(candidate))
             discoveredCandidates.add(candidate);
         candidates.add(candidate);
     }
+    const evidence = latestResponse ?? latestConnectionError;
     return {
-        responded: false,
-        status: null,
+        responded: evidence?.statusCode !== null && evidence?.statusCode !== undefined,
+        status: evidence?.statusCode ?? null,
         attempts,
         elapsedMs: Date.now() - started,
-        url: null,
+        url: evidence?.requestedUrl ?? null,
         candidates: [...candidates],
         discoveredCandidates: [...discoveredCandidates],
+        evidence,
+    };
+}
+export async function probeHealthCandidatesOnce(initialUrls) {
+    const started = Date.now();
+    const candidates = [...new Set(initialUrls)];
+    let attempts = 0;
+    let latestResponse = null;
+    let latestConnectionError = null;
+    for (const url of candidates) {
+        attempts++;
+        const evidence = await probe(url);
+        if (evidence.statusCode !== null)
+            latestResponse = evidence;
+        else if (evidence.connectionError || !latestConnectionError)
+            latestConnectionError = evidence;
+        if (evidence.acceptedAsHealthy) {
+            return {
+                responded: true,
+                status: evidence.statusCode,
+                attempts,
+                elapsedMs: Date.now() - started,
+                url,
+                candidates,
+                discoveredCandidates: [],
+                evidence,
+            };
+        }
+    }
+    const evidence = latestResponse ?? latestConnectionError;
+    return {
+        responded: evidence?.statusCode !== null && evidence?.statusCode !== undefined,
+        status: evidence?.statusCode ?? null,
+        attempts,
+        elapsedMs: Date.now() - started,
+        url: evidence?.requestedUrl ?? null,
+        candidates,
+        discoveredCandidates: [],
+        evidence,
     };
 }
 export function pollHealth(url, timeoutMs, intervalMs = 1000) {
@@ -111,32 +359,62 @@ export function pollHealth(url, timeoutMs, intervalMs = 1000) {
 }
 function probe(url) {
     return new Promise(resolve => {
-        const req = http.get(url, { timeout: 3000 }, res => { res.resume(); resolve(res.statusCode ?? null); });
-        req.on("timeout", () => { req.destroy(); resolve(null); });
-        req.on("error", () => resolve(null));
+        let settled = false;
+        const finish = (evidence) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(evidence);
+        };
+        const connectionFailure = (message) => ({
+            requestedUrl: url,
+            statusCode: null,
+            statusText: null,
+            headers: {},
+            redirectLocation: null,
+            bodyExcerpt: "",
+            timestamp: new Date().toISOString(),
+            acceptedAsHealthy: false,
+            connectionError: redactText(message).text,
+        });
+        let transport;
+        try {
+            transport = new URL(url).protocol === "https:" ? https : http;
+        }
+        catch (error) {
+            finish(connectionFailure(connectionErrorMessage(error)));
+            return;
+        }
+        const req = transport.get(url, { timeout: 3000 }, res => {
+            let bodyExcerpt = "";
+            res.setEncoding("utf8");
+            res.on("data", chunk => {
+                if (bodyExcerpt.length < BODY_EXCERPT_LIMIT) {
+                    bodyExcerpt += String(chunk).slice(0, BODY_EXCERPT_LIMIT - bodyExcerpt.length);
+                }
+            });
+            res.on("end", () => {
+                const statusCode = res.statusCode ?? null;
+                const headers = normalizedHeaders(res.headers);
+                const redirectLocation = headers.location ?? null;
+                finish({
+                    requestedUrl: url,
+                    statusCode,
+                    statusText: statusCode === null ? null : res.statusMessage || http.STATUS_CODES[statusCode] || null,
+                    headers,
+                    redirectLocation,
+                    bodyExcerpt: redactText(bodyExcerpt).text,
+                    timestamp: new Date().toISOString(),
+                    acceptedAsHealthy: acceptedAsHealthy(statusCode, redirectLocation),
+                    connectionError: null,
+                });
+            });
+            res.on("error", error => finish(connectionFailure(connectionErrorMessage(error))));
+        });
+        req.on("timeout", () => {
+            finish(connectionFailure("request timed out after 3000ms"));
+            req.destroy();
+        });
+        req.on("error", error => finish(connectionFailure(connectionErrorMessage(error))));
     });
 }
-export function minimalEnv(extra = {}) {
-    const keep = [
-        "PATH",
-        "HOME",
-        "USER",
-        "SHELL",
-        "TMPDIR",
-        "TEMP",
-        "LANG",
-        "TERM",
-        "NODE_OPTIONS",
-        "COREPACK_HOME",
-        "npm_config_cache",
-        "SystemRoot",
-        "SYSTEMROOT",
-        "ComSpec",
-        "PATHEXT",
-    ];
-    const env = {};
-    for (const k of keep)
-        if (process.env[k])
-            env[k] = process.env[k];
-    return { ...env, ...extra, CI: "true", BOOTPROOF: "1" };
-}

package/dist/external-health.d.ts

@@ -0,0 +1,16 @@
+import type { Attestation, ExternalVerificationClassification } from "./types.js";
+export interface ExternalHealthObservation {
+    requestedUrl: string;
+    statusCode: number | null;
+    statusText: string | null;
+    finalUrl: string;
+    headers: Record<string, string>;
+    redirectLocation: string | null;
+    responseSnippet: string;
+    observedAt: string;
+    classification: ExternalVerificationClassification;
+    verified: boolean;
+    connectionError: string | null;
+}
+export declare function observeExternalHealth(value: string, timeoutMs?: number): Promise<ExternalHealthObservation>;
+export declare function buildExternalHealthAttestation(repo: string, url: string, timeoutMs?: number): Promise<Attestation>;

package/dist/external-health.js

@@ -0,0 +1,214 @@
+import http from "node:http";
+import https from "node:https";
+import { buildAttestation } from "./proof.js";
+import { redactText } from "./redact.js";
+const RESPONSE_SNIPPET_LIMIT = 1000;
+const SENSITIVE_HEADER_NAME = /authorization|cookie|token|secret|api[-_]?key|password|passwd|credential|private[-_]?key|signature/i;
+const SENSITIVE_FIELD_NAME = String.raw `(?:access[_-]?token|refresh[_-]?token|token|secret|password|passwd|api[_-]?key|private[_-]?key|authorization|cookie|session)`;
+function parsedExternalUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`unsupported external health URL protocol: ${url.protocol}`);
+    }
+    if (url.username || url.password) {
+        throw new Error("external health URLs must not contain credentials");
+    }
+    return url;
+}
+function safeRecordedUrl(value) {
+    const url = new URL(value);
+    url.username = "";
+    url.password = "";
+    url.hash = "";
+    for (const name of new Set(url.searchParams.keys())) {
+        url.searchParams.set(name, "[redacted]");
+    }
+    return url.toString();
+}
+function safeRedirectLocation(location, baseUrl) {
+    try {
+        const sanitized = new URL(location, baseUrl);
+        const safe = safeRecordedUrl(sanitized);
+        if (location.startsWith("/")) {
+            const parsed = new URL(safe);
+            return `${parsed.pathname}${parsed.search}`;
+        }
+        return safe;
+    }
+    catch {
+        return redactText(location).text;
+    }
+}
+function redactExternalText(value) {
+    return redactText(value).text
+        .replace(new RegExp(`("${SENSITIVE_FIELD_NAME}"\\s*:\\s*)"(?:\\\\.|[^"\\\\])*"`, "gi"), '$1"[redacted]"')
+        .replace(new RegExp(`\\b(${SENSITIVE_FIELD_NAME}=)[^&\\s]+`, "gi"), "$1[redacted]");
+}
+function safeResponseHeaders(headers, baseUrl) {
+    const safe = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        if (SENSITIVE_HEADER_NAME.test(name)) {
+            safe[name] = "[redacted]";
+            continue;
+        }
+        const joined = Array.isArray(value) ? value.join(", ") : value;
+        safe[name] = name.toLowerCase() === "location"
+            ? safeRedirectLocation(joined, baseUrl)
+            : redactExternalText(joined);
+    }
+    return safe;
+}
+function requestOnce(url, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const transport = url.protocol === "https:" ? https : http;
+        const request = transport.get(url, { timeout: timeoutMs }, response => {
+            let responseSnippet = "";
+            response.setEncoding("utf8");
+            response.on("data", chunk => {
+                if (responseSnippet.length >= RESPONSE_SNIPPET_LIMIT)
+                    return;
+                responseSnippet += String(chunk).slice(0, RESPONSE_SNIPPET_LIMIT - responseSnippet.length);
+            });
+            response.on("end", () => {
+                const statusCode = response.statusCode ?? 0;
+                const headers = safeResponseHeaders(response.headers, url.toString());
+                resolve({
+                    requestedUrl: safeRecordedUrl(url),
+                    statusCode,
+                    statusText: response.statusMessage || http.STATUS_CODES[statusCode] || "",
+                    headers,
+                    redirectLocation: headers.location ?? null,
+                    responseSnippet: redactExternalText(responseSnippet).slice(0, RESPONSE_SNIPPET_LIMIT),
+                    observedAt: new Date().toISOString(),
+                });
+            });
+            response.on("error", reject);
+        });
+        request.on("timeout", () => {
+            request.destroy(new Error(`request timed out after ${timeoutMs}ms`));
+        });
+        request.on("error", reject);
+    });
+}
+export async function observeExternalHealth(value, timeoutMs = 5000) {
+    const initialUrl = parsedExternalUrl(value);
+    try {
+        const response = await requestOnce(initialUrl, timeoutMs);
+        const finalUrl = response.requestedUrl;
+        const authRequired = response.statusCode === 401 || response.statusCode === 403;
+        const verified = response.statusCode >= 200 && response.statusCode < 400;
+        const classification = authRequired
+            ? "auth_required"
+            : verified
+                ? "external_service_verified"
+                : "external_health_unreachable";
+        return {
+            requestedUrl: response.requestedUrl,
+            statusCode: response.statusCode,
+            statusText: response.statusText,
+            finalUrl,
+            headers: response.headers,
+            redirectLocation: response.redirectLocation,
+            responseSnippet: response.responseSnippet,
+            observedAt: response.observedAt,
+            classification,
+            verified,
+            connectionError: null,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            requestedUrl: safeRecordedUrl(initialUrl),
+            statusCode: null,
+            statusText: null,
+            finalUrl: safeRecordedUrl(initialUrl),
+            headers: {},
+            redirectLocation: null,
+            responseSnippet: "",
+            observedAt: new Date().toISOString(),
+            classification: "external_health_unreachable",
+            verified: false,
+            connectionError: redactExternalText(message),
+        };
+    }
+}
+function statusLabel(observation) {
+    if (observation.statusCode === null)
+        return "no HTTP response";
+    return `HTTP ${observation.statusCode}${observation.statusText ? ` ${observation.statusText}` : ""}`;
+}
+export async function buildExternalHealthAttestation(repo, url, timeoutMs = 5000) {
+    const startedAt = new Date().toISOString();
+    const observation = await observeExternalHealth(url, timeoutMs);
+    const status = statusLabel(observation);
+    const healthEvidence = {
+        requestedUrl: observation.requestedUrl,
+        statusCode: observation.statusCode,
+        statusText: observation.statusText,
+        headers: observation.headers,
+        redirectLocation: observation.redirectLocation,
+        bodyExcerpt: observation.responseSnippet,
+        timestamp: observation.observedAt,
+        acceptedAsHealthy: observation.verified,
+        connectionError: observation.connectionError,
+    };
+    const explanation = observation.verified
+        ? `Observed ${status} from an externally managed service. BootProof did not start or orchestrate the service.`
+        : observation.classification === "auth_required"
+            ? `Observed ${status}; authentication is required, so external health was not fully verified. BootProof did not start or orchestrate the service.`
+            : `External health was not verified: ${observation.connectionError ?? status}. BootProof did not start or orchestrate the service.`;
+    return buildAttestation({
+        repo,
+        plan: {
+            provider: "local",
+            steps: [{
+                    id: "external-health",
+                    kind: "health",
+                    description: "Observe an externally managed HTTP health endpoint",
+                    required: true,
+                }],
+            healthUrl: observation.requestedUrl,
+            healthCandidates: [observation.requestedUrl],
+            observedPort: observation.statusCode === null
+                ? null
+                : Number(new URL(observation.finalUrl).port || (new URL(observation.finalUrl).protocol === "https:" ? 443 : 80)),
+            healthCandidateSource: observation.statusCode === null ? "inferred" : "observed",
+            generatedFiles: [],
+        },
+        observed: [{
+                id: "external-health",
+                kind: "health",
+                startedAt,
+                finishedAt: observation.observedAt,
+                exitCode: null,
+                ok: observation.verified,
+                observation: observation.verified
+                    ? `${status} observed at ${observation.finalUrl}; service ownership is external`
+                    : `${observation.classification}: ${observation.connectionError ?? status}; service ownership is external`,
+            }],
+        startedAt,
+        booted: false,
+        healthVerified: observation.verified,
+        healthObservation: observation.verified ? `${status} at ${observation.finalUrl}` : null,
+        healthEvidence,
+        observedHealthCandidates: [observation.requestedUrl],
+        failureClass: observation.classification === "external_service_verified"
+            ? null
+            : observation.classification,
+        failureEvidence: observation.verified
+            ? null
+            : observation.connectionError ?? `${status} at ${observation.finalUrl}`,
+        explanation,
+        verificationMode: "external-health",
+        bootproofOrchestrated: false,
+        externalHealthUrl: observation.requestedUrl,
+        observedStatus: observation.statusCode,
+        observedFinalUrl: observation.finalUrl,
+        observedAt: observation.observedAt,
+        responseSnippet: observation.responseSnippet,
+        classification: observation.classification,
+    });
+}