server.mjs

// server.mjs
import express from "express";
import crypto from "crypto";
import fs from "node:fs";
import Ajv from "ajv";
import addFormats from "ajv-formats";
import { ethers } from "ethers";
import net from "net";

// Runtime-core is the single cryptographic source of truth
import {
  CANONICAL_ID_SORTED_KEYS_V1,
  signReceiptEd25519Sha256,
  verifyReceiptEd25519Sha256,
} from "@commandlayer/runtime-core";

/**
 * Notes
 * - Node 18+ provides global fetch. Node 22 definitely does.
 * - This runtime is deterministic (non-LLM reference verbs).
 * - Receipt signing is attempted for verb routes when signer config is valid.
 * - Receipt verification can use env pubkey OR ENS (optional).
 */

// -----------------------
// env helpers (allow legacy aliases)
// -----------------------
function envAny(...names) {
  for (const n of names) {
    const v = process.env[n];
    if (v && String(v).trim()) return String(v).trim();
  }
  return null;
}

function envFlag(name) {
  return String(process.env[name] || "0") === "1";
}

// -----------------------
// instance identity + crash logging
// -----------------------
const BOOTED_AT = Date.now();
const uptimeMs = () => Date.now() - BOOTED_AT;
const instancePayload = () => ({ instance: { uptime_ms: uptimeMs() } });

process.on("unhandledRejection", (reason) => {
  // log but do not crash the process; handlers catch and return JSON
  console.error("[fatal] unhandledRejection", reason);
});
process.on("uncaughtException", (err) => {
  console.error("[fatal] uncaughtException", err);
});

// -----------------------
// app + basic middleware
// -----------------------
const app = express();
app.use(express.json({ limit: "2mb" }));

// Force JSON errors (prevents Express HTML error pages)
app.use((err, req, res, next) => {
  if (err) {
    return res.status(400).json({
      ok: false,
      error: "invalid_json",
      message: err.message,
      ...instancePayload(),
    });
  }
  next();
});

// basic CORS (no deps)
app.use((req, res, next) => {
  res.setHeader("Access-Control-Allow-Origin", "*");
  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Debug-Token");
  res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
  if (req.method === "OPTIONS") return res.status(204).end();
  next();
});

const HOST = String(process.env.HOST || "0.0.0.0");
const PORT = Number(process.env.PORT || 8080);

// -----------------------
// runtime config
// -----------------------
const ENABLED_VERBS = (
  process.env.ENABLED_VERBS ||
  "fetch,describe,format,clean,parse,summarize,convert,explain,analyze,classify"
)
  .split(",")
  .map((s) => s.trim())
  .filter(Boolean);

const DEV_AUTO_KEYS = envFlag("DEV_AUTO_KEYS");

function envAnySource(...names) {
  for (const n of names) {
    const v = process.env[n];
    if (v && String(v).trim()) return { name: n, value: String(v).trim() };
  }
  return null;
}

const runtimeConfig = {
  signerId: String(envAny("CL_RECEIPT_SIGNER_ID", "RECEIPT_SIGNER_ID", "CL_RECEIPT_SIGNER") || "").trim(),
  privateKeySource: envAnySource(
    "CL_RECEIPT_SIGNING_PRIVATE_KEY_PEM",
    "RECEIPT_SIGNING_PRIVATE_KEY_PEM",
    "CL_RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64",
    "RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64",
    "CL_RECEIPT_SIGNING_PRIVATE_KEY_B64",
    "RECEIPT_SIGNING_PRIVATE_KEY_B64",
    "CL_RECEIPT_SIGNING_PRIVATE_KEY_PEM_FILE",
    "CL_PRIVATE_KEY_PEM",
    "CL_PRIVATE_KEY_PEM_B64"
  ),
  publicKeySource: envAnySource(
    "CL_RECEIPT_SIGNING_PUBLIC_KEY_B64",
    "RECEIPT_SIGNING_PUBLIC_KEY_B64",
    "CL_RECEIPT_SIGNING_PUBLIC_KEY_PEM",
    "RECEIPT_SIGNING_PUBLIC_KEY_PEM",
    "CL_RECEIPT_SIGNING_PUBLIC_KEY_PEM_B64",
    "RECEIPT_SIGNING_PUBLIC_KEY_PEM_B64",
    "CL_RECEIPT_SIGNING_PUBLIC_KEY_PEM_FILE",
    "CL_PUBLIC_KEY_B64",
    "RECEIPT_SIGNING_PUBLIC_KEY_RAW32_B64"
  ),
  canonicalId: CANONICAL_ID_SORTED_KEYS_V1,
  kid: "",
  signerSource: "missing",
  publicKeyRaw32: null,
  publicKeyPemOptional: null,
  ethRpcUrl: String(envAny("ETH_RPC_URL") || "").trim(),
};

// service identity / discovery
const SERVICE_NAME = process.env.SERVICE_NAME || "commandlayer-runtime";
const SERVICE_VERSION = process.env.SERVICE_VERSION || "1.0.0";
const CANONICAL_BASE = (process.env.CANONICAL_BASE_URL || "https://runtime.commandlayer.org").replace(/\/+$/, "");
const API_VERSION = process.env.API_VERSION || "1.0.0";

// ENS verifier config
const ETH_RPC_URL = runtimeConfig.ethRpcUrl;

// TXT keys (defaults match your records)
const ENS_SIG_PUB_KEY = process.env.ENS_SIG_PUB_KEY || "cl.sig.pub";
const ENS_SIG_KID_KEY = process.env.ENS_SIG_KID_KEY || "cl.sig.kid";
const ENS_SIG_CANONICAL_KEY = process.env.ENS_SIG_CANONICAL_KEY || "cl.sig.canonical";

// AJV schema validation host
const SCHEMA_HOST = (process.env.SCHEMA_HOST || "https://www.commandlayer.org").replace(/\/+$/, "");
const SCHEMA_FETCH_TIMEOUT_MS = Number(process.env.SCHEMA_FETCH_TIMEOUT_MS || 15000);
const SCHEMA_VALIDATE_BUDGET_MS = Number(process.env.SCHEMA_VALIDATE_BUDGET_MS || 15000);

// scaling + safety knobs
const MAX_JSON_CACHE_ENTRIES = Number(process.env.MAX_JSON_CACHE_ENTRIES || 256);
const JSON_CACHE_TTL_MS = Number(process.env.JSON_CACHE_TTL_MS || 10 * 60 * 1000);
const MAX_VALIDATOR_CACHE_ENTRIES = Number(process.env.MAX_VALIDATOR_CACHE_ENTRIES || 128);
const VALIDATOR_CACHE_TTL_MS = Number(process.env.VALIDATOR_CACHE_TTL_MS || 30 * 60 * 1000);
const SERVER_MAX_HANDLER_MS = Number(process.env.SERVER_MAX_HANDLER_MS || 12000);

// fetch hardening
const FETCH_TIMEOUT_MS = Number(process.env.FETCH_TIMEOUT_MS || 8000);
const FETCH_MAX_BYTES = Number(process.env.FETCH_MAX_BYTES || 256 * 1024);
const ENABLE_SSRF_GUARD = String(process.env.ENABLE_SSRF_GUARD || "1") === "1";
const ALLOW_FETCH_HOSTS = (process.env.ALLOW_FETCH_HOSTS || "")
  .split(",")
  .map((s) => s.trim().toLowerCase())
  .filter(Boolean);

// verify hardening
const VERIFY_MAX_MS = Number(process.env.VERIFY_MAX_MS || 30000);

// edge-safe schema verify (returns 202 until validator warmed)
const VERIFY_SCHEMA_CACHED_ONLY = String(process.env.VERIFY_SCHEMA_CACHED_ONLY || "1") === "1";

// prewarm knobs
const PREWARM_MAX_VERBS = Number(process.env.PREWARM_MAX_VERBS || 25);
const PREWARM_TOTAL_BUDGET_MS = Number(process.env.PREWARM_TOTAL_BUDGET_MS || 12000);
const PREWARM_PER_VERB_BUDGET_MS = Number(process.env.PREWARM_PER_VERB_BUDGET_MS || 5000);

// debug gating
const ENABLE_DEBUG = String(process.env.ENABLE_DEBUG || "0") === "1";
const DEBUG_TOKEN = process.env.DEBUG_TOKEN || "";

function requireDebug(req, res, next) {
  if (!ENABLE_DEBUG) return res.status(404).end();
  if (!DEBUG_TOKEN) return res.status(404).end();

  const auth = String(req.headers.authorization || "");
  const xTok = String(req.headers["x-debug-token"] || "");
  const bearer = auth.toLowerCase().startsWith("bearer ") ? auth.slice(7).trim() : "";
  const ok = (bearer && bearer === DEBUG_TOKEN) || (xTok && xTok === DEBUG_TOKEN);

  if (!ok) return res.status(404).end();
  next();
}

function nowIso() {
  return new Date().toISOString();
}

function normalizePemLoose(input) {
  if (!input) return null;
  // Support single-line .env values like "...\\n..." by converting literal backslash-n into newline.
  let s = String(input).replace(/\\n/g, "\n").trim();

  const begin = s.match(/-----BEGIN [^-]+-----/);
  const end = s.match(/-----END [^-]+-----/);
  if (!begin || !end) return null;

  const type = begin[0].replace("-----BEGIN ", "").replace("-----", "").trim();
  const body = s
    .replace(/-----BEGIN [^-]+-----/g, "")
    .replace(/-----END [^-]+-----/g, "")
    .replace(/[\r\n\s]/g, "")
    .trim();

  if (!body || !/^[A-Za-z0-9+/=]+$/.test(body)) return null;

  const wrapped = body.match(/.{1,64}/g)?.join("\n") || body;
  return `-----BEGIN ${type}-----\n${wrapped}\n-----END ${type}-----`;
}

function decodeB64Strict(s) {
  try {
    const cleaned0 = String(s || "").replace(/\s+/g, "");
    if (!cleaned0) return null;

    let cleaned = cleaned0.replace(/-/g, "+").replace(/_/g, "/");
    const pad = cleaned.length % 4;
    if (pad) cleaned += "=".repeat(4 - pad);

    const out = Buffer.from(cleaned, "base64");
    if (!out.length) return null;
    return out;
  } catch {
    return null;
  }
}

function getPrivatePemFromEnv() {
  const src = runtimeConfig.privateKeySource;
  if (!src) return null;
  if (src.name.endsWith("_PEM")) return normalizePemLoose(src.value);
  if (src.name.endsWith("_PEM_FILE")) {
    try {
      return normalizePemLoose(fs.readFileSync(src.value, "utf8"));
    } catch {
      return null;
    }
  }
  const decoded = decodeB64Strict(src.value);
  return normalizePemLoose(decoded?.toString("utf8") || "");
}

function deriveKidFromRaw32(raw32) {
  if (!raw32 || raw32.length !== 32) return "";
  return crypto.createHash("sha256").update(raw32).digest("base64url").slice(0, 16);
}

function shortFingerprint(raw32) {
  if (!raw32 || raw32.length !== 32) return null;
  return crypto.createHash("sha256").update(raw32).digest("hex").slice(0, 16);
}

function isPkcs8PrivatePem(pem) {
  return /-----BEGIN PRIVATE KEY-----/.test(String(pem || ""));
}

function validatePrivateKeyPem(pem) {
  if (!pem || !isPkcs8PrivatePem(pem)) return { ok: false, reason: "private key must be PKCS8 PEM (BEGIN PRIVATE KEY)" };
  try {
    const k = crypto.createPrivateKey({ key: pem, format: "pem" });
    if (k.asymmetricKeyType !== "ed25519") return { ok: false, reason: "private key must be Ed25519" };
    return { ok: true };
  } catch (e) {
    return { ok: false, reason: e?.message || "invalid private key PEM" };
  }
}

// Convert `ed25519:<base64>` into a PEM SPKI public key.
// SPKI DER for Ed25519: 302a300506032b6570032100 || <32-byte pubkey>
function ed25519RawToSpkiDer(raw32) {
  if (!raw32 || raw32.length !== 32) throw new Error("ed25519 pubkey must be 32 bytes");
  const prefix = Buffer.from("302a300506032b6570032100", "hex");
  return Buffer.concat([prefix, Buffer.from(raw32)]);
}

function spkiDerToPem(der) {
  const b64 = Buffer.from(der).toString("base64");
  const wrapped = b64.match(/.{1,64}/g)?.join("\n") || b64;
  return `-----BEGIN PUBLIC KEY-----\n${wrapped}\n-----END PUBLIC KEY-----`;
}

function publicKeyRaw32FromSpkiDer(der) {
  const buf = Buffer.from(der);
  if (buf.length < 32) throw new Error("invalid spki der length");
  return buf.subarray(buf.length - 32);
}

function getPublicPemFromEnv() {
  const src = runtimeConfig.publicKeySource;
  if (!src) return null;

  if (src.name.endsWith("_PUBLIC_KEY_B64") || src.name.endsWith("_RAW32_B64")) {
    const raw = decodeB64Strict(src.value);
    if (!raw || raw.length !== 32) return null;
    runtimeConfig.publicKeyRaw32 = Buffer.from(raw);
    return spkiDerToPem(ed25519RawToSpkiDer(raw));
  }

  if (src.name.endsWith("_PEM") || src.name.endsWith("_PEM_FILE") || src.name.endsWith("_PEM_B64")) {
    let pem = null;
    if (src.name.endsWith("_PEM")) pem = normalizePemLoose(src.value);
    else if (src.name.endsWith("_PEM_FILE")) {
      try {
        pem = normalizePemLoose(fs.readFileSync(src.value, "utf8"));
      } catch {
        pem = null;
      }
    } else {
      pem = normalizePemLoose(decodeB64Strict(src.value)?.toString("utf8") || "");
    }

    if (!pem) return null;

    const pub = crypto.createPublicKey({ key: pem, format: "pem" });
    if (pub.asymmetricKeyType !== "ed25519") return null;

    const der = pub.export({ type: "spki", format: "der" });
    const raw = publicKeyRaw32FromSpkiDer(der);
    runtimeConfig.publicKeyRaw32 = Buffer.from(raw);
    runtimeConfig.publicKeyPemOptional = pem;
    return spkiDerToPem(der);
  }

  return null;
}

function assertBootConfigOrThrow() {
  if (DEV_AUTO_KEYS) return;

  const missing = [];
  if (!runtimeConfig.signerId) missing.push("CL_RECEIPT_SIGNER_ID|RECEIPT_SIGNER_ID");
  if (!runtimeConfig.privateKeySource) missing.push("receipt signing private key env var");
  if (!runtimeConfig.publicKeySource) missing.push("receipt signing public key env var");

  if (missing.length) throw new Error(`Missing required env var(s): ${missing.join(", ")}`);
}

function validatePublicKeyPem(pem) {
  if (!pem) return { ok: false, reason: "missing public key" };
  try {
    const k = crypto.createPublicKey({ key: pem, format: "pem" });
    if (k.asymmetricKeyType !== "ed25519") return { ok: false, reason: "public key must be Ed25519" };
    return { ok: true };
  } catch (e) {
    return { ok: false, reason: e?.message || "invalid public key" };
  }
}

function escapedOneLinePem(pem) {
  return String(pem || "").replace(/\n/g, "\\n");
}

function printEnsTxtValues({ pubRaw32B64, kid, canonicalId, signerId }) {
  if (!pubRaw32B64) return;
  console.log("ENS TXT values to set");
  console.log(`cl.sig.pub = ed25519:${pubRaw32B64}`);
  console.log(`cl.sig.kid = ${kid}`);
  console.log(`cl.sig.canonical = ${canonicalId}`);
  console.log(`cl.receipt.signer = ${signerId || "runtime.commandlayer.eth"} (optional)`);
}

const activeSigner = {
  privateKeyPem: null,
  publicKeyRaw32B64: "",
  publicKeyPem: null,
  publicKeyRaw32: null,
  publicKeyFingerprint: null,
  source: "missing",
};

const signerBootState = {
  ok: false,
  errors: [],
};

function getActivePrivatePem() {
  return activeSigner.privateKeyPem || null;
}

function getActivePublicPem() {
  return activeSigner.publicKeyPem || null;
}

function maybeEnableDevAutoKeys() {
  const missingPrivate = !activeSigner.privateKeyPem;
  const missingPublic = !activeSigner.publicKeyPem;
  if (!DEV_AUTO_KEYS || (!missingPrivate && !missingPublic)) return;

  const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519");
  const privatePem = privateKey.export({ type: "pkcs8", format: "pem" });
  const spkiDer = publicKey.export({ type: "spki", format: "der" });
  const raw32 = publicKeyRaw32FromSpkiDer(spkiDer);
  const raw32B64 = raw32.toString("base64");

  activeSigner.privateKeyPem = String(privatePem);
  activeSigner.publicKeyRaw32B64 = raw32B64;
  activeSigner.publicKeyRaw32 = Buffer.from(raw32);
  activeSigner.publicKeyPem = spkiDerToPem(spkiDer);
  activeSigner.publicKeyFingerprint = shortFingerprint(raw32);
  activeSigner.source = "dev_auto_keys";
  runtimeConfig.kid = deriveKidFromRaw32(raw32);
  runtimeConfig.signerSource = "dev_auto_keys";

  console.warn("DEV_AUTO_KEYS=1 enabled; generated in-memory temporary Ed25519 keypair.");
  console.warn(`TEMP PRIVATE KEY PEM (set RECEIPT_SIGNING_PRIVATE_KEY_PEM): ${escapedOneLinePem(activeSigner.privateKeyPem)}`);
  console.warn(`TEMP PUBLIC RAW32 B64 (set RECEIPT_SIGNING_PUBLIC_KEY_B64): ${activeSigner.publicKeyRaw32B64}`);
  printEnsTxtValues({
    pubRaw32B64: activeSigner.publicKeyRaw32B64,
    kid: runtimeConfig.kid,
    canonicalId: runtimeConfig.canonicalId,
    signerId: runtimeConfig.signerId,
  });
}

function initializeSignerConfigOrThrow() {
  signerBootState.errors = [];

  try {
    assertBootConfigOrThrow();
  } catch (e) {
    signerBootState.errors.push(String(e?.message || e));
  }

  const maybePrivatePem = getPrivatePemFromEnv();
  const privateCheck = validatePrivateKeyPem(maybePrivatePem);
  if (!privateCheck.ok) signerBootState.errors.push(`private_key: ${privateCheck.reason}`);
  else activeSigner.privateKeyPem = maybePrivatePem;

  const envPublicPem = getPublicPemFromEnv();
  const publicCheck = validatePublicKeyPem(envPublicPem);
  if (!publicCheck.ok) signerBootState.errors.push(`public_key: ${publicCheck.reason}`);
  else {
    activeSigner.publicKeyPem = envPublicPem;
    if (runtimeConfig.publicKeyRaw32) {
      activeSigner.publicKeyRaw32 = Buffer.from(runtimeConfig.publicKeyRaw32);
      activeSigner.publicKeyRaw32B64 = activeSigner.publicKeyRaw32.toString("base64");
      activeSigner.publicKeyFingerprint = shortFingerprint(activeSigner.publicKeyRaw32);
      runtimeConfig.kid = deriveKidFromRaw32(activeSigner.publicKeyRaw32);
      runtimeConfig.signerSource = "env";
      activeSigner.source = "env";
    }
  }

  if (!activeSigner.privateKeyPem || !activeSigner.publicKeyPem) {
    maybeEnableDevAutoKeys();
  }

  if (activeSigner.privateKeyPem && activeSigner.publicKeyPem && activeSigner.source === "dev_auto_keys") {
    signerBootState.errors = [];
  }

  if (!activeSigner.privateKeyPem || !activeSigner.publicKeyPem) {
    signerBootState.errors.push(
      "Invalid signer config: provide RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64 and RECEIPT_SIGNING_PUBLIC_KEY_B64 (or supported CL_/legacy aliases)"
    );
  }

  signerBootState.ok = !!activeSigner.privateKeyPem && !!activeSigner.publicKeyPem && signerBootState.errors.length === 0;

  if (!signerBootState.ok) {
    console.error("[boot] signer config invalid", signerBootState.errors);
    if (!DEV_AUTO_KEYS) {
      const reason = signerBootState.errors.join("; ") || "invalid signer configuration";
      console.error(`[boot] fatal signer misconfiguration: ${reason}`);
      process.exit(1);
    }
  }

  console.log(
    `[boot] signer_ok=${signerBootState.ok} signer_source=${activeSigner.source} kid=${runtimeConfig.kid} fp=${
      activeSigner.publicKeyFingerprint || "n/a"
    }`
  );

  printEnsTxtValues({
    pubRaw32B64: activeSigner.publicKeyRaw32B64,
    kid: runtimeConfig.kid,
    canonicalId: runtimeConfig.canonicalId,
    signerId: runtimeConfig.signerId,
  });
}

function enabled(verb) {
  return ENABLED_VERBS.includes(verb);
}

function makeError(code, message, extra = {}) {
  return { status: "error", code, message, ...extra };
}

function requireBody(req, res) {
  if (!req.body || typeof req.body !== "object") {
    res.status(400).json({ ...makeError(400, "Invalid JSON body"), ...instancePayload() });
    return false;
  }
  return true;
}

// -----------------------
// SSRF guard for fetch()
// -----------------------
function isPrivateIp(ip) {
  if (!net.isIP(ip)) return false;
  if (net.isIP(ip) === 6) return true; // block ipv6 by default
  const parts = ip.split(".").map((n) => Number(n));
  const [a, b] = parts;
  if (a === 10) return true;
  if (a === 127) return true;
  if (a === 169 && b === 254) return true;
  if (a === 172 && b >= 16 && b <= 31) return true;
  if (a === 192 && b === 168) return true;
  if (a === 0) return true;
  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT
  return false;
}

async function resolveARecords(hostname) {
  const dns = await import("dns/promises");
  try {
    const addrs = await dns.resolve4(hostname);
    return Array.isArray(addrs) ? addrs : [];
  } catch {
    return [];
  }
}

async function ssrfGuardOrThrow(urlStr) {
  if (!ENABLE_SSRF_GUARD) return;

  let u;
  try {
    u = new URL(urlStr);
  } catch {
    throw new Error("fetch requires a valid absolute URL");
  }

  if (!/^https?:$/.test(u.protocol)) throw new Error("fetch only allows http(s)");
  const host = (u.hostname || "").toLowerCase();

  if (ALLOW_FETCH_HOSTS.length) {
    const ok = ALLOW_FETCH_HOSTS.some((h) => host === h || host.endsWith("." + h));
    if (!ok) throw new Error("fetch host not allowed");
  }

  if (host === "localhost" || host.endsWith(".localhost")) throw new Error("fetch host blocked");
  if (host === "169.254.169.254") throw new Error("fetch host blocked");
  if (net.isIP(host) && isPrivateIp(host)) throw new Error("fetch to private IP blocked");

  const addrs = await resolveARecords(host);
  if (addrs.some(isPrivateIp)) throw new Error("fetch DNS resolves to private IP (blocked)");
}

// -----------------------
// ENS helpers (ethers v6)
// -----------------------
function hasRpc() {
  return !!ETH_RPC_URL;
}

async function withTimeout(promise, ms, label = "timeout") {
  if (!ms || ms <= 0) return await promise;
  return await Promise.race([promise, new Promise((_, rej) => setTimeout(() => rej(new Error(label)), ms))]);
}

function parseEd25519Txt(txt) {
  if (!txt) return null;
  const s = String(txt).trim();
  const m = s.match(/^ed25519:([A-Za-z0-9+/_=-]+)$/i);
  if (!m) return null;
  const raw = decodeB64Strict(m[1]);
  if (!raw || raw.length !== 32) return null;
  return raw;
}

function normalizeEnsName(name) {
  const s = String(name || "").trim();
  return s || null;
}

// ENS cache for resolved signer info
let ensCache = {
  fetched_at: 0,
  ttl_ms: 10 * 60 * 1000,
  signer_ens: null,
  kid: null,
  canonical: null,
  pubkey_pem: null,
  pubkey_source: null,
  error: null,
};

async function fetchEnsSignerBundle({ signerName, refresh = false } = {}) {
  const now = Date.now();
  const signerEns = normalizeEnsName(signerName || runtimeConfig.signerId);

  if (process.env.ENS_MOCK_TXT_JSON) {
    try {
      const mock = JSON.parse(process.env.ENS_MOCK_TXT_JSON);
      const pubTxt = String(mock[ENS_SIG_PUB_KEY] || "");
      const raw = parseEd25519Txt(pubTxt);
      const kid = normalizeEnsName(mock[ENS_SIG_KID_KEY]);
      const canonical = normalizeEnsName(mock[ENS_SIG_CANONICAL_KEY]);
      if (!raw || !canonical) throw new Error("invalid ENS_MOCK_TXT_JSON");
      const bundle = {
        fetched_at: now,
        ttl_ms: ensCache.ttl_ms,
        signer_ens: signerEns,
        kid,
        canonical,
        pubkey_pem: spkiDerToPem(ed25519RawToSpkiDer(raw)),
        pubkey_source: "ens_mock",
        error: null,
      };
      ensCache = { ...ensCache, ...bundle };
      return { ok: true, ...bundle, cache: { ...ensCache } };
    } catch (e) {
      return { ok: false, error: e?.message || "ens mock parse failed", cache: { ...ensCache } };
    }
  }

  if (!signerEns) {
    ensCache = { ...ensCache, fetched_at: now, error: "Missing signer ENS name", signer_ens: null };
    return { ok: false, ...ensCache, cache: { ...ensCache } };
  }

  if (!refresh && ensCache.pubkey_pem && now - ensCache.fetched_at < ensCache.ttl_ms && ensCache.signer_ens === signerEns) {
    return { ok: true, ...ensCache, cache: { ...ensCache } };
  }

  if (!ETH_RPC_URL) {
    ensCache = { ...ensCache, fetched_at: now, error: "Missing ETH_RPC_URL", signer_ens: signerEns };
    return { ok: false, ...ensCache, cache: { ...ensCache } };
  }

  try {
    const provider = new ethers.JsonRpcProvider(ETH_RPC_URL);
    const signerResolver = await withTimeout(provider.getResolver(signerEns), 6000, "ens_signer_resolver_timeout");
    if (!signerResolver) throw new Error(`No resolver for signer ENS name: ${signerEns}`);

    const [sigPubTxt, kidTxt, canonicalTxt] = await Promise.all([
      withTimeout(signerResolver.getText(ENS_SIG_PUB_KEY), 6000, "ens_sig_pub_timeout"),
      withTimeout(signerResolver.getText(ENS_SIG_KID_KEY), 6000, "ens_sig_kid_timeout"),
      withTimeout(signerResolver.getText(ENS_SIG_CANONICAL_KEY), 6000, "ens_sig_canonical_timeout"),
    ]);

    const raw = parseEd25519Txt(sigPubTxt);
    const kid = normalizeEnsName(kidTxt);
    const canonical = normalizeEnsName(canonicalTxt);

    if (!raw) throw new Error(`Missing or invalid ${ENS_SIG_PUB_KEY} on ${signerEns}`);
    // kid is optional for compatibility; strict checking is handled in /verify?strict_kid=1
    if (!canonical) throw new Error(`Missing ${ENS_SIG_CANONICAL_KEY} on ${signerEns}`);

    const bundle = {
      fetched_at: now,
      ttl_ms: ensCache.ttl_ms,
      signer_ens: signerEns,
      kid,
      canonical,
      pubkey_pem: spkiDerToPem(ed25519RawToSpkiDer(raw)),
      pubkey_source: `${signerEns}:${ENS_SIG_PUB_KEY}`,
      error: null,
    };

    ensCache = { ...ensCache, ...bundle };
    return { ok: true, ...bundle, cache: { ...ensCache } };
  } catch (e) {
    ensCache = {
      ...ensCache,
      fetched_at: now,
      signer_ens: signerEns,
      pubkey_pem: null,
      pubkey_source: null,
      kid: null,
      canonical: null,
      error: e?.message || "ens fetch failed",
    };
    return { ok: false, ...ensCache, cache: { ...ensCache } };
  }
}

// -----------------------
// AJV schema validation
// -----------------------
const schemaJsonCache = new Map(); // url -> { fetchedAt, schema }
const validatorCache = new Map(); // verb -> { compiledAt, validate }
const inflightValidator = new Map(); // verb -> Promise<validate>

function cachePrune(map, { ttlMs, maxEntries, tsField } = {}) {
  const now = Date.now();

  if (ttlMs && ttlMs > 0) {
    for (const [k, v] of map.entries()) {
      const t = v?.[tsField] || 0;
      if (now - t > ttlMs) map.delete(k);
    }
  }

  if (maxEntries && maxEntries > 0 && map.size > maxEntries) {
    const entries = Array.from(map.entries()).sort((a, b) => (a[1]?.[tsField] || 0) - (b[1]?.[tsField] || 0));
    const toDelete = entries.slice(0, map.size - maxEntries);
    for (const [k] of toDelete) map.delete(k);
  }
}

function normalizeSchemaFetchUrl(url) {
  if (!url) return url;
  let u = String(url);
  u = u.replace(/^http:\/\//i, "https://");
  u = u.replace(/^https:\/\/commandlayer\.org/i, "https://www.commandlayer.org");
  u = u.replace(/^https:\/\/www\.commandlayer\.org\/+/, "https://www.commandlayer.org/");
  if (SCHEMA_HOST.startsWith("https://www.commandlayer.org")) {
    u = u.replace(/^https:\/\/commandlayer\.org/i, "https://www.commandlayer.org");
  }
  return u;
}

async function fetchJsonWithTimeout(url, timeoutMs) {
  if (typeof fetch !== "function") throw new Error("global fetch is not available (requires Node 18+)");
  const u = normalizeSchemaFetchUrl(url);

  cachePrune(schemaJsonCache, { ttlMs: JSON_CACHE_TTL_MS, maxEntries: MAX_JSON_CACHE_ENTRIES, tsField: "fetchedAt" });

  const cached = schemaJsonCache.get(u);
  if (cached) return cached.schema;

  const ac = new AbortController();
  const t = setTimeout(() => ac.abort(), timeoutMs);

  try {
    const resp = await fetch(u, {
      method: "GET",
      headers: { accept: "application/json" },
      signal: ac.signal,
      redirect: "follow",
    });
    if (!resp.ok) throw new Error(`schema fetch failed: ${resp.status} ${resp.statusText}`);
    const schema = await resp.json();
    schemaJsonCache.set(u, { fetchedAt: Date.now(), schema });
    return schema;
  } finally {
    clearTimeout(t);
  }
}

function makeAjv() {
  const ajv = new Ajv({
    allErrors: true,
    strict: false,
    validateSchema: false,
    loadSchema: async (uri) => await fetchJsonWithTimeout(uri, SCHEMA_FETCH_TIMEOUT_MS),
  });
  addFormats(ajv);
  return ajv;
}

function receiptSchemaUrlForVerb(verb) {
  return `${SCHEMA_HOST}/schemas/v1.0.0/commons/${verb}/receipts/${verb}.receipt.schema.json`;
}

async function getValidatorForVerb(verb) {
  cachePrune(validatorCache, {
    ttlMs: VALIDATOR_CACHE_TTL_MS,
    maxEntries: MAX_VALIDATOR_CACHE_ENTRIES,
    tsField: "compiledAt",
  });

  const hit = validatorCache.get(verb);
  if (hit?.validate) return hit.validate;
  if (inflightValidator.has(verb)) return await inflightValidator.get(verb);

  const build = (async () => {
    const ajv = makeAjv();
    const url = receiptSchemaUrlForVerb(verb);

    // Preload shared refs (best effort)
    try {
      const shared = [
        `${SCHEMA_HOST}/schemas/v1.0.0/_shared/receipt.base.schema.json`,
        `${SCHEMA_HOST}/schemas/v1.0.0/_shared/x402.schema.json`,
        `${SCHEMA_HOST}/schemas/v1.0.0/_shared/identity.schema.json`,
      ];
      await Promise.all(shared.map((u) => fetchJsonWithTimeout(u, SCHEMA_FETCH_TIMEOUT_MS).catch(() => null)));
    } catch {
      // ignore
    }

    const schema = await fetchJsonWithTimeout(url, SCHEMA_FETCH_TIMEOUT_MS);
    const validate = await withTimeout(ajv.compileAsync(schema), SCHEMA_VALIDATE_BUDGET_MS, "ajv_compile_budget_exceeded");

    validatorCache.set(verb, { compiledAt: Date.now(), validate });
    return validate;
  })().finally(() => inflightValidator.delete(verb));

  inflightValidator.set(verb, build);
  return await build;
}

function ajvErrorsToSimple(errors) {
  if (!errors || !Array.isArray(errors)) return null;
  return errors.slice(0, 25).map((e) => ({
    instancePath: e.instancePath,
    schemaPath: e.schemaPath,
    keyword: e.keyword,
    message: e.message,
  }));
}

// -----------------------
// Warm queue (edge-safe)
// -----------------------
const warmQueue = new Set();
let warmRunning = false;

function hasValidatorCached(verb) {
  return !!validatorCache.get(verb)?.validate;
}

function startWarmWorker() {
  if (warmRunning) return;
  warmRunning = true;

  setTimeout(() => {
    (async () => {
      const started = Date.now();
      try {
        while (warmQueue.size > 0) {
          if (Date.now() - started > PREWARM_TOTAL_BUDGET_MS) break;

          const verb = warmQueue.values().next().value;
          warmQueue.delete(verb);

          if (!verb) continue;
          if (hasValidatorCached(verb)) continue;

          try {
            await withTimeout(getValidatorForVerb(verb), PREWARM_PER_VERB_BUDGET_MS, "prewarm_per_verb_timeout");
          } catch (e) {
            console.warn("[prewarm] verb failed", verb, e?.message || e);
          }
        }
      } catch (e) {
        console.error("[prewarm] worker crashed", e?.message || e);
      } finally {
        warmRunning = false;
        if (warmQueue.size > 0) startWarmWorker();
      }
    })().catch((e) => {
      console.error("[prewarm] detached task rejected", e?.message || e);
      warmRunning = false;
    });
  }, 0);
}

// -----------------------
// receipts (runtime-core: single source of truth)
// -----------------------
function makeReceipt({ x402, trace, result, status = "success", error = null, delegation_result = null, actor = null }) {
  let receipt = {
    status,
    x402,
    trace,
    ...(delegation_result ? { delegation_result } : {}),
    ...(error ? { error } : {}),
    ...(status === "success" ? { result } : {}),
    metadata: {
      proof: {
        alg: "ed25519-sha256",
        canonical: runtimeConfig.canonicalId,
        signer_id: runtimeConfig.signerId,
        kid: runtimeConfig.kid,
        hash_sha256: null,
        signature_b64: null,
      },
      receipt_id: "",
    },
  };

  if (actor) receipt.metadata.actor = actor;

  const privPem = getActivePrivatePem();
  if (!privPem) throw new Error("Missing/invalid private key");

  // runtime-core should populate hash_sha256 + signature_b64 deterministically
  receipt = signReceiptEd25519Sha256(receipt, {
    signer_id: runtimeConfig.signerId,
    kid: runtimeConfig.kid,
    canonical_id: runtimeConfig.canonicalId,
    privateKeyPem: privPem,
  });

  // Compatibility: if runtime-core returns `canonical`, also emit `canonical_id`
  if (receipt?.metadata?.proof?.canonical && !receipt.metadata.proof.canonical_id) {
    receipt.metadata.proof.canonical_id = receipt.metadata.proof.canonical;
  }

  return receipt;
}

function normalizeReceiptForRuntimeCoreVerify(receipt) {
  const cloned = JSON.parse(JSON.stringify(receipt || {}));
  if (cloned?.metadata?.proof && typeof cloned.metadata.proof === "object") {
    const proof = cloned.metadata.proof;
    if (!proof.canonical && proof.canonical_id) proof.canonical = proof.canonical_id;
    delete proof.canonical_id;
  }
  return cloned;
}

// deterministic verb implementations
// -----------------------
async function doFetch(body) {
  const url = body?.source || body?.input?.source || body?.input?.url;
  if (!url || typeof url !== "string") throw new Error("fetch requires source (url)");

  await ssrfGuardOrThrow(url);

  const ac = new AbortController();
  const t = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);

  let resp;
  try {
    resp = await fetch(url, { method: "GET", signal: ac.signal });
  } finally {
    clearTimeout(t);
  }

  const reader = resp.body?.getReader?.();
  let received = 0;
  const chunks = [];

  if (reader) {
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      if (value) {
        received += value.byteLength;
        if (received > FETCH_MAX_BYTES) break;
        chunks.push(Buffer.from(value));
      }
    }
  }

  let buf;
  if (chunks.length) {
    buf = Buffer.concat(chunks);
  } else {
    const txt = await resp.text();
    buf = Buffer.from(txt, "utf8");
    received = buf.length;
  }

  const text = buf.toString("utf8");
  const preview = text.slice(0, 2000);

  return {
    items: [
      {
        source: url,
        query: body?.query ?? null,
        include_metadata: body?.include_metadata ?? null,
        ok: resp.ok,
        http_status: resp.status,
        headers: Object.fromEntries(resp.headers.entries()),
        body_preview: preview,
        bytes_read: Math.min(received, FETCH_MAX_BYTES),
        truncated: received > FETCH_MAX_BYTES,
      },
    ],
  };
}

function doDescribe(body) {
  const input = body?.input || {};
  const subject = String(input.subject || "").trim();
  if (!subject) throw new Error("describe.input.subject required");
  const detail = input.detail_level || "short";

  const bullets = [
    "Schemas define meaning (requests + receipts).",
    "Runtimes can be swapped without breaking interoperability.",
    "Receipts can be independently verified (hash + signature).",
  ];

  const description =
    detail === "short"
      ? `**${subject}** is a standard “API meaning” contract agents can call using published schemas and receipts.`
      : `**${subject}** is a semantic contract for agents. It standardizes verbs, strict JSON Schemas (requests + receipts), and verifiable receipts so different runtimes can execute the same intent without semantic drift.`;

  return { description, bullets, properties: { verb: "describe", version: "1.0.0", detail_level: detail } };
}

function doFormat(body) {
  const input = body?.input || {};
  const content = String(input.content ?? "");
  const target = input.target_style || "text";
  if (!content.trim()) throw new Error("format.input.content required");

  let formatted = content;
  let style = target;

  if (target === "table") {
    const lines = content
      .split(/\r?\n/)
      .map((s) => s.trim())
      .filter(Boolean);
    const rows = [];
    for (const ln of lines) {
      const m = ln.match(/^([^:]+):\s*(.*)$/);
      if (m) rows.push([m[1].trim(), m[2].trim()]);
    }
    formatted = `| key | value |\n|---|---|\n` + rows.map(([k, v]) => `| ${k} | ${v} |`).join("\n");
    style = "table";
  }

  return {
    formatted_content: formatted,
    style,
    original_length: content.length,
    formatted_length: formatted.length,
    notes: "Deterministic reference formatter (non-LLM).",
  };
}

function doClean(body) {
  const input = body?.input || {};
  let content = String(input.content ?? "");
  if (content === "") throw new Error("clean.input.content required");

  const ops = Array.isArray(input.operations) ? input.operations : [];
  const issues = [];

  const apply = (op) => {
    if (op === "normalize_newlines") content = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
    if (op === "collapse_whitespace") content = content.replace(/[ \t]+/g, " ");
    if (op === "trim") content = content.trim();
    if (op === "remove_empty_lines") content = content.split("\n").filter((l) => l.trim() !== "").join("\n");
    if (op === "redact_emails") {
      const before = content;
      content = content.replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, "[redacted-email]");
      if (content !== before) issues.push("emails_redacted");
    }
  };

  for (const op of ops) apply(op);

  return {
    cleaned_content: content,
    original_length: String(input.content ?? "").length,
    cleaned_length: content.length,
    operations_applied: ops,
    issues_detected: issues,
  };
}

function parseYamlBestEffort(text) {
  const out = {};
  const lines = text.split(/\r?\n/);
  for (const ln of lines) {
    const m = ln.match(/^\s*([^:#]+)\s*:\s*(.*?)\s*$/);
    if (m) out[m[1].trim()] = m[2].trim();
  }
  return out;
}

function doParse(body) {
  const input = body?.input || {};
  const content = String(input.content ?? "");
  if (!content.trim()) throw new Error("parse.input.content required");

  const contentType = (input.content_type || "").toLowerCase();
  const mode = input.mode || "best_effort";

  let parsed = null;
  let confidence = 0.75;
  const warnings = [];

  if (contentType === "json") {
    try {
      parsed = JSON.parse(content);
      confidence = 0.98;
    } catch {
      if (mode === "strict") throw new Error("invalid json");
      warnings.push("Invalid JSON; returned empty object in best_effort.");
      parsed = {};
      confidence = 0.2;
    }
  } else if (contentType === "yaml") {
    parsed = parseYamlBestEffort(content);
    confidence = 0.75;
  } else {
    try {
      parsed = JSON.parse(content);
      confidence = 0.9;
    } catch {
      parsed = parseYamlBestEffort(content);
      confidence = Object.keys(parsed).length ? 0.6 : 0.3;
      if (!Object.keys(parsed).length) warnings.push("Could not confidently parse content.");
    }
  }

  const result = { parsed, confidence };
  if (warnings.length) result.warnings = warnings;
  if (input.target_schema) result.target_schema = String(input.target_schema);
  return result;
}

function sha256HexUtf8(str) {
  return crypto.createHash("sha256").update(String(str), "utf8").digest("hex");
}

function doSummarize(body) {
  const input = body?.input || {};
  const content = String(input.content ?? "");
  if (!content.trim()) throw new Error("summarize.input.content required");

  const style = input.summary_style || "text";
  const format = (input.format_hint || "text").toLowerCase();
  const sentences = content.split(/(?<=[.!?])\s+/).filter(Boolean);

  let summary = "";
  if (style === "bullet_points") {
    const picks = sentences.slice(0, 3).map((s) => s.replace(/\s+/g, " ").trim());
    summary = picks.join(" ");
  } else {
    summary = sentences.slice(0, 2).join(" ").trim();
  }
  if (!summary) summary = content.slice(0, 400).trim();

  const srcHash = sha256HexUtf8(content);
  const cr = summary.length ? Number((content.length / summary.length).toFixed(3)) : 0;

  return {
    summary,
    format: format === "markdown" ? "markdown" : "text",
    compression_ratio: cr,
    source_hash: srcHash,
  };
}

function doConvert(body) {
  const input = body?.input || {};
  const content = String(input.content ?? "");
  const src = String(input.source_format ?? "").toLowerCase();
  const tgt = String(input.target_format ?? "").toLowerCase();
  if (!content.trim()) throw new Error("convert.input.content required");
  if (!src) throw new Error("convert.input.source_format required");
  if (!tgt) throw new Error("convert.input.target_format required");

  let converted = content;
  const warnings = [];
  let lossy = false;

  if (src === "json" && tgt === "csv") {
    let obj;
    try {
      obj = JSON.parse(content);
    } catch {
      throw new Error("convert json->csv requires valid JSON");
    }
    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
      const keys = Object.keys(obj);
      const vals = keys.map((k) => String(obj[k]));
      converted = `${keys.join(",")}\n${vals.join(",")}`;
      lossy = true;
      warnings.push("JSON->CSV is lossy (types/nesting may be flattened).");
    } else {
      throw new Error("convert json->csv supports only flat JSON objects");
    }
  } else {
    warnings.push(`No deterministic converter for ${src}->${tgt}; echoing content.`);
  }

  return { converted_content: converted, source_format: src, target_format: tgt, lossy, warnings };
}

function doExplain(body) {
  const input = body?.input || {};
  const subject = String(input.subject || "").trim();
  if (!subject) throw new Error("explain.input.subject required");

  const detail = input.detail_level || "short";
  const core = [
    "A “receipt” is verifiable evidence that an execution happened under a specific verb + schema version.",
    "It includes the structured output plus a cryptographic hash and signature.",
    "Because the schema is public, anyone can independently validate the receipt later.",
  ];

  const steps = [
    "1) Validate the request against the published request schema.",
    "2) Execute the verb and produce structured output.",
    "3) Build the receipt (base fields + result).",
    "4) Canonicalize + hash the unsigned receipt.",
    "5) Sign the hash with the runtime signer key.",
    "6) Anyone can verify schema validity + hash match + signature (optionally resolving pubkey from ENS).",
  ];

  const explanation =
    `**${subject}** are cryptographically verifiable execution artifacts that bind intent (verb+version), semantics (schema), and output into a signed proof.\n\n` +
    core.map((s) => `- ${s}`).join("\n");

  const result = { explanation, summary: "Receipts are evidence: validate schema + hash + signature." };
  if (detail !== "short") result.steps = steps;
  return result;
}

function doAnalyze(body) {
  const input = String(body?.input ?? "");
  if (!input.trim()) throw new Error("analyze.input required (string)");

  const goal = String(body?.goal ?? "").trim();
  const hints = Array.isArray(body?.hints) ? body.hints.map(String) : [];
  const lines = input.split(/\r?\n/).filter((l) => l.trim() !== "");
  const words = input.trim().split(/\s+/).filter(Boolean);

  const containsUrls = /\bhttps?:\/\/[^\s]+/i.test(input);
  const containsEmails = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i.test(input);
  const containsJsonMarkers = /[{[\]}]/.test(input);
  const containsNumbers = /\b\d+(\.\d+)?\b/.test(input);

  const labels = [];
  if (containsJsonMarkers) labels.push("structured");
  if (containsUrls) labels.push("contains_urls");
  if (containsEmails) labels.push("contains_emails");

  let score = 0;
  if (containsEmails) score += 0.25;
  if (containsUrls) score += 0.2;
  if (containsJsonMarkers) score += 0.1;
  if (containsNumbers) score += 0.05;
  score = Math.min(1, Number(score.toFixed(3)));

  const summary = `Deterministic analysis: ${labels.join(",") || "plain_text"}. Goal="${goal || "n/a"}". Score=${score}.`;
  const insights = [
    `Input length: ${input.length} chars; ~${words.length} words; ${lines.length} non-empty lines.`,
    goal ? `Goal: ${goal}` : "Goal: (none)",
    `Hints provided: ${hints.length}.`,
  ];

  return { summary, insights, labels, score };
}

function doClassify(body) {
  const actor = String(body?.actor ?? "").trim();
  if (!actor) throw new Error("classify.actor required");

  const input = body?.input || {};
  const content = String(input.content ?? "");
  if (!content.trim()) throw new Error("classify.input.content required");

  const maxLabels = Number(body?.limits?.max_labels || 5);

  const labels = [];
  const scores = [];

  const hasUrl = /\bhttps?:\/\/[^\s]+/i.test(content);
  const hasEmail = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i.test(content);
  const hasCode = /\b(error|exception|stack|trace|cannot get|http\/1\.1|curl)\b/i.test(content.toLowerCase());
  const hasFinance = /\b(invoice|payment|usd|\$|bank|wire|crypto)\b/i.test(content.toLowerCase());

  const push = (lbl, sc) => {
    labels.push(lbl);
    scores.push(Number(sc.toFixed(6)));
  };

  if (hasUrl) push("contains_urls", 0.733333);
  if (hasEmail) push("contains_emails", 0.5);
  if (hasCode) push("code_or_logs", 0.4375);
  if (hasFinance) push("finance", 0.25);
  if (!labels.length) push("general", 0.25);

  const trimmedLabels = labels.slice(0, Math.min(128, maxLabels));
  const trimmedScores = scores.slice(0, trimmedLabels.length);

  return { labels: trimmedLabels, scores: trimmedScores, taxonomy: ["root", trimmedLabels[0] || "general"] };
}

// Router: dispatch by verb
function respondSigningError(res, e) {
  return res.status(500).json({
    ok: false,
    code: "SIGNER_MISCONFIGURED",
    message: String(e?.message || "signer misconfigured"),
    ...instancePayload(),
  });
}

const handlers = {
  fetch: doFetch,
  describe: async (b) => doDescribe(b),
  format: async (b) => doFormat(b),
  clean: async (b) => doClean(b),
  parse: async (b) => doParse(b),
  summarize: async (b) => doSummarize(b),
  convert: async (b) => doConvert(b),
  explain: async (b) => doExplain(b),
  analyze: async (b) => doAnalyze(b),
  classify: async (b) => doClassify(b),
};

async function handleVerb(verb, req, res) {
  if (!enabled(verb)) {
    return res.status(404).json({ ...makeError(404, `Verb not enabled: ${verb}`), ...instancePayload() });
  }
  if (!handlers[verb]) {
    return res.status(404).json({ ...makeError(404, `Verb not implemented: ${verb}`), ...instancePayload() });
  }
  if (!requireBody(req, res)) return;

  const rawParent = req.body?.trace?.parent_trace_id ?? req.body?.x402?.extras?.parent_trace_id ?? null;
  const parentTraceId = typeof rawParent === "string" && rawParent.trim().length ? rawParent.trim() : null;

  const trace = {
    provider: process.env.RAILWAY_SERVICE_NAME || "runtime",
    ...(parentTraceId ? { parent_trace_id: parentTraceId } : {}),
  };

  try {
    const x402 = req.body?.x402 || { verb, version: "1.0.0", entry: `x402://${verb}agent.eth/${verb}/v1.0.0` };

    const callerTimeout = Number(req.body?.limits?.timeout_ms || req.body?.limits?.max_latency_ms || 0);
    const timeoutMs = Math.min(SERVER_MAX_HANDLER_MS, callerTimeout && callerTimeout > 0 ? callerTimeout : SERVER_MAX_HANDLER_MS);

    const work = Promise.resolve(handlers[verb](req.body));
    const result = timeoutMs
      ? await Promise.race([work, new Promise((_, rej) => setTimeout(() => rej(new Error("timeout")), timeoutMs))])
      : await work;

    const actor = req.body?.actor
      ? { id: String(req.body.actor), role: "user" }
      : req.body?.x402?.tenant
      ? { id: String(req.body.x402.tenant), role: "tenant" }
      : null;


    try {
      const receipt = makeReceipt({ x402, trace, result, status: "success", actor });
      return res.json(receipt);
    } catch (signErr) {
      return respondSigningError(res, signErr);
    }


    const receipt = makeReceipt({ x402, trace, result, status: "success", actor });
    

return res.json(receipt);

  } catch (e) {
    const x402 = req.body?.x402 || { verb, version: "1.0.0", entry: `x402://${verb}agent.eth/${verb}/v1.0.0` };

    const actor = req.body?.actor
      ? { id: String(req.body.actor), role: "user" }
      : req.body?.x402?.tenant
      ? { id: String(req.body.x402.tenant), role: "tenant" }
      : null;

    const err = {
      code: String(e?.code || "INTERNAL_ERROR"),
      message: String(e?.message || "unknown error").slice(0, 2048),
      retryable: String(e?.message || "").includes("timeout"),
      details: { verb },
    };



    try {
      const receipt = makeReceipt({ x402, trace, status: "error", error: err, actor });
      return res.status(500).json(receipt);
    } catch (signErr) {
      return respondSigningError(res, signErr);
    }


      let receipt;
      try {
        receipt = makeReceipt({ x402, trace, status: "error", error: err, actor });
      } catch (e2) {
        receipt = {
          status: "error",
          x402,
          trace,
          error: err,
          metadata: {
            proof: {
              alg: "ed25519-sha256",
              canonical: CANONICAL_ID_SORTED_KEYS_V1,
              signer_id: SIGNER_ID,
              kid: SIGNER_KID,
              hash_sha256: null,
              signature_b64: null,
              note: "unsigned_error_receipt",
            },
            receipt_id: "",
            ...(actor ? { actor } : {}),
          },
        };
      }

      return res.status(500).json(receipt);

  }
}

// -----------------------
// health/index
// -----------------------
app.get("/", (req, res) => {
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  const verbs = (ENABLED_VERBS || []).map((v) => `/${v}/v${API_VERSION}`);
  return res.status(200).end(
    JSON.stringify({
      ok: true,
      service: SERVICE_NAME,
      version: SERVICE_VERSION,
      api_version: API_VERSION,
      base: CANONICAL_BASE,
      health: "/health",
      healthz: "/healthz",
      verify: "/verify",
      verbs,
      time: nowIso(),
    })
  );
});

app.get("/health", (req, res) => {
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  return res.status(200).end(
    JSON.stringify({
      ok: true,
      service: SERVICE_NAME,
      version: SERVICE_VERSION,
      api_version: API_VERSION,
      base: CANONICAL_BASE,
      node: process.version,
      host: HOST,
      port: PORT,
      enabled_verbs: ENABLED_VERBS,
      signer_id: runtimeConfig.signerId,
      signer_ok: signerBootState.ok,
      verifier_ok: !!getActivePublicPem() || hasRpc(),
      signer_source: activeSigner.source,
      kid: runtimeConfig.kid,
      canonical_id: runtimeConfig.canonicalId,
      public_key_fingerprint: activeSigner.publicKeyFingerprint,
      signer_errors: signerBootState.errors,
      time: nowIso(),
      ...instancePayload(),
    })
  );
});

app.get("/healthz", (req, res) => {
  // keep behavior: alias to /health
  req.url = "/health";
  req.originalUrl = "/health";
  return app._router.handle(req, res, () => {});
});

// -----------------------
// debug (gated)
// -----------------------
app.get("/debug/env", requireDebug, (req, res) => {
  const privPem = getActivePrivatePem();
  const pubPem = getActivePublicPem();

  res.json({
    ok: true,
    node: process.version,
    host: HOST,
    port: PORT,
    service: process.env.RAILWAY_SERVICE_NAME || "runtime",
    enabled_verbs: ENABLED_VERBS,
    signer_id: runtimeConfig.signerId,
    signer_kid: runtimeConfig.kid,
    signer_ok: !!privPem,
    verifier_ok: !!pubPem || hasRpc(),
    signer_source: activeSigner.source,
    env_presence: {
      CL_RECEIPT_SIGNER: !!process.env.CL_RECEIPT_SIGNER,
      CL_KEY_ID: !!process.env.CL_KEY_ID,
      CL_CANONICAL_ID: !!process.env.CL_CANONICAL_ID,
      CL_PRIVATE_KEY_PEM: !!process.env.CL_PRIVATE_KEY_PEM,
      CL_PRIVATE_KEY_PEM_B64: !!process.env.CL_PRIVATE_KEY_PEM_B64,
      CL_PUBLIC_KEY_B64: !!process.env.CL_PUBLIC_KEY_B64,
      ETH_RPC_URL: !!process.env.ETH_RPC_URL,
    },
    key_loading_mode: {
      private_key_pem: process.env.CL_PRIVATE_KEY_PEM?.includes("\\n") ? "single-line-escaped" : "multiline-or-raw",
      public_key: "cl_public_key_b64_raw32",
      private_key_valid: !!privPem,
      public_key_valid: !!pubPem,
      private_key_chars: privPem ? String(privPem).length : 0,
      public_key_raw32_b64_chars: activeSigner.publicKeyRaw32B64 ? activeSigner.publicKeyRaw32B64.length : 0,
    },
    ens_keys: {
      sig_pub: ENS_SIG_PUB_KEY,
      sig_kid: ENS_SIG_KID_KEY,
      sig_canonical: ENS_SIG_CANONICAL_KEY,
    },
    has_rpc: hasRpc(),
    schema_host: SCHEMA_HOST,
    schema_fetch_timeout_ms: SCHEMA_FETCH_TIMEOUT_MS,
    schema_validate_budget_ms: SCHEMA_VALIDATE_BUDGET_MS,
    verify_schema_cached_only: VERIFY_SCHEMA_CACHED_ONLY,
    enable_ssrf_guard: ENABLE_SSRF_GUARD,
    fetch_timeout_ms: FETCH_TIMEOUT_MS,
    fetch_max_bytes: FETCH_MAX_BYTES,
    verify_max_ms: VERIFY_MAX_MS,
    cache: {
      max_json_cache_entries: MAX_JSON_CACHE_ENTRIES,
      json_cache_ttl_ms: JSON_CACHE_TTL_MS,
      max_validator_cache_entries: MAX_VALIDATOR_CACHE_ENTRIES,
      validator_cache_ttl_ms: VALIDATOR_CACHE_TTL_MS,
    },
    server_max_handler_ms: SERVER_MAX_HANDLER_MS,
    prewarm: {
      max_verbs: PREWARM_MAX_VERBS,
      total_budget_ms: PREWARM_TOTAL_BUDGET_MS,
      per_verb_budget_ms: PREWARM_PER_VERB_BUDGET_MS,
    },
    service_name: SERVICE_NAME,
    service_version: SERVICE_VERSION,
    api_version: API_VERSION,
    canonical_base_url: CANONICAL_BASE,
    canonical_id: runtimeConfig.canonicalId,
    debug: { enable_debug: ENABLE_DEBUG, has_debug_token: !!DEBUG_TOKEN },
  });
});

app.get("/debug/enskey", requireDebug, async (req, res) => {
  const refresh = String(req.query.refresh || "0") === "1";
  const out = await fetchEnsSignerBundle({ refresh });

  res.json({
    ok: !!out.ok,
    signer_ens: out.signer_ens || null,
    kid: out.kid || null,
    canonical: out.canonical || null,
    pubkey_source: out.pubkey_source || null,
    cache: out.cache ? { fetched_at: new Date(out.cache.fetched_at).toISOString(), ttl_ms: out.cache.ttl_ms } : null,
    preview: out.pubkey_pem ? out.pubkey_pem.slice(0, 90) + "..." : null,
    error: out.error || null,
  });
});

app.get("/debug/validators", requireDebug, (req, res) => {
  res.json({
    ok: true,
    cached: Array.from(validatorCache.keys()),
    cache_sizes: { schemaJsonCache: schemaJsonCache.size, validatorCache: validatorCache.size },
    inflight: Array.from(inflightValidator.keys()),
    warm_queue_size: warmQueue.size,
    warm_running: warmRunning,
    ...instancePayload(),
  });
});

app.post("/debug/prewarm", requireDebug, (req, res) => {
  const verbs = Array.isArray(req.body?.verbs) ? req.body.verbs : [];
  const cleaned = verbs
    .map((v) => String(v || "").trim())
    .filter(Boolean)
    .slice(0, PREWARM_MAX_VERBS);

  const supported = cleaned.filter((v) => handlers[v]);
  for (const v of supported) warmQueue.add(v);

  res.json({
    ok: true,
    queued: supported,
    already_cached: supported.filter(hasValidatorCached),
    queue_size: warmQueue.size,
  });

  startWarmWorker();
});

// -----------------------
// verify endpoint (signature/hash + optional schema + optional ENS binding)
// -----------------------
// -----------------------
// verify endpoint (signature/hash + optional schema + optional ENS binding)
// -----------------------
app.post("/verify", async (req, res) => {
  const receipt = req.body;

  const wantEns = String(req.query.ens || "0") === "1";
  const strictKid = String(req.query.strict_kid || "0") === "1";
  const refresh = String(req.query.refresh || "0") === "1";
  const wantSchema = String(req.query.schema || "0") === "1";

  const proof = receipt?.metadata?.proof;
  const proofCanonical = String(proof?.canonical_id || proof?.canonical || "");
  const runtimeCoreReceipt = normalizeReceiptForRuntimeCoreVerify(receipt);

  const verifyLogic = async () => {
    if (!proof?.signature_b64 || !proof?.hash_sha256) {
      return res.status(400).json({
        ok: false,
        checks: {
          schema_valid: wantSchema ? false : null,
          hash_matches: null,
          signature_valid: false,
          ens_match: wantEns ? false : null,
        },
        error: "missing metadata.proof.signature_b64 or hash_sha256",
        ...instancePayload(),
      });
    }

    // 1) pick pubkey (env first, then ENS if requested)
    let pubPem = getActivePublicPem();
    let pubSrc = pubPem ? "env" : null;
    let ensExpect = null;

    if (wantEns) {
      const signerForEns = String(proof?.signer_id || runtimeConfig.signerId || "").trim();
      const ensOut = await fetchEnsSignerBundle({ signerName: signerForEns, refresh });

      if (!ensOut.ok || !ensOut.pubkey_pem) {
        return res.status(400).json({
          ok: false,
          checks: {
            schema_valid: wantSchema ? false : null,
            hash_matches: null,
            signature_valid: false,
            ens_match: false,
          },
          error: ensOut.error || "ens resolution failed",
          values: { signer_ens: signerForEns || null },
          ...instancePayload(),
        });
      }

      pubPem = ensOut.pubkey_pem;
      pubSrc = "ens";

      ensExpect = {
        signer_ens: ensOut.signer_ens,
        kid: ensOut.kid || null,
        canonical: ensOut.canonical || null,
      };

      const kidOk = strictKid && ensExpect.kid ? String(proof.kid || "") === String(ensExpect.kid) : true;
      const canonicalOk = proofCanonical === String(ensExpect.canonical || "");
      const signerOk = String(proof.signer_id || "") === String(ensExpect.signer_ens || "");

      if (!kidOk || !canonicalOk || !signerOk) {
        return res.status(400).json({
          ok: false,
          checks: {
            schema_valid: wantSchema ? false : null,
            hash_matches: null,
            signature_valid: false,
            ens_match: false,
          },
          error: "receipt proof does not match ENS signer records",
          values: {
            proof: {
              signer_id: proof?.signer_id ?? null,
              kid: proof?.kid ?? null,
              canonical_id: proofCanonical || null,
            },
            ens: ensExpect,
            pubkey_source: pubSrc,
          },
          ...instancePayload(),
        });
      }
    }

    if (!pubPem) {
      return res.status(400).json({
        ok: false,
        checks: {
          schema_valid: wantSchema ? false : null,
          hash_matches: null,
          signature_valid: false,
          ens_match: wantEns ? false : null,
        },
        error: "no public key available (set RECEIPT_SIGNING_PUBLIC_KEY_B64 or use ens=1 with valid ENS TXT)",
        ...instancePayload(),
      });
    }

    // 2) verify signature/hash via runtime-core
    let v;
    try {
      v = verifyReceiptEd25519Sha256(runtimeCoreReceipt, {
        publicKeyPemOrDer: pubPem,
        allowedCanonicals: [runtimeConfig.canonicalId],
      });
    } catch (e) {
      return res.status(400).json({
        ok: false,
        checks: {
          schema_valid: wantSchema ? false : null,
          hash_matches: null,
          signature_valid: false,
          ens_match: wantEns ? true : null,
        },
        values: {
          verb: receipt?.x402?.verb ?? null,
          signer_id: proof?.signer_id ?? null,
          pubkey_source: pubSrc,
          ens: ensExpect,
        },
        error: e?.message || "public key decode/verify failed",
        ...instancePayload(),
      });
    }

    const signatureValid = v?.checks?.signature_valid ?? !!v?.ok;
    const hashMatches =
      v?.checks?.hash_matches ?? (v?.ok ? true : v?.reason === "hash_mismatch" ? false : null);

    const sigErr = signatureValid ? null : v?.reason || "verify failed";

    // 3) schema validation (optional + edge-safe)
    let schemaOk = null;
    let schemaErrors = null;

    if (wantSchema) {
      schemaOk = false;
      const verb = String(receipt?.x402?.verb || "").trim();

      if (!verb) {
        schemaErrors = [{ message: "missing receipt.x402.verb" }];
      } else if (VERIFY_SCHEMA_CACHED_ONLY && !hasValidatorCached(verb)) {
        warmQueue.add(verb);
        startWarmWorker();

        return res.status(202).json({
          ok: false,
          checks: {
            schema_valid: false,
            hash_matches: hashMatches,
            signature_valid: signatureValid,
            ens_match: wantEns ? true : null,
          },
          values: {
            verb: receipt?.x402?.verb ?? null,
            signer_id: proof?.signer_id ?? null,
            pubkey_source: pubSrc,
            claimed_hash: proof?.hash_sha256 ?? null,
            ens: ensExpect,
          },
          errors: { schema_errors: [{ message: "validator_not_warmed_yet" }], signature_error: sigErr },
          retry_after_ms: 1000,
          ...instancePayload(),
        });
      } else {
        try {
          const validate = VERIFY_SCHEMA_CACHED_ONLY ? validatorCache.get(verb)?.validate : await getValidatorForVerb(verb);
          if (!validate) {
            schemaOk = false;
            schemaErrors = [{ message: "validator_missing" }];
          } else {
            const ok = validate(receipt);
            schemaOk = !!ok;
            if (!ok) schemaErrors = ajvErrorsToSimple(validate.errors) || [{ message: "schema validation failed" }];
          }
        } catch (e) {
          schemaOk = false;
          schemaErrors = [{ message: e?.message || "schema validation error" }];
        }
      }
    }

    const okFinal =
      hashMatches === true &&
      signatureValid === true &&
      (wantSchema ? schemaOk === true : true);

    return res.json({
      ok: okFinal,
      ...(okFinal ? {} : { reason: sigErr || (wantSchema && !schemaOk ? "schema_invalid" : "verify_failed") }),
      signer_id: proof?.signer_id ?? null,
      kid: proof?.kid ?? null,
      hash_sha256: proof?.hash_sha256 ?? null,
      verified_with: wantEns ? "ens" : "env",
      checks: {
        schema_valid: schemaOk,
        hash_matches: hashMatches,
        signature_valid: signatureValid,
        ens_match: wantEns ? true : null,
      },
      values: {
        verb: receipt?.x402?.verb ?? null,
        signer_id: proof?.signer_id ?? null,
        kid: proof?.kid ?? null,
        canonical_id: proofCanonical || null,
        pubkey_source: pubSrc,
        ens: ensExpect,
      },
      errors: { schema_errors: schemaErrors, signature_error: sigErr },
      ...instancePayload(),
    });
  };

  try {
    await Promise.race([
      verifyLogic(),
      new Promise((_, rej) => setTimeout(() => rej(new Error("verify_timeout")), VERIFY_MAX_MS)),
    ]);
  } catch (e) {
    return res.status(500).json({
      ok: false,
      error: e?.message || "verify failed",
      checks: { schema_valid: null, hash_matches: null, signature_valid: false, ens_match: null },
      ...instancePayload(),
    });
  }
});
// verb routes
// -----------------------
for (const verb of ENABLED_VERBS) {
  app.post(`/${verb}/v${API_VERSION}`, (req, res) => handleVerb(verb, req, res));
}

// JSON 404 for any unknown routes
app.use((req, res) => {
  res.status(404).json({ ok: false, error: "not_found", path: req.path, ...instancePayload() });
});

// -----------------------
// boot + listen
// -----------------------
initializeSignerConfigOrThrow();

app.listen(PORT, HOST, () => {
  console.log(`runtime listening on http://${HOST}:${PORT}`);
});