settld 0.1.2 → 0.2.0

package/scripts/ci/run-circle-sandbox-smoke.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const ARTIFACT_PATH = path.resolve(process.cwd(), "artifacts/gates/x402-circle-sandbox-smoke.json");
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function readEnv(name, fallback = null) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === null || String(raw).trim() === "") return fallback;
+  return String(raw).trim();
+}
+
+function hasTruthyEnv(name) {
+  const value = readEnv(name, "");
+  if (!value) return false;
+  const normalized = value.toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+function parseJsonSafe(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function writeArtifact(value) {
+  ensureDir(ARTIFACT_PATH);
+  fs.writeFileSync(ARTIFACT_PATH, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function assertRequiredEnv() {
+  const required = ["CIRCLE_API_KEY", "CIRCLE_WALLET_ID_SPEND", "CIRCLE_WALLET_ID_ESCROW", "CIRCLE_TOKEN_ID_USDC"];
+  const missing = required.filter((name) => !readEnv(name));
+  if (missing.length > 0) {
+    throw new Error(`missing required env: ${missing.join(", ")}`);
+  }
+  const hasEntityProvider =
+    Boolean(readEnv("ENTITY_SECRET")) ||
+    Boolean(readEnv("CIRCLE_ENTITY_SECRET_HEX")) ||
+    Boolean(readEnv("CIRCLE_ENTITY_SECRET_CIPHERTEXT_TEMPLATE")) ||
+    (Boolean(readEnv("CIRCLE_ENTITY_SECRET_CIPHERTEXT")) && hasTruthyEnv("CIRCLE_ALLOW_STATIC_ENTITY_SECRET"));
+  if (!hasEntityProvider) {
+    throw new Error(
+      "missing entity secret provider: set ENTITY_SECRET/CIRCLE_ENTITY_SECRET_HEX, CIRCLE_ENTITY_SECRET_CIPHERTEXT_TEMPLATE, or CIRCLE_ENTITY_SECRET_CIPHERTEXT + CIRCLE_ALLOW_STATIC_ENTITY_SECRET=1"
+    );
+  }
+}
+
+async function callCircle({ method, endpoint, body = null }) {
+  const baseUrl = readEnv("CIRCLE_BASE_URL", "https://api.circle.com").replace(/\/+$/, "");
+  const apiKey = readEnv("CIRCLE_API_KEY", "");
+  const response = await fetch(`${baseUrl}${endpoint}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${apiKey}`,
+      accept: "application/json",
+      ...(body ? { "content-type": "application/json; charset=utf-8" } : {})
+    },
+    body: body ? JSON.stringify(body) : undefined
+  });
+  const text = await response.text();
+  const json = parseJsonSafe(text);
+  return { status: response.status, text, json };
+}
+
+async function requestFaucetTopup({ walletAddress, blockchain, native, usdc }) {
+  const out = await callCircle({
+    method: "POST",
+    endpoint: "/v1/faucet/drips",
+    body: {
+      address: walletAddress,
+      blockchain,
+      native: Boolean(native),
+      usdc: Boolean(usdc),
+      eurc: false
+    }
+  });
+  const accepted = out.status === 204 || out.status === 409 || out.status === 429 || out.status === 400;
+  return {
+    ok: accepted,
+    status: out.status,
+    body: out.json ?? out.text ?? null
+  };
+}
+
+async function resolveWalletAddress(walletId) {
+  const out = await callCircle({
+    method: "GET",
+    endpoint: `/v1/w3s/wallets/${encodeURIComponent(walletId)}`
+  });
+  if (out.status < 200 || out.status >= 300) {
+    throw new Error(`wallet lookup failed (${walletId}): HTTP ${out.status}`);
+  }
+  const payload = out.json ?? {};
+  const candidates = [payload, payload.wallet, payload.data, payload.data?.wallet];
+  if (Array.isArray(payload?.data?.wallets)) {
+    for (const row of payload.data.wallets) candidates.push(row);
+  }
+  for (const row of candidates) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    if (typeof row.address === "string" && row.address.trim() !== "") return row.address.trim();
+    if (typeof row.blockchainAddress === "string" && row.blockchainAddress.trim() !== "") return row.blockchainAddress.trim();
+  }
+  throw new Error(`wallet lookup did not include address (${walletId})`);
+}
+
+function runNodeTest({ label, testFile, env }) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    const child = spawn(process.execPath, ["--test", testFile], {
+      cwd: process.cwd(),
+      env: { ...process.env, ...env },
+      stdio: "inherit"
+    });
+    child.once("close", (code, signal) => {
+      resolve({
+        label,
+        testFile,
+        code,
+        signal,
+        ok: code === 0,
+        durationMs: Date.now() - startedAt
+      });
+    });
+  });
+}
+
+async function main() {
+  const startedAt = nowIso();
+  const report = {
+    schemaVersion: "X402CircleSandboxSmoke.v1",
+    ok: false,
+    startedAt,
+    completedAt: null,
+    steps: [],
+    errors: []
+  };
+
+  try {
+    assertRequiredEnv();
+
+    const circleMode = readEnv("X402_CIRCLE_RESERVE_MODE", readEnv("SETTLD_DEMO_CIRCLE_MODE", "sandbox"));
+    if (String(circleMode).toLowerCase() !== "sandbox") {
+      throw new Error(`expected sandbox mode, got ${circleMode}`);
+    }
+
+    const blockchain = readEnv("CIRCLE_BLOCKCHAIN", "BASE-SEPOLIA");
+    const spendWalletId = readEnv("CIRCLE_WALLET_ID_SPEND", "");
+    const escrowWalletId = readEnv("CIRCLE_WALLET_ID_ESCROW", "");
+    const spendAddress = await resolveWalletAddress(spendWalletId);
+    const escrowAddress = await resolveWalletAddress(escrowWalletId);
+
+    const shouldTopup = !hasTruthyEnv("CIRCLE_SKIP_TOPUP");
+    if (shouldTopup) {
+      const spendTopup = await requestFaucetTopup({
+        walletAddress: spendAddress,
+        blockchain,
+        native: true,
+        usdc: true
+      });
+      report.steps.push({ step: "faucet_topup_spend", ...spendTopup });
+
+      const escrowTopup = await requestFaucetTopup({
+        walletAddress: escrowAddress,
+        blockchain,
+        native: true,
+        usdc: false
+      });
+      report.steps.push({ step: "faucet_topup_escrow", ...escrowTopup });
+    } else {
+      report.steps.push({ step: "faucet_topup", skipped: true, reason: "CIRCLE_SKIP_TOPUP=1" });
+    }
+
+    const testEnv = {
+      CIRCLE_E2E: "1",
+      CIRCLE_BATCH_E2E: "1",
+      CIRCLE_E2E_AMOUNT_CENTS: readEnv("CIRCLE_E2E_AMOUNT_CENTS", "100"),
+      CIRCLE_BATCH_E2E_AMOUNT_CENTS: readEnv("CIRCLE_BATCH_E2E_AMOUNT_CENTS", "100")
+    };
+
+    const reserve = await runNodeTest({
+      label: "reserve_e2e",
+      testFile: "test/circle-sandbox-reserve-e2e.test.js",
+      env: testEnv
+    });
+    report.steps.push(reserve);
+    if (!reserve.ok) throw new Error("reserve e2e failed");
+
+    const batch = await runNodeTest({
+      label: "batch_settlement_e2e",
+      testFile: "test/circle-sandbox-batch-settlement-e2e.test.js",
+      env: testEnv
+    });
+    report.steps.push(batch);
+    if (!batch.ok) throw new Error("batch settlement e2e failed");
+
+    report.ok = true;
+  } catch (err) {
+    report.errors.push({
+      message: err?.message ?? String(err ?? "")
+    });
+    report.ok = false;
+  } finally {
+    report.completedAt = nowIso();
+    writeArtifact(report);
+    process.stdout.write(`wrote circle sandbox smoke report: ${ARTIFACT_PATH}\n`);
+  }
+
+  if (!report.ok) process.exitCode = 1;
+}
+
+main().catch((err) => {
+  const fallback = {
+    schemaVersion: "X402CircleSandboxSmoke.v1",
+    ok: false,
+    startedAt: nowIso(),
+    completedAt: nowIso(),
+    steps: [],
+    errors: [{ message: err?.message ?? String(err ?? "") }]
+  };
+  writeArtifact(fallback);
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(err)}\n`);
+  process.exitCode = 1;
+});

package/scripts/ci/run-go-live-gate.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { loadLighthouseTrackerFromPath } from "./lib/lighthouse-tracker.mjs";
+
+function parseBoolEnv(name, fallback = false) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === null || String(raw).trim() === "") return fallback;
+  const value = String(raw).trim().toLowerCase();
+  if (["1", "true", "yes", "y"].includes(value)) return true;
+  if (["0", "false", "no", "n"].includes(value)) return false;
+  throw new Error(`${name} must be boolean-like (true/false)`);
+}
+
+function runShell(command, { env = process.env } = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn("bash", ["-lc", command], { stdio: "inherit", env });
+    child.on("error", rejectPromise);
+    child.on("exit", (code) => resolvePromise(code ?? 1));
+  });
+}
+
+async function main() {
+  const reportPath = resolve(process.cwd(), process.env.GO_LIVE_GATE_REPORT_PATH || "artifacts/gates/s13-go-live-gate.json");
+  const throughputReportPath = resolve(
+    process.cwd(),
+    process.env.THROUGHPUT_REPORT_PATH || "artifacts/throughput/10x-drill-summary.json"
+  );
+  const incidentRehearsalReportPath = resolve(
+    process.cwd(),
+    process.env.THROUGHPUT_INCIDENT_REHEARSAL_REPORT_PATH || "artifacts/throughput/10x-incident-rehearsal-summary.json"
+  );
+  const lighthouseTrackerPath = resolve(
+    process.cwd(),
+    process.env.LIGHTHOUSE_TRACKER_PATH || "planning/launch/lighthouse-production-tracker.json"
+  );
+  await mkdir(dirname(reportPath), { recursive: true });
+
+  const runThroughput = parseBoolEnv("RUN_THROUGHPUT_DRILL", true);
+  const allowThroughputSkip = parseBoolEnv("ALLOW_THROUGHPUT_SKIP", false);
+  const runIncidentRehearsal = parseBoolEnv("RUN_INCIDENT_REHEARSAL", runThroughput);
+  const allowIncidentRehearsalSkip = parseBoolEnv("ALLOW_INCIDENT_REHEARSAL_SKIP", false);
+  const deterministicTestCommand =
+    process.env.GO_LIVE_TEST_COMMAND ||
+    "node --test test/settlement-kernel.test.js && node --test test/api-e2e-ops-money-rails.test.js && node --test test/api-e2e-ops-finance-net-close.test.js && node --test test/api-e2e-ops-arbitration-workspace.test.js && node --test test/api-e2e-ops-command-center.test.js && node --test test/api-e2e-billing-plan-enforcement.test.js";
+
+  const checks = [];
+  const startedAt = Date.now();
+
+  const deterministicStartedAt = Date.now();
+  const deterministicExitCode = await runShell(deterministicTestCommand);
+  checks.push({
+    id: "deterministic_critical_suite",
+    ok: deterministicExitCode === 0,
+    command: deterministicTestCommand,
+    exitCode: deterministicExitCode,
+    durationMs: Date.now() - deterministicStartedAt
+  });
+
+  if (runThroughput) {
+    const throughputCommand = "node scripts/ci/run-10x-throughput-drill.mjs";
+    const throughputStartedAt = Date.now();
+    const throughputExitCode = await runShell(throughputCommand, { env: process.env });
+    let throughputVerdictOk = throughputExitCode === 0;
+    let throughputSummary = null;
+    try {
+      throughputSummary = JSON.parse(await readFile(throughputReportPath, "utf8"));
+      throughputVerdictOk = throughputSummary?.verdict?.ok === true && throughputVerdictOk;
+    } catch (err) {
+      throughputVerdictOk = false;
+      throughputSummary = { error: err?.message ?? "unable to read throughput report" };
+    }
+    const throughputSkipped = allowThroughputSkip && throughputVerdictOk !== true;
+    checks.push({
+      id: "throughput_10x_drill",
+      ok: throughputSkipped ? true : throughputVerdictOk,
+      skipped: throughputSkipped,
+      command: throughputCommand,
+      exitCode: throughputExitCode,
+      durationMs: Date.now() - throughputStartedAt,
+      reportPath: throughputReportPath,
+      summary: throughputSummary
+    });
+  }
+
+  if (runIncidentRehearsal) {
+    const incidentRehearsalCommand = "node scripts/ci/run-10x-throughput-incident-rehearsal.mjs";
+    const incidentRehearsalStartedAt = Date.now();
+    const incidentRehearsalExitCode = await runShell(incidentRehearsalCommand, { env: process.env });
+    let incidentRehearsalVerdictOk = incidentRehearsalExitCode === 0;
+    let incidentRehearsalSummary = null;
+    try {
+      incidentRehearsalSummary = JSON.parse(await readFile(incidentRehearsalReportPath, "utf8"));
+      incidentRehearsalVerdictOk = incidentRehearsalSummary?.verdict?.ok === true && incidentRehearsalVerdictOk;
+    } catch (err) {
+      incidentRehearsalVerdictOk = false;
+      incidentRehearsalSummary = { error: err?.message ?? "unable to read incident rehearsal report" };
+    }
+    const incidentRehearsalSkipped = allowIncidentRehearsalSkip && incidentRehearsalVerdictOk !== true;
+    checks.push({
+      id: "throughput_incident_rehearsal",
+      ok: incidentRehearsalSkipped ? true : incidentRehearsalVerdictOk,
+      skipped: incidentRehearsalSkipped,
+      command: incidentRehearsalCommand,
+      exitCode: incidentRehearsalExitCode,
+      durationMs: Date.now() - incidentRehearsalStartedAt,
+      reportPath: incidentRehearsalReportPath,
+      summary: incidentRehearsalSummary
+    });
+  }
+
+  let lighthouse = null;
+  let lighthouseOk = false;
+  try {
+    lighthouse = await loadLighthouseTrackerFromPath(lighthouseTrackerPath);
+    lighthouseOk = lighthouse.ok === true;
+  } catch (err) {
+    lighthouse = { error: err?.message ?? "unable to load lighthouse tracker" };
+    lighthouseOk = false;
+  }
+  checks.push({
+    id: "lighthouse_customers_paid_production",
+    ok: lighthouseOk,
+    trackerPath: lighthouseTrackerPath,
+    summary: lighthouse
+  });
+
+  const overallOk = checks.every((check) => check.ok === true);
+  const report = {
+    schemaVersion: "GoLiveGateReport.v1",
+    generatedAt: new Date().toISOString(),
+    durationMs: Date.now() - startedAt,
+    checks,
+    verdict: {
+      ok: overallOk,
+      requiredChecks: checks.length,
+      passedChecks: checks.filter((check) => check.ok === true).length
+    }
+  };
+
+  await writeFile(reportPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+  process.stdout.write(`wrote go-live gate report: ${reportPath}\n`);
+  if (!overallOk) process.exitCode = 1;
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || err?.message || String(err)}\n`);
+  process.exit(1);
+});

package/scripts/ci/run-kernel-v0-ship-gate.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { spawn } from "node:child_process";
+
+function parseBoolEnv(name, fallback = false) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === null || String(raw).trim() === "") return fallback;
+  const value = String(raw).trim().toLowerCase();
+  if (["1", "true", "yes", "y"].includes(value)) return true;
+  if (["0", "false", "no", "n"].includes(value)) return false;
+  throw new Error(`${name} must be boolean-like (true/false)`);
+}
+
+function runShell(command, { env = process.env } = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn("bash", ["-lc", command], { stdio: "inherit", env });
+    child.on("error", rejectPromise);
+    child.on("exit", (code) => resolvePromise(code ?? 1));
+  });
+}
+
+async function runCheck(check, env) {
+  const startedAt = Date.now();
+  const exitCode = await runShell(check.command, { env });
+  return {
+    id: check.id,
+    ok: exitCode === 0,
+    command: check.command,
+    exitCode,
+    durationMs: Date.now() - startedAt
+  };
+}
+
+async function main() {
+  const reportPath = resolve(
+    process.cwd(),
+    process.env.KERNEL_V0_SHIP_GATE_REPORT_PATH || "artifacts/gates/kernel-v0-ship-gate.json"
+  );
+  const runQuickstart = parseBoolEnv("RUN_KERNEL_V0_QUICKSTART_SMOKE", true);
+  await mkdir(dirname(reportPath), { recursive: true });
+
+  const checks = [
+    {
+      id: "kernel_v0_truth_launch_claims",
+      command: "node scripts/ci/check-kernel-v0-launch-gate.mjs --mode prepublish"
+    },
+    {
+      id: "x402_core_e2e_suite",
+      command:
+        "node --test test/api-e2e-x402-authorize-payment.test.js test/api-e2e-x402-receipts.test.js test/api-e2e-x402-gate-reversal.test.js test/api-e2e-x402-wallet-issuer.test.js test/api-e2e-x402-provider-signature.test.js test/x402-gateway-autopay.test.js test/x402-receipt-verifier.test.js test/x402-receipt-store.test.js test/x402-wallet-issuer-decision.test.js test/x402-provider-refund-decision.test.js test/x402-reversal-command.test.js"
+    },
+    {
+      id: "api_sdk_contract_suite",
+      command:
+        "node --test test/api-r1-contract-freeze.test.js test/api-sdk-contract-freeze.test.js test/api-openapi.test.js"
+    }
+  ];
+
+  if (runQuickstart) {
+    checks.push({
+      id: "x402_quickstart_smoke",
+      command: "SETTLD_QUICKSTART_KEEP_ALIVE=0 npm run -s quickstart:x402"
+    });
+  }
+
+  const startedAt = Date.now();
+  const results = [];
+  for (const check of checks) {
+    const result = await runCheck(check, process.env);
+    results.push(result);
+    if (!result.ok) break;
+  }
+
+  const passedChecks = results.filter((row) => row.ok).length;
+  const allPassed = passedChecks === checks.length;
+  const report = {
+    schemaVersion: "KernelV0ShipGateReport.v1",
+    generatedAt: new Date().toISOString(),
+    durationMs: Date.now() - startedAt,
+    checks: results,
+    verdict: {
+      ok: allPassed,
+      requiredChecks: checks.length,
+      passedChecks
+    }
+  };
+
+  await writeFile(reportPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+  process.stdout.write(`wrote kernel v0 ship gate report: ${reportPath}\n`);
+  if (!allPassed) process.exitCode = 1;
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || err?.message || String(err)}\n`);
+  process.exit(1);
+});

package/scripts/ci/run-mcp-host-cert-matrix.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { runHostConfigSetup, SUPPORTED_HOSTS } from "../setup/host-config.mjs";
+
+const REPORT_SCHEMA_VERSION = "SettldMcpHostCertMatrix.v1";
+const DEFAULT_REPORT_PATH = path.resolve(process.cwd(), "artifacts/ops/mcp-host-cert-matrix.json");
+
+function parseArgs(argv) {
+  const out = { reportPath: DEFAULT_REPORT_PATH };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = String(argv[i] ?? "").trim();
+    if (!arg) continue;
+    if (arg === "--report") {
+      out.reportPath = path.resolve(process.cwd(), String(argv[i + 1] ?? "").trim());
+      i += 1;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      out.help = true;
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  return out;
+}
+
+function getServerNode(config, host) {
+  if (config && typeof config === "object") {
+    if (config.mcpServers && typeof config.mcpServers === "object" && config.mcpServers.settld) return config.mcpServers.settld;
+    if (config.servers && typeof config.servers === "object" && config.servers.settld) return config.servers.settld;
+    if (host === "openclaw" && typeof config.command === "string") return config;
+  }
+  return null;
+}
+
+function normalizeErrorCode(err) {
+  return typeof err?.code === "string" && err.code.trim() ? err.code.trim() : "ERROR";
+}
+
+async function runFailClosedBypassChecks({ host, configPath, env }) {
+  const checks = [];
+  const scenarios = [
+    {
+      id: "reject_missing_api_key",
+      expectedCode: "MISSING_ENV",
+      expectedMessageIncludes: "SETTLD_API_KEY",
+      buildEnv: () => {
+        const next = { ...env };
+        delete next.SETTLD_API_KEY;
+        return next;
+      }
+    },
+    {
+      id: "reject_invalid_base_url",
+      expectedCode: "INVALID_ENV",
+      expectedMessageIncludes: "SETTLD_BASE_URL must be a valid http(s) URL",
+      buildEnv: () => ({
+        ...env,
+        SETTLD_BASE_URL: "ftp://127.0.0.1:3000"
+      })
+    }
+  ];
+
+  for (const scenario of scenarios) {
+    try {
+      await runHostConfigSetup({
+        host,
+        configPath,
+        dryRun: true,
+        env: scenario.buildEnv()
+      });
+      checks.push({
+        id: scenario.id,
+        ok: false,
+        detail: "host config setup unexpectedly succeeded"
+      });
+    } catch (err) {
+      const observedCode = normalizeErrorCode(err);
+      const observedMessage = err?.message ?? String(err);
+      const matchesCode = observedCode === scenario.expectedCode;
+      const matchesMessage = observedMessage.includes(scenario.expectedMessageIncludes);
+      checks.push({
+        id: scenario.id,
+        ok: matchesCode && matchesMessage,
+        expectedCode: scenario.expectedCode,
+        observedCode,
+        observedMessage
+      });
+    }
+  }
+
+  return checks;
+}
+
+async function certHost({ host, rootDir }) {
+  const configPath = path.join(rootDir, `${host}.json`);
+  const env = {
+    SETTLD_BASE_URL: "http://127.0.0.1:3000",
+    SETTLD_TENANT_ID: "tenant_default",
+    SETTLD_API_KEY: "key_test.secret_test",
+    SETTLD_PAID_TOOLS_BASE_URL: "http://127.0.0.1:3005",
+    SETTLD_PAID_TOOLS_AGENT_PASSPORT: JSON.stringify({
+      schemaVersion: "X402AgentPassport.v1",
+      sponsorRef: "sponsor_local",
+      sponsorWalletRef: "wallet_local",
+      agentKeyId: "agent_key_local",
+      policyRef: "policy_local",
+      policyVersion: 1,
+      delegationDepth: 0
+    })
+  };
+
+  const first = await runHostConfigSetup({ host, configPath, dryRun: false, env });
+  const second = await runHostConfigSetup({ host, configPath, dryRun: false, env });
+
+  const parsed = JSON.parse(await fs.readFile(configPath, "utf8"));
+  const server = getServerNode(parsed, host);
+  if (!server || typeof server !== "object") {
+    throw new Error(`missing settld server entry for host ${host}`);
+  }
+  const envKeys = Object.keys(server.env ?? {});
+  if (!envKeys.includes("SETTLD_BASE_URL") || !envKeys.includes("SETTLD_TENANT_ID") || !envKeys.includes("SETTLD_API_KEY")) {
+    throw new Error(`incomplete env projection for host ${host}`);
+  }
+  if (second.changed !== false) {
+    throw new Error(`host config setup is not idempotent for host ${host} (second pass changed=true)`);
+  }
+
+  const bypassChecks = await runFailClosedBypassChecks({ host, configPath, env });
+  const bypassFailures = bypassChecks.filter((check) => check.ok !== true);
+  if (bypassFailures.length) {
+    const err = new Error(`host bridge bypass checks failed for host ${host}`);
+    err.details = {
+      bypassChecks
+    };
+    throw err;
+  }
+
+  return {
+    host,
+    ok: true,
+    configPath,
+    keyPath: first.keyPath,
+    firstChanged: first.changed,
+    secondChanged: second.changed,
+    envKeys,
+    bypassChecks
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write("usage:\n");
+    process.stdout.write("  node scripts/ci/run-mcp-host-cert-matrix.mjs [--report <path>]\n");
+    return;
+  }
+
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "settld-mcp-host-cert-"));
+  const checks = [];
+  let ok = true;
+
+  try {
+    for (const host of SUPPORTED_HOSTS) {
+      try {
+        const row = await certHost({ host, rootDir: tempRoot });
+        checks.push(row);
+      } catch (err) {
+        ok = false;
+        checks.push({
+          host,
+          ok: false,
+          error: err?.message ?? String(err),
+          details: err?.details ?? null
+        });
+      }
+    }
+  } finally {
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+
+  const report = {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    ok,
+    checks
+  };
+
+  await fs.mkdir(path.dirname(args.reportPath), { recursive: true });
+  await fs.writeFile(args.reportPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+
+  process.stdout.write(JSON.stringify({ ok, reportPath: args.reportPath }, null, 2) + "\n");
+  if (!ok) process.exitCode = 1;
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(err)}\n`);
+  process.exit(1);
+});