@rakay-technology/kraft 0.7.4

package/dist/chunk-Y7PVJUXJ.js

@@ -0,0 +1,2275 @@
+#!/usr/bin/env sh
+":" //# ; exec "$(command -v node || command -v bun)" "$0" "$@"
+import { createRequire as __ospCreateRequire } from "node:module";
+const require = __ospCreateRequire(import.meta.url);
+import {
+  edgeDownExplanation,
+  explainEdgeDown,
+  isEdgeDownFailure
+} from "./chunk-I3DPMTSF.js";
+import {
+  edgeFailureReason
+} from "./chunk-YZUKHG3S.js";
+import {
+  probeHostedHttp
+} from "./chunk-ZVFS4LUA.js";
+import {
+  ACME_CHALLENGE_LOCATION,
+  ACME_HTTP01_PORT,
+  EDGE_CHALLENGE_DIR,
+  EDGE_CHALLENGE_LOCATION,
+  EDGE_CHALLENGE_URL_PREFIX,
+  EDGE_SAME_PATH_MOUNTS,
+  LUA_LOGGER_PATH,
+  OPENRESTY_DEFAULT_PATHS,
+  RULES_GUARD_PATH,
+  buildReloadCommand,
+  cloudEdgeRealIpConf,
+  detectOpenRestyPaths,
+  edgeChallengeVhostConf,
+  isCloudFrontedHost,
+  luaSourceAvailable,
+  reloadBareOpenResty
+} from "./chunk-BQMFIXHI.js";
+import {
+  probeListeningPort
+} from "./chunk-WYNM7L22.js";
+import {
+  EXECUTOR_DELEGATE
+} from "./chunk-OFXBNFNL.js";
+import {
+  logEntry,
+  sq
+} from "./chunk-MNV2QFHW.js";
+import {
+  PROXY_DIRECTIVES,
+  parseProxyValue,
+  resolveProxyDirectives,
+  resolveRedirectStatus,
+  safeErrorMessage,
+  sanitizeProxySettings
+} from "./chunk-PVOWHIND.js";
+
+// ../../packages/adapters/src/infra/nginx.ts
+import {
+  access as fsAccess,
+  writeFile as fsWriteFile,
+  rm as fsRm,
+  mkdir as fsMkdir,
+  readFile as fsReadFile,
+  readdir as fsReaddir,
+  rename as fsRename,
+  stat as fsStat
+} from "fs/promises";
+import { execFile as cpExecFile } from "child_process";
+import { createHash, randomBytes } from "crypto";
+import { promisify } from "util";
+import { posix as edgePath } from "path";
+
+// ../../packages/adapters/src/system/proxy/cert-material.ts
+import { X509Certificate, createPrivateKey } from "crypto";
+
+// ../../packages/adapters/src/system/edge-container-executor.ts
+function containerCommand(container, command) {
+  return `docker exec ${sq(container)} sh -c ${sq(command)}`;
+}
+async function diagnoseEdgeDown(inner, container) {
+  const status = await inner.exec(`docker inspect -f '{{.State.Status}}' ${sq(container)} 2>/dev/null`).catch(() => null);
+  const logs = await inner.exec(`docker logs --tail 40 ${sq(container)} 2>&1`).catch(() => null);
+  return explainEdgeDown({
+    container,
+    status: status?.trim() || null,
+    reason: logs ? edgeFailureReason(logs) : null
+  });
+}
+function resolveRef(ref) {
+  return typeof ref === "function" ? ref() : ref;
+}
+async function readMaybeInContainer(exec, path, container) {
+  const direct = await exec.readFile(path).catch(() => "");
+  if (direct.trim()) return direct;
+  const name = await resolveRef(container);
+  if (!name) return "";
+  return exec.exec(containerCommand(name, `cat ${sq(path)}`)).catch(() => "");
+}
+async function writeEdgeFileIn(inner, container, path, content, opts) {
+  if (opts === void 0) await inner.writeFile(path, content);
+  else await inner.writeFile(path, content, opts);
+  if (!container) return;
+  const visible = await inner.exec(containerCommand(container, `test -e ${sq(path)} && echo visible`)).catch(() => "");
+  if (visible.trim() === "visible") return;
+  const dir = path.replace(/\/[^/]*$/, "");
+  if (dir && dir !== path) {
+    await inner.exec(containerCommand(container, `mkdir -p ${sq(dir)}`)).catch(() => {
+    });
+  }
+  await inner.exec(`docker cp ${sq(path)} ${sq(`${container}:${path}`)}`).catch(() => {
+  });
+}
+function edgeContainerExecutor(inner, container, opts) {
+  const inContainer = (command) => containerCommand(container, command);
+  const overrides = {
+    // Both command paths enrich a "the container isn't up" failure with the
+    // container's name, state and `[emerg]` — see `diagnoseEdgeDown`. Gated on the
+    // narrow daemon/nginx signatures (`isEdgeDownFailure`), because a non-zero exit
+    // is ordinary here: the container-file probes report a missing path that way, and
+    // paying two `docker` round-trips per miss would be a real cost on every read.
+    exec: async (command, execOpts) => {
+      try {
+        return await inner.exec(inContainer(command), execOpts);
+      } catch (err) {
+        const message = err?.message ?? String(err);
+        if (!isEdgeDownFailure(message)) throw err;
+        throw new Error(
+          `${await diagnoseEdgeDown(inner, container)}
+${message}`
+        );
+      }
+    },
+    // streamExec REPORTS failure instead of throwing it, and its callers build the
+    // error they raise out of what was streamed (`_execCertbot` accumulates the log
+    // lines and throws that text). So the explanation has to go through `onLog` to
+    // reach them — appending it only to the return value would leave certbot's
+    // caller raising the daemon's bare container id, which is the original bug.
+    streamExec: async (command, onLog, opts2) => {
+      const result = await inner.streamExec(inContainer(command), onLog, opts2);
+      if (result.code === 0 || !isEdgeDownFailure(result.output)) return result;
+      const explanation = await diagnoseEdgeDown(inner, container);
+      onLog(logEntry(explanation, "error"));
+      return { code: result.code, output: `${explanation}
+${result.output}` };
+    },
+    // A rename is a FILE op, so it follows the files, never the commands. Stated
+    // here rather than left to the Proxy's passthrough: if the inner executor has no
+    // `rename`, the fallback must still be the INNER shell (the host) — routing it
+    // through this decorator's `exec` would put a `mv` inside the container, where
+    // the host path it was handed does not exist.
+    rename: async (from, to) => {
+      if (inner.rename) return inner.rename(from, to);
+      await inner.exec(`mv ${sq(from)} ${sq(to)}`);
+    }
+  };
+  if (opts?.files === "auto") {
+    Object.assign(overrides, {
+      readFile: (path) => readMaybeInContainer(inner, path, container),
+      writeFile: (path, content, writeOpts) => writeEdgeFileIn(inner, container, path, content, writeOpts),
+      exists: async (path) => {
+        if (await inner.exists(path).catch(() => false)) return true;
+        const { code } = await inner.streamExec(
+          inContainer(`test -e ${sq(path)}`),
+          () => {
+          }
+        );
+        return code === 0;
+      },
+      // The rename half of an atomic write must land in the same namespace as the
+      // write itself, so it follows readFile/writeFile — host first, container only
+      // when the host can't see the file.
+      rename: async (from, to) => {
+        if (await inner.exists(from).catch(() => false)) {
+          if (inner.rename) return inner.rename(from, to);
+          await inner.exec(`mv ${sq(from)} ${sq(to)}`);
+          return;
+        }
+        await inner.exec(inContainer(`mv ${sq(from)} ${sq(to)}`));
+      },
+      // mkdir/rm are idempotent and rare (route register/deregister), so both homes
+      // get them unconditionally rather than paying a probe to decide.
+      mkdir: async (path) => {
+        await inner.mkdir(path);
+        await inner.exec(inContainer(`mkdir -p ${sq(path)}`)).catch(() => {
+        });
+      },
+      rm: async (path) => {
+        await inner.rm(path);
+        await inner.exec(inContainer(`rm -rf ${sq(path)}`)).catch(() => {
+        });
+      }
+    });
+  }
+  return new Proxy(inner, {
+    get(target, prop) {
+      if (prop === EXECUTOR_DELEGATE) return void 0;
+      if (Object.prototype.hasOwnProperty.call(overrides, prop)) {
+        return overrides[prop];
+      }
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+
+// ../../packages/adapters/src/system/proxy/cert-material.ts
+var ACME_ISSUERS = [
+  "let's encrypt",
+  "lets encrypt",
+  "letsencrypt",
+  "zerossl",
+  "google trust services",
+  "buypass",
+  "actalis",
+  "ssl.com"
+];
+function issuerLabel(x509) {
+  const fields = /* @__PURE__ */ new Map();
+  for (const line of x509.issuer.split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq > 0)
+      fields.set(
+        line.slice(0, eq).trim().toUpperCase(),
+        line.slice(eq + 1).trim()
+      );
+  }
+  return fields.get("CN") ?? fields.get("O") ?? x509.issuer.replace(/\n/g, ", ");
+}
+function isAcmeIssuer(x509) {
+  const haystack = `${x509.issuer}`.toLowerCase();
+  return ACME_ISSUERS.some((ca) => haystack.includes(ca));
+}
+function certNames(x509) {
+  const names = [];
+  for (const entry of (x509.subjectAltName ?? "").split(",")) {
+    const [kind, ...rest] = entry.trim().split(":");
+    if (kind?.toUpperCase() === "DNS" && rest.length)
+      names.push(rest.join(":").trim().toLowerCase());
+  }
+  if (names.length === 0) {
+    const cn = x509.subject.split("\n").find((l) => l.trim().toUpperCase().startsWith("CN="));
+    if (cn)
+      names.push(
+        cn.slice(cn.indexOf("=") + 1).trim().toLowerCase()
+      );
+  }
+  return names;
+}
+function coversHost(x509, host) {
+  const target = host.toLowerCase();
+  if (x509.checkHost(target)) return true;
+  return certNames(x509).some((name) => {
+    if (name === target) return true;
+    if (!name.startsWith("*.")) return false;
+    const suffix = name.slice(1);
+    return target.endsWith(suffix) && !target.slice(0, -suffix.length).includes(".");
+  });
+}
+function validateCertFor(host, pems, source) {
+  const certPem = pems.certPem ?? "";
+  const keyPem = pems.keyPem ?? "";
+  if (!certPem.trim() || !keyPem.trim()) {
+    return { cert: null, reason: `${source}: cert or key is empty` };
+  }
+  let x509;
+  try {
+    x509 = new X509Certificate(certPem);
+  } catch (err) {
+    return {
+      cert: null,
+      reason: `${source}: unreadable certificate (${safeErrorMessage(err)})`
+    };
+  }
+  try {
+    if (!x509.checkPrivateKey(createPrivateKey(keyPem))) {
+      return {
+        cert: null,
+        reason: `${source}: private key does not match the certificate`
+      };
+    }
+  } catch (err) {
+    return {
+      cert: null,
+      reason: `${source}: unreadable private key (${safeErrorMessage(err)})`
+    };
+  }
+  if (!coversHost(x509, host)) {
+    return {
+      cert: null,
+      reason: `${source}: certificate covers ${certNames(x509).join(", ") || "no DNS names"} \u2014 not ${host}`
+    };
+  }
+  const notAfter = new Date(x509.validTo);
+  if (!Number.isFinite(notAfter.getTime())) {
+    return {
+      cert: null,
+      reason: `${source}: certificate has an unreadable expiry`
+    };
+  }
+  if (notAfter.getTime() <= Date.now()) {
+    return {
+      cert: null,
+      reason: `${source}: certificate expired ${notAfter.toISOString()}`
+    };
+  }
+  return {
+    cert: {
+      certPem,
+      keyPem,
+      source,
+      expiresAt: notAfter.toISOString(),
+      issuer: issuerLabel(x509),
+      covers: certNames(x509),
+      renewable: isAcmeIssuer(x509)
+    }
+  };
+}
+function isSafeCertPath(p) {
+  return /^\/[A-Za-z0-9._/-]+$/.test(p) && !p.includes("..");
+}
+var BOOTSTRAP_CERT_SEGMENT = "kraft-bootstrap";
+function isBootstrapCertPath(p) {
+  return p.split("/").includes(BOOTSTRAP_CERT_SEGMENT);
+}
+async function readDeclaredPair(exec, certPath, keyPath, container) {
+  if (!isSafeCertPath(certPath) || !isSafeCertPath(keyPath)) return null;
+  if (isBootstrapCertPath(certPath) || isBootstrapCertPath(keyPath))
+    return null;
+  const certPem = await readMaybeInContainer(exec, certPath, container);
+  const keyPem = await readMaybeInContainer(exec, keyPath, container);
+  return certPem && keyPem ? { certPem, keyPem } : null;
+}
+
+// ../../packages/adapters/src/system/output-exists.ts
+var SAFE_HOST = /^[A-Za-z0-9][A-Za-z0-9.-]{0,252}$/;
+var SAFE_PATH = /^\/[A-Za-z0-9._~/-]*$/;
+function safeRequestPath(path) {
+  return SAFE_PATH.test(path) && !path.split("/").includes("..");
+}
+function buildCommand(servedPath, opts) {
+  const p = servedPath.replace(/'/g, "'\\''");
+  const parts = [
+    `if [ -e '${p}' ]; then echo FOUND; fi`,
+    `if [ -f '${p}' ] || [ -f '${p}/index.html' ]; then echo INDEX; fi`
+  ];
+  const host = opts?.hostname;
+  const path = opts?.requestPath ?? "/";
+  if (host && SAFE_HOST.test(host) && safeRequestPath(path)) {
+    const port = opts?.edgePort ?? 80;
+    const maxTime = opts?.timeoutSeconds ?? 3;
+    parts.push(
+      `if command -v curl >/dev/null 2>&1; then echo "HTTP $(curl -sS -o /dev/null -w '%{http_code} %{num_connects}' --max-time ${maxTime} -H 'Host: ${host}' -H 'X-Forwarded-Proto: https' 'http://127.0.0.1:${port}${path}' 2>/dev/null)"; fi`
+    );
+  }
+  parts.push("true");
+  return parts.join("; ");
+}
+function statusIsServed(status) {
+  if (status >= 200 && status < 400) return true;
+  return status === 401 || status === 403;
+}
+function parseHttp(out) {
+  const match = /(^|\n)HTTP (\d+) (\d+)(\r?\n|$)/.exec(out);
+  if (!match) return {};
+  const status = Number(match[2]);
+  const connects = Number(match[3]);
+  if (!Number.isFinite(status) || status === 0 || connects === 0) return {};
+  return { status, served: statusIsServed(status) };
+}
+async function probeStaticOutput(executor, servedPath, opts) {
+  try {
+    const out = await executor.exec(buildCommand(servedPath, opts), {
+      timeout: 8e3
+    });
+    return {
+      found: /(^|\n)FOUND(\r?\n|$)/.test(out),
+      hasIndex: /(^|\n)INDEX(\r?\n|$)/.test(out),
+      checked: true,
+      ...parseHttp(out)
+    };
+  } catch {
+    return { found: false, hasIndex: false, checked: false };
+  }
+}
+
+// ../../packages/adapters/src/infra/nginx.ts
+var { dirname, join } = edgePath;
+var CTL = "\\x00-\\x1f\\x7f";
+var PROXY_HEADERS = `proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $kraft_fwd_proto;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_pass_header X-Accel-Buffering;`;
+var FORWARD_VARS = `    set $kraft_fwd_proto $scheme;
+    set $kraft_redirect_https 1;
+    if ($http_x_forwarded_proto = "https") {
+        set $kraft_fwd_proto https;
+        set $kraft_redirect_https 0;
+    }`;
+var VHOST_GENERATION = 2;
+var GENERATION_MARKER = `# kraft-vhost-gen: ${VHOST_GENERATION}`;
+var GENERATED_HEADER = `# Auto-generated by Kraft - do not edit manually
+${GENERATION_MARKER}`;
+function readVhostGeneration(conf) {
+  const m = conf.match(/^# kraft-vhost-gen: (\d+)$/m);
+  return m ? Number(m[1]) : null;
+}
+var HTTPS_UPGRADE = `if ($kraft_redirect_https) {
+            return 301 https://$server_name$request_uri;
+        }
+
+        `;
+var WEBHOOK_LOCATION_PREFIX = "/_kraft/hooks/";
+function renderProxyLocations(route, opts) {
+  if (!route.proxyLocations || route.proxyLocations.length === 0) return "";
+  const head = `${opts.httpsUpgrade ? HTTPS_UPGRADE : ""}${renderRedirectRules(route, "        ")}`;
+  const claimed = /* @__PURE__ */ new Set([
+    "prefix:/",
+    `prefix:${WEBHOOK_LOCATION_PREFIX}`,
+    // An exact webhook match would not be a duplicate, but it would outrank and
+    // hijack the edge-owned delivery endpoint just as surely as a prefix would.
+    `exact:${WEBHOOK_LOCATION_PREFIX}`
+  ]);
+  const blocks = [];
+  for (const loc of route.proxyLocations) {
+    assertValidUpstream(loc.targetUrl);
+    assertNotReservedLocation(loc.pathPrefix);
+    const headers = loc.external ? externalProxyHeaders(loc.targetUrl) : PROXY_HEADERS;
+    if (!loc.pattern || !loc.upstreamPath) {
+      assertValidLiteralPath(loc.pathPrefix, "proxy location prefix");
+      const kind = loc.exact ? "exact" : "prefix";
+      const key = `${kind}:${loc.pathPrefix}`;
+      if (claimed.has(key)) continue;
+      claimed.add(key);
+      blocks.push(`
+    location ${loc.exact ? "=" : "^~"} ${loc.pathPrefix} {
+        ${head}proxy_pass ${loc.targetUrl};
+        ${headers}
+    }`);
+      continue;
+    }
+    assertValidRedirectPattern(loc.pattern);
+    assertNotReservedLocation(loc.pattern);
+    assertNoNginxInjection(loc.upstreamPath, "rewrite upstream path");
+    assertNoRuntimeVariable(loc.upstreamPath, "rewrite upstream path", true);
+    const match = `^${toNginxPattern(loc.pattern)}$`;
+    if (claimed.has(`regex:${match}`)) continue;
+    claimed.add(`regex:${match}`);
+    blocks.push(`
+    location ~ ${match} {
+        ${head}rewrite ${match} ${loc.upstreamPath} break;
+        proxy_pass ${loc.targetUrl};
+        ${headers}
+    }`);
+  }
+  return blocks.join("");
+}
+function assertNotReservedLocation(pathOrPattern) {
+  if (pathOrPattern.startsWith(WELL_KNOWN_PREFIX)) {
+    throw new Error(
+      `Refusing to generate a location under ${WELL_KNOWN_PREFIX}: ${pathOrPattern}. That namespace belongs to the edge \u2014 a location there can hijack certificate issuance.`
+    );
+  }
+}
+var WELL_KNOWN_PREFIX = "/.well-known/";
+function externalProxyHeaders(targetUrl) {
+  const host = new URL(targetUrl).host;
+  assertNoNginxInjection(host, "external proxy host");
+  return `${PROXY_HEADERS.replace("Host $host;", `Host ${host};`)}
+        proxy_ssl_server_name on;`;
+}
+function renderHostRedirect(route) {
+  const redirect = route.redirectHost;
+  if (!redirect?.target) return null;
+  assertValidDomain(redirect.target);
+  return `return ${resolveRedirectStatus(redirect.statusCode)} https://${redirect.target}$request_uri;`;
+}
+function renderRedirectRules(route, indent) {
+  if (!route.redirects || route.redirects.length === 0) return "";
+  const rules = route.redirects.map((r) => {
+    assertValidRedirect(r);
+    const match = r.pattern ? `^${toNginxPattern(r.pattern, "?")}(?:[?].*)?$` : r.exact ? `^${escapeLiteralPath(r.path)}(?:[?].*)?$` : `^${escapeLiteralPath(r.path)}`;
+    const query = r.destination.includes("?") ? "" : "$is_args$args";
+    return `${indent}if ($request_uri ~ "${match}") {
+${indent}    return ${r.statusCode} ${r.destination}${query};
+${indent}}`;
+  });
+  return `${rules.join("\n")}
+
+${indent}`;
+}
+function assertValidHeader(key, value) {
+  if (!/^[A-Za-z0-9-]+$/.test(key))
+    throw new Error(`Invalid response header name: ${key}`);
+  if (/[\r\n]/.test(value))
+    throw new Error(`Invalid response header value for ${key}`);
+  assertNoRuntimeVariable(value, `response header value for ${key}`);
+}
+function addHeaderLine(key, value) {
+  assertValidHeader(key, value);
+  return `    add_header ${key} "${value.replace(/"/g, '\\"')}" always;`;
+}
+function renderServerHeaders(route, slug) {
+  const lines = headerEntries(route, slug).map(
+    (e) => e.variable === null ? addHeaderLine(e.header.key, e.header.value) : `    add_header ${e.header.key} $${e.variable} always;`
+  );
+  return lines.length > 0 ? `
+${lines.join("\n")}` : "";
+}
+function headerEntries(route, slug) {
+  const prefix = `osh_hdr_${slug.replace(/[^A-Za-z0-9]+/g, "_")}`;
+  let n = 0;
+  return (route.headerRules ?? []).flatMap(
+    (rule) => rule.headers.map((header) => ({
+      rule,
+      header,
+      variable: rule.path === "/" ? null : `${prefix}_${n++}`
+    }))
+  );
+}
+function renderHeaderMaps(route, slug) {
+  const scoped = headerEntries(route, slug).filter((e) => e.variable !== null);
+  if (scoped.length === 0) return "";
+  const blocks = scoped.map((e) => {
+    assertValidLiteralPath(e.rule.path, "header rule path");
+    assertValidHeader(e.header.key, e.header.value);
+    return `map $request_uri $${e.variable} {
+    default "";
+    ~^${escapeLiteralPath(e.rule.path)} "${e.header.value.replace(/"/g, '\\"')}";
+}`;
+  });
+  return `${blocks.join("\n")}
+`;
+}
+function renderUrlShape(route) {
+  if (!("staticRoot" in route) || !route.staticRoot) return "";
+  const rules = [];
+  if (route.cleanUrls) {
+    rules.push(`        if ($request_uri ~ "^([^?]*)[.]html([?].*)?$") {
+            return 308 $1$2;
+        }`);
+  }
+  if (route.trailingSlash === false) {
+    rules.push(`        if ($request_uri ~ "^([^?]+)/([?].*)?$") {
+            return 308 $1$2;
+        }`);
+  }
+  return rules.length > 0 ? `${rules.join("\n").trimStart()}
+
+        ` : "";
+}
+var SLASH_FALLBACK_NAME = "@osh_add_slash";
+function renderSlashFallback(staticRoot) {
+  return `    location ${SLASH_FALLBACK_NAME} {
+        root ${staticRoot};
+
+        if ($request_uri ~ "^([^?]*[^/?])([?].*)?$") {
+            return 308 $1/$2;
+        }
+
+        try_files /index.html =404;
+    }`;
+}
+function renderStaticTryFiles(route) {
+  const parts = ["$uri"];
+  if (route.cleanUrls) parts.push("$uri.html");
+  if (route.trailingSlash === false) parts.push("$uri/index.html");
+  else parts.push("$uri/");
+  parts.push(
+    route.trailingSlash === true ? SLASH_FALLBACK_NAME : "/index.html"
+  );
+  return `try_files ${parts.join(" ")};`;
+}
+function renderProxyDirectives(proxy, opts) {
+  const lines = resolveProxyDirectives(proxy, {
+    scope: opts.tlsOnly ? "tls" : "shared",
+    ...opts.nginxVersion !== void 0 ? { nginxVersion: opts.nginxVersion } : {}
+  }).map((d) => `    ${d.directive} ${d.text};`);
+  return lines.length > 0 ? `
+${lines.join("\n")}` : "";
+}
+function renderProxyOptions(proxy, nginxVersion) {
+  return renderProxyDirectives(proxy, { tlsOnly: false, nginxVersion });
+}
+function renderProxyTlsOptions(proxy, nginxVersion) {
+  return renderProxyDirectives(proxy, { tlsOnly: true, nginxVersion });
+}
+function renderGeoEntries(whitelist) {
+  const entries = [
+    "        default         0;",
+    "        127.0.0.1/32    1;",
+    "        ::1/128         1;"
+  ];
+  for (const cidr of whitelist) {
+    if (/^[\da-fA-F.:\/]+$/.test(cidr) && cidr.length <= 50) {
+      entries.push(`        ${cidr.padEnd(15)} 1;`);
+    }
+  }
+  return entries;
+}
+var DEFAULT_CERT_DIR = "/etc/letsencrypt/live";
+var LETSENCRYPT_PRODUCTION_DIRECTORY = "https://acme-v02.api.letsencrypt.org/directory";
+function assertValidAcmeOptions(opts) {
+  if (!!opts.acmeEabKid !== !!opts.acmeEabHmacKey) {
+    throw new Error("ACME EAB requires both a key identifier and an HMAC key");
+  }
+  if (opts.acmeDirectoryUrl) {
+    let directory;
+    try {
+      directory = new URL(opts.acmeDirectoryUrl);
+    } catch {
+      throw new Error("ACME directory must be a valid http(s) URL");
+    }
+    if (directory.protocol !== "https:" && directory.protocol !== "http:") {
+      throw new Error("ACME directory must use http or https");
+    }
+  }
+  if (opts.acmeEabKid && (!/^[\x20-\x7E]+$/.test(opts.acmeEabKid) || opts.acmeEabKid.length > 512)) {
+    throw new Error(
+      "ACME EAB key identifier must be printable ASCII (maximum 512 characters)"
+    );
+  }
+  if (opts.acmeEabHmacKey && !/^[A-Za-z0-9_-]+={0,2}$/.test(opts.acmeEabHmacKey)) {
+    throw new Error("ACME EAB HMAC key must be base64url encoded");
+  }
+  if (opts.acmeCaBundle && !opts.acmeCaBundle.startsWith("/")) {
+    throw new Error(
+      "ACME CA bundle must be an absolute path in the Certbot environment"
+    );
+  }
+}
+function acmeKeyArgs(keyType) {
+  switch (keyType) {
+    case "ec256":
+      return ["--key-type", "ecdsa", "--elliptic-curve", "secp256r1"];
+    case "ec384":
+      return ["--key-type", "ecdsa", "--elliptic-curve", "secp384r1"];
+    case "rsa2048":
+      return ["--key-type", "rsa", "--rsa-key-size", "2048"];
+    case "rsa4096":
+      return ["--key-type", "rsa", "--rsa-key-size", "4096"];
+    default:
+      return [];
+  }
+}
+var DOMAIN_RE = /^(\*\.)?[a-zA-Z0-9]([a-zA-Z0-9.-]*[a-zA-Z0-9])?$/;
+function assertValidDomain(domain) {
+  if (!DOMAIN_RE.test(domain) || domain.length > 253) {
+    throw new Error(`Invalid domain: ${domain}`);
+  }
+}
+function assertNoNginxInjection(value, what) {
+  if (/[\s;{}#\\'"]/.test(value)) {
+    throw new Error(
+      `Invalid ${what} (contains characters that could inject nginx config): ${value}`
+    );
+  }
+}
+function assertNoRuntimeVariable(value, what, allowCaptures = false) {
+  const residue = allowCaptures ? value.replace(/\$[1-9]/g, "") : value;
+  if (residue.includes("$")) {
+    throw new Error(
+      `Invalid ${what} (contains an nginx variable reference): ${value}`
+    );
+  }
+}
+function assertValidUpstream(targetUrl) {
+  assertNoNginxInjection(targetUrl, "proxy target");
+  assertNoRuntimeVariable(targetUrl, "proxy target");
+  if (!/^https?:\/\/.+/.test(targetUrl)) {
+    throw new Error(
+      `Invalid proxy target (must be http/https URL): ${targetUrl}`
+    );
+  }
+}
+var REDIRECT_PATTERN_RE = /^\/(?:[A-Za-z0-9_~\-/]|\\\.|\(\.\*\)|\(\.\+\)|\(\[\^\/\][*+]\))*$/;
+function assertValidRedirectPattern(pattern) {
+  if (!REDIRECT_PATTERN_RE.test(pattern)) {
+    throw new Error(`Invalid capture pattern: ${pattern}`);
+  }
+}
+var REGEX_METACHARS = /[*+?^$()[\]|]/;
+function assertValidLiteralPath(value, what) {
+  assertNoNginxInjection(value, what);
+  if (!value.startsWith("/") || REGEX_METACHARS.test(value)) {
+    throw new Error(`Invalid ${what} (not a plain path): ${value}`);
+  }
+}
+function escapeLiteralPath(value) {
+  return value.replace(/\./g, "[.]");
+}
+function assertValidRedirect(redirect) {
+  if (redirect.pattern !== void 0)
+    assertValidRedirectPattern(redirect.pattern);
+  assertValidLiteralPath(redirect.path, "redirect path");
+  assertNoNginxInjection(redirect.destination, "redirect destination");
+  assertNoRuntimeVariable(redirect.destination, "redirect destination", true);
+}
+var NGINX_CAPTURE = {
+  "(.*)": `([^${CTL}]*)`,
+  "(.+)": `([^${CTL}]+)`,
+  "([^/]+)": `([^/${CTL}]+)`,
+  "([^/]*)": `([^/${CTL}]*)`
+};
+function toNginxPattern(pattern, alsoExclude = "") {
+  return pattern.replace(/\(\.[*+]\)|\(\[\^\/\][*+]\)/g, (group) => {
+    const hardened = NGINX_CAPTURE[group];
+    if (!hardened) return group;
+    return alsoExclude ? hardened.replace(`${CTL}]`, `${CTL}${alsoExclude}]`) : hardened;
+  });
+}
+var CHALLENGE_TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9._~-]{7,127}$/;
+function assertValidChallengeToken(token) {
+  if (!CHALLENGE_TOKEN_RE.test(token) || token.includes("..")) {
+    throw new Error(`Invalid edge-target challenge token: ${token}`);
+  }
+}
+var MANAGED_STATIC_BASE = "/opt/kraft";
+function assertValidStaticRoot(root, opts) {
+  assertNoNginxInjection(root, "static root");
+  if (!root.startsWith("/") || root.includes("..")) {
+    throw new Error(
+      `Invalid static root (must be an absolute path, no traversal): ${root}`
+    );
+  }
+  if (opts?.adopted) return;
+  const confined = root === MANAGED_STATIC_BASE || root.startsWith(`${MANAGED_STATIC_BASE}/`);
+  if (!confined) {
+    throw new Error(
+      `Refusing to serve static root outside ${MANAGED_STATIC_BASE}: ${root}. Kraft-managed routes serve only their own build output; pass staticRootAdopted when importing a root an existing proxy already serves.`
+    );
+  }
+}
+var execFileAsync = promisify(cpExecFile);
+function isAcmePortBindFailure(output) {
+  return /could not bind (?:tcp )?port|address already in use|problem binding to port/i.test(
+    output || ""
+  );
+}
+function summarizeCertbotFailure(output, domain) {
+  const edgeDown = edgeDownExplanation(output);
+  if (edgeDown) return edgeDown;
+  const structured = certbotDiagnosis(output, domain);
+  if (structured) return structured;
+  const lines = (output || "").split("\n").map((l) => l.trim()).filter(Boolean);
+  return lines.slice(-3).join(" \xB7 ") || `certbot failed to issue a certificate for ${domain}`;
+}
+function certbotDiagnosis(output, domain) {
+  const text = output || "";
+  const pick = (re) => text.match(re)?.[0]?.replace(/\s+/g, " ").trim();
+  const detail = pick(/Detail:\s*[^\n]+/i);
+  const hint = pick(/Hint:\s*[^\n]+/i);
+  const challengeUrl = pick(/https?:\/\/\S*\.well-known\/acme-challenge\/\S*/i);
+  const redirectedToHttps = /^https:/i.test(challengeUrl ?? "");
+  let diagnosis;
+  if (isAcmePortBindFailure(text)) {
+    diagnosis = `Couldn't start the certificate challenge listener for ${domain} on port ${ACME_HTTP01_PORT}: something on this server is already holding it. That port is used only while a certificate is being issued, so this is almost always a certificate run from an earlier attempt that hasn't exited \u2014 retry, and if it persists find the holder with \`ss -ltnp | grep ${ACME_HTTP01_PORT}\` and stop it. Nothing was requested from Let's Encrypt, so this is not a DNS or routing problem.`;
+  } else if (/timeout during connect|connection refused|failed to connect|Timeout/i.test(
+    text
+  )) {
+    diagnosis = `Port 80 for ${domain} isn't reachable from the internet \u2014 a firewall / cloud security group is blocking it, the domain doesn't point at this server, or another proxy is still bound to :80.`;
+  } else if (/NXDOMAIN|no\s+(A|AAAA)\s+record|DNS problem|could not be resolved|no records? found/i.test(
+    text
+  )) {
+    diagnosis = `${domain} doesn't resolve to this server yet \u2014 the DNS A record is missing or hasn't propagated. Wait for propagation, then retry from the Domains tab.`;
+  } else if (/\b52[56]\b|ssl handshake failed/i.test(text)) {
+    diagnosis = `Cloudflare's proxy is answering the certificate challenge for ${domain} instead of forwarding it to this server: it redirects the request to HTTPS, then rejects the origin's TLS. Fix it one of three ways \u2014 set SSL/TLS \u2192 Overview to "Full" (not "Full (strict)") until the first certificate is issued, or turn the orange cloud off for this record until it is, or upload a Cloudflare Origin CA certificate from the Domains tab and skip Let's Encrypt entirely.`;
+  } else if (/404|invalid response|unauthorized|"?status"?:?\s*40\d/i.test(text)) {
+    diagnosis = redirectedToHttps ? `The challenge for ${domain} was redirected from HTTP to HTTPS and then answered with a 404 \u2014 so whatever served it isn't routing that hostname. If ${domain} is behind Cloudflare, its "Always Use HTTPS" is doing the redirect: set SSL/TLS \u2192 Overview to "Full" (not "Full (strict)") until the first certificate is issued, or turn the orange cloud off for this record. Otherwise check the A record points at this server and the domain is registered here. Nothing is occupying :80, so take-over / migrate will not help.` : `Port 80 answered but not with our ACME challenge \u2014 another web server is still serving :80, so the takeover didn't complete. Re-run and choose take-over / migrate.`;
+  } else if (/too many certificates|rateLimited|rate limit/i.test(text)) {
+    diagnosis = `Let's Encrypt rate limit reached for ${domain} \u2014 wait before retrying.`;
+  }
+  const parts = [diagnosis, detail, hint].filter(Boolean);
+  return parts.length > 0 ? parts.join(" \u2014 ") : void 0;
+}
+var NginxProvider = class {
+  sitesDir;
+  acmeEmail;
+  acmeDirectoryUrl;
+  acmeEabKid;
+  acmeEabHmacKey;
+  acmeKeyType;
+  acmeCaBundle;
+  acmeTosAgreed;
+  certDir;
+  executor;
+  paths;
+  reloadCommand;
+  pinPaths;
+  containerEdge;
+  challengeDir;
+  /**
+   * nginx version of the edge, when `detectOpenRestyPaths` could read it. Gates the
+   * one directive whose syntax is version-dependent (`http2`); undefined = unknown,
+   * which `proxyDirectiveAllowed` treats as allow.
+   */
+  nginxVersion;
+  constructor(opts) {
+    assertValidAcmeOptions(opts);
+    this.sitesDir = opts.paths.sitesDir;
+    this.nginxVersion = opts.paths.nginxVersion;
+    this.acmeEmail = opts.acmeEmail;
+    this.acmeDirectoryUrl = opts.acmeDirectoryUrl;
+    this.acmeEabKid = opts.acmeEabKid;
+    this.acmeEabHmacKey = opts.acmeEabHmacKey;
+    this.acmeKeyType = opts.acmeKeyType;
+    this.acmeCaBundle = opts.acmeCaBundle;
+    this.acmeTosAgreed = opts.acmeTosAgreed ?? true;
+    this.certDir = opts.certDir ?? DEFAULT_CERT_DIR;
+    this.executor = opts.executor ?? null;
+    this.paths = opts.paths;
+    this.containerEdge = opts.containerEdge ?? false;
+    this.reloadCommand = buildReloadCommand(opts.paths);
+    this.pinPaths = opts.pinPaths ?? false;
+    this.challengeDir = opts.challengeDir ?? EDGE_CHALLENGE_DIR;
+  }
+  // ── File operation helpers (dual-path: local or remote) ──────────────
+  async _writeFile(path, content, mode) {
+    const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}-${randomBytes(4).toString("hex")}`;
+    if (this.executor) {
+      if (mode !== void 0) this._assertChmodReaches(path, mode);
+      try {
+        await this.executor.writeFile(tmpPath, content);
+        if (mode !== void 0) {
+          await this._chmod(tmpPath, mode);
+        }
+        if (this.executor.rename) {
+          await this.executor.rename(tmpPath, path);
+        } else {
+          await this.executor.exec(`mv ${sq(tmpPath)} ${sq(path)}`);
+        }
+      } catch (err) {
+        await this.executor.rm(tmpPath).catch(() => void 0);
+        throw err;
+      }
+    } else {
+      await fsMkdir(dirname(path), { recursive: true });
+      try {
+        await fsWriteFile(tmpPath, content, { encoding: "utf-8", mode });
+        await fsRename(tmpPath, path);
+      } catch (err) {
+        await fsRm(tmpPath).catch(() => void 0);
+        throw err;
+      }
+    }
+  }
+  async _readFile(path) {
+    if (this.executor) {
+      return this.executor.readFile(path);
+    }
+    return fsReadFile(path, "utf-8");
+  }
+  async _exists(path) {
+    if (this.executor) {
+      return this.executor.exists(path);
+    }
+    try {
+      await fsAccess(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async _rm(path) {
+    if (this.executor) {
+      await this.executor.rm(path);
+    } else {
+      try {
+        await fsRm(path, { recursive: true, force: true });
+      } catch {
+      }
+    }
+  }
+  async _mkdir(path) {
+    if (this.executor) {
+      await this.executor.mkdir(path);
+    } else {
+      await fsMkdir(path, { recursive: true });
+    }
+  }
+  /**
+   * Do a FILE op and a COMMAND at `path` reach the same bytes?
+   *
+   * On a container edge they travel different namespaces: `writeFile`/`mkdir` land on
+   * the HOST (bind mount) while `exec` runs INSIDE the container. They name the same
+   * file only where a mount carries the same string on both sides
+   * ({@link EDGE_SAME_PATH_MOUNTS}). A bare or remote edge has one namespace, so
+   * everything qualifies.
+   */
+  _sharesHostNamespace(path) {
+    if (!this.containerEdge) return true;
+    return EDGE_SAME_PATH_MOUNTS.some(
+      (m) => path === m || path.startsWith(`${m}/`)
+    );
+  }
+  /**
+   * Refuse an operation that mixes the two channels at a path where they are not the
+   * same file. `action` completes "Refusing to …" and must name the path.
+   *
+   * Never "skip it and continue", because both failure modes are silent. A `chmod`
+   * either misses or tightens a DIFFERENT file that does exist in the container,
+   * leaving a TLS private key or the ACME EAB HMAC key at the default mode and
+   * reporting success. An `openssl -keyout` writes the key into the container's own
+   * filesystem, where the host path OpenResty reads never sees it — and a vhost
+   * pointing at material the host lacks fails `openresty -t` for the WHOLE edge.
+   */
+  _assertOneNamespace(path, action) {
+    if (this._sharesHostNamespace(path)) return;
+    throw new Error(
+      `Refusing to ${action}: this edge runs in a container, so file operations land on the host while commands run inside it. Only paths under ${EDGE_SAME_PATH_MOUNTS.join(", ")} are the same path on both sides.`
+    );
+  }
+  /** The chmod half of {@link _assertOneNamespace}: the write travels the file channel, the mode the command channel. */
+  _assertChmodReaches(path, mode) {
+    this._assertOneNamespace(
+      path,
+      `write ${path} with mode 0${mode.toString(8)}`
+    );
+  }
+  /** No-op without an executor: the local path sets the mode at creation instead. */
+  async _chmod(path, mode) {
+    if (!this.executor) return;
+    this._assertChmodReaches(path, mode);
+    await this.executor.exec(`chmod ${sq(mode.toString(8))} ${sq(path)}`);
+  }
+  /**
+   * Put `fullchain.pem` + `privkey.pem` in `dir` as ONE atomic step.
+   *
+   * Both files are written into a temp sibling dir, then the pair is moved into
+   * place together. A cert and its key are only valid as a set — writing them
+   * individually means a crash, a full disk, or a dropped SSH connection between
+   * the two leaves the new cert next to the previous key, and `openresty -t` then
+   * fails for the WHOLE edge (every domain, not just this one) until someone
+   * notices. `mv -T`/rename of the staged dir also means a concurrent reload sees
+   * either the old pair or the new one, never a half-written PEM.
+   */
+  async stageCertDir(dir, cert) {
+    const staging = `${dir}.staging-${process.pid}-${randomBytes(4).toString("hex")}`;
+    try {
+      await this._mkdir(staging);
+      await this._writeFile(join(staging, "fullchain.pem"), cert.certPem);
+      await this._writeFile(join(staging, "privkey.pem"), cert.keyPem, 384);
+      if (this.executor) {
+        await this._mkdir(dir);
+        await this.executor.exec(
+          `mv -f ${sq(join(staging, "fullchain.pem"))} ${sq(join(staging, "privkey.pem"))} ${sq(dir)}/`
+        );
+      } else {
+        await fsMkdir(dir, { recursive: true });
+        await fsRename(
+          join(staging, "fullchain.pem"),
+          join(dir, "fullchain.pem")
+        );
+        await fsRename(join(staging, "privkey.pem"), join(dir, "privkey.pem"));
+      }
+    } finally {
+      await this._rm(staging).catch(() => void 0);
+    }
+  }
+  /**
+   * Where a domain's temporary self-signed cert lives — a SIBLING of certbot's
+   * `live/`, deliberately not inside it. See {@link ensureBootstrapCert}.
+   */
+  bootstrapCertDir(domain) {
+    return join(dirname(this.certDir), BOOTSTRAP_CERT_SEGMENT, domain);
+  }
+  /**
+   * Ensure a self-signed placeholder cert exists for `domain`, so a route whose TLS
+   * we terminate can ALWAYS complete a TLS handshake — including before certbot has
+   * issued anything.
+   *
+   * Why a missing :443 block is a hard failure, not a soft one: an unmatched SNI
+   * falls through to the edge's :443 catch-all, which answers with the "service not
+   * found" page (#431) under a placeholder certificate that belongs to no domain.
+   * For a domain we DO route that is a broken site: the visitor is told nothing is
+   * deployed here, and behind Cloudflare "Full" — which accepts any origin cert —
+   * they get that page rather than the app. Issuance deadlocks with it: Cloudflare
+   * answers the HTTP-01 challenge with a 301 to https, the catch-all deliberately
+   * carries no ACME location on :443, so the challenge 404s and the vhost stays
+   * HTTP-only — forever (#308). A per-domain placeholder breaks the loop: the
+   * domain gets its OWN name-bound :443 block, the challenge completes, and the
+   * real cert takes over.
+   *
+   * So the :443 catch-all having gained a certificate of its own does NOT make this
+   * redundant — it only changed the symptom from a raw TLS error (#431's old error
+   * 525) into a wrong page. The catch-all's cert is deliberately valid for nothing;
+   * serving it for a domain we route is the cross-serving that block exists to
+   * prevent.
+   *
+   * Deliberately NOT written under `certDir`: `certsExist()` / `readCertInfo()`
+   * read that path, so a self-signed cert there would short-circuit provisionCert
+   * and report an untrusted cert as `active`, with the renewal scheduler and the
+   * verify-pending sweep both satisfied. Keeping it in a sibling dir means cert
+   * STATUS is untouched — the domain still reads provisioning/error and keeps
+   * retrying until a real cert lands.
+   *
+   * Returns null when nothing could be produced (no `openssl` on the executor, exec
+   * failure); the caller falls back to an HTTP-only vhost, exactly as before.
+   * Never throws — a placeholder must not be able to fail a deploy.
+   */
+  async ensureBootstrapCert(domain) {
+    const dir = this.bootstrapCertDir(domain);
+    const certPath = join(dir, "fullchain.pem");
+    const keyPath = join(dir, "privkey.pem");
+    if (!this._sharesHostNamespace(dir)) {
+      console.warn(
+        `[SSL] not creating a temporary certificate for ${domain}: ${dir} is not the same path inside the edge container as on the host, so OpenResty could not read the key \u2014 serving HTTP only until a real certificate is issued.`
+      );
+      return null;
+    }
+    try {
+      if (await this._exists(certPath) && await this._exists(keyPath)) {
+        return { certPath, keyPath };
+      }
+    } catch {
+      return null;
+    }
+    const staging = `${dir}.staging-${process.pid}-${randomBytes(4).toString("hex")}`;
+    try {
+      await this._mkdir(staging);
+      await this._exec("openssl", [
+        "req",
+        "-x509",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        join(staging, "privkey.pem"),
+        "-out",
+        join(staging, "fullchain.pem"),
+        "-days",
+        "3650",
+        "-subj",
+        `/CN=${domain}`,
+        "-addext",
+        `subjectAltName=DNS:${domain}`
+      ]);
+      await this._chmod(join(staging, "privkey.pem"), 384);
+      await this._mkdir(dir);
+      if (this.executor) {
+        await this.executor.exec(
+          `mv -f ${sq(join(staging, "fullchain.pem"))} ${sq(join(staging, "privkey.pem"))} ${sq(dir)}/`
+        );
+      } else {
+        await fsRename(join(staging, "fullchain.pem"), certPath);
+        await fsRename(join(staging, "privkey.pem"), keyPath);
+      }
+      return { certPath, keyPath };
+    } catch (err) {
+      console.warn(
+        `[SSL] could not create a temporary certificate for ${domain} \u2014 serving HTTP only until a real certificate is issued (is openssl installed on the edge?): ${safeErrorMessage(err)}`
+      );
+      return null;
+    } finally {
+      await this._rm(staging).catch(() => void 0);
+    }
+  }
+  async _exec(command, args = []) {
+    if (this.executor) {
+      const full = args.length ? `${command} ${args.map(sq).join(" ")}` : command;
+      return this.executor.exec(full);
+    }
+    try {
+      const { stdout } = await execFileAsync(command, args);
+      return stdout;
+    } catch (err) {
+      const e = err;
+      const detail = [e.stderr?.trim(), e.stdout?.trim()].filter(Boolean).join("\n");
+      throw new Error(detail || e.message || String(err));
+    }
+  }
+  /**
+   * Does this static `root` resolve where OpenResty looks? (RoutingProvider)
+   *
+   * Runs the probe through `this.executor` — the SAME handle vhost writes and
+   * `openresty -s reload` go through — so it answers from the edge's own vantage
+   * point. That is the whole value: for a containerized edge the executor's `exec`
+   * lands INSIDE the container (DockerEdgeExecutor / edgeContainerExecutor), so a
+   * `root` that exists on the host but was never bind-mounted reads as missing
+   * here, which is exactly the 404 a host-side probe cannot see. With no executor
+   * the edge is bare-local and shares this process's filesystem, so node:fs is
+   * already the right vantage point.
+   *
+   * Advisory: never throws.
+   */
+  async probeStaticRoot(servedPath, opts) {
+    if (this.executor)
+      return probeStaticOutput(this.executor, servedPath, opts);
+    const fs = await this.probeStaticRootViaFs(servedPath);
+    if (!opts?.hostname) return fs;
+    const http = await probeHostedHttp({
+      hostname: opts.hostname,
+      path: opts.requestPath ?? "/",
+      port: opts.edgePort ?? 80,
+      timeoutMs: (opts.timeoutSeconds ?? 3) * 1e3
+    });
+    return http ? { ...fs, status: http.status, served: http.served } : fs;
+  }
+  async probeStaticRootViaFs(servedPath) {
+    const found = await this._exists(servedPath);
+    if (!found) return { found: false, hasIndex: false, checked: true };
+    const isFile = await fsStat(servedPath).then((s) => s.isFile()).catch(() => false);
+    const hasIndex = isFile || await this._exists(join(servedPath, "index.html"));
+    return { found: true, hasIndex, checked: true };
+  }
+  /**
+   * Run certbot, optionally STREAMING its output line-by-line to `onLog` (the
+   * live verify modal). Falls back to buffered `_exec` when no callback / no
+   * executor. `streamExec` doesn't reject on a non-zero exit — it returns the
+   * code — so mirror `_exec`'s throw-with-output so `summarizeCertbotFailure`
+   * still sees the real cause.
+   */
+  async _execCertbot(args, onLog) {
+    const command = this.acmeCaBundle ? "env" : "certbot";
+    const commandArgs = this.acmeCaBundle ? [`REQUESTS_CA_BUNDLE=${this.acmeCaBundle}`, "certbot", ...args] : args;
+    if (!onLog || !this.executor) {
+      let out;
+      try {
+        out = await this._exec(command, commandArgs);
+      } catch (err) {
+        throw new Error(this.redactAcmeSecrets(safeErrorMessage(err)));
+      }
+      const redacted = this.redactAcmeSecrets(out);
+      if (redacted) onLog?.(redacted);
+      return redacted;
+    }
+    const full = `${command} ${commandArgs.map(sq).join(" ")}`;
+    let output = "";
+    const { code } = await this.executor.streamExec(full, (log) => {
+      output += log.message;
+      onLog(this.redactAcmeSecrets(log.message));
+    });
+    if (code !== 0) {
+      throw new Error(
+        this.redactAcmeSecrets(output).trim() || `certbot exited ${code}`
+      );
+    }
+    return this.redactAcmeSecrets(output);
+  }
+  redactAcmeSecrets(value) {
+    return this.acmeEabHmacKey ? value.split(this.acmeEabHmacKey).join("[REDACTED]") : value;
+  }
+  /**
+   * Keep EAB HMAC material out of argv/process listings and remove it after use.
+   *
+   * Same layout contract as runtime/git-ssh-material.ts (the repo's other
+   * ephemeral-secret-on-disk site): the material lives in its OWN 0700 directory
+   * with the file at 0600, the bytes never travel through a shell command line,
+   * and cleanup removes the directory as a unit. The 0700 parent goes first, so
+   * even the temp file _writeFile stages is born unreadable to other users.
+   */
+  async createEphemeralEabConfig() {
+    if (!this.acmeEabKid || !this.acmeEabHmacKey) return null;
+    const dir = join(
+      dirname(this.certDir),
+      `.kraft-eab-${randomBytes(12).toString("hex")}`
+    );
+    const path = join(dir, "eab.ini");
+    if (this.executor) await this.executor.mkdir(dir);
+    else await fsMkdir(dir, { recursive: true, mode: 448 });
+    try {
+      await this._chmod(dir, 448);
+      await this._writeFile(
+        path,
+        `eab-kid = ${this.acmeEabKid}
+eab-hmac-key = ${this.acmeEabHmacKey}
+`,
+        384
+      );
+    } catch (err) {
+      await this._rm(dir).catch(() => void 0);
+      throw err;
+    }
+    return path;
+  }
+  /** Materialize generated DNS hooks on the same target where Certbot runs. */
+  async createEphemeralDnsHooks(opts) {
+    if (!opts?.dnsAuthHookScript) return null;
+    const dir = join(
+      dirname(this.certDir),
+      `.kraft-dns-${randomBytes(12).toString("hex")}`
+    );
+    const authPath = join(dir, "auth.sh");
+    const cleanupPath = join(dir, "cleanup.sh");
+    const recordPath = join(dir, "record-id.txt");
+    await this._mkdir(dir);
+    try {
+      await this._chmod(dir, 448);
+      await this._writeFile(authPath, opts.dnsAuthHookScript, 448);
+      if (opts.dnsCleanupHookScript) {
+        await this._writeFile(cleanupPath, opts.dnsCleanupHookScript, 448);
+      }
+    } catch (err) {
+      await this._rm(dir).catch(() => void 0);
+      throw err;
+    }
+    const recordEnv = `KRAFT_DNS_RECORD_FILE=${sq(recordPath)}`;
+    return {
+      dir,
+      authCommand: `${recordEnv} ${sq(authPath)}`,
+      cleanupCommand: opts.dnsCleanupHookScript ? `${recordEnv} ${sq(cleanupPath)}` : void 0
+    };
+  }
+  async _captureFile(path) {
+    if (!await this._exists(path)) {
+      return { exists: false };
+    }
+    return {
+      exists: true,
+      content: await this._readFile(path)
+    };
+  }
+  async _restoreFile(path, snapshot) {
+    if (!snapshot.exists) {
+      await this._rm(path);
+      return;
+    }
+    await this._writeFile(path, snapshot.content ?? "");
+  }
+  // ── Routing ──────────────────────────────────────────────────────────
+  /**
+   * Register a route by writing an OpenResty server block.
+   *
+   * Creates a conf file in sites-enabled, then reloads.
+   * If TLS is enabled and certs exist, configures SSL. If certs don't
+   * exist yet, writes an HTTP-only block (certbot will add SSL later
+   * via provisionCert).
+   */
+  async registerRoute(route) {
+    assertValidDomain(route.domain);
+    await this._mkdir(this.sitesDir);
+    const slug = await this.resolveSlug(route.domain);
+    const configPath = join(this.sitesDir, `${slug}.conf`);
+    if ("staticRoot" in route && route.staticRoot) {
+      assertValidStaticRoot(route.staticRoot, {
+        adopted: route.staticRootAdopted
+      });
+    } else {
+      assertValidUpstream(route.targetUrl);
+    }
+    const hostRedirect = renderHostRedirect(route);
+    const locationBody = hostRedirect ? hostRedirect : "staticRoot" in route && route.staticRoot ? `root ${route.staticRoot};
+        index index.html;
+        ${renderStaticTryFiles(route)}` : `proxy_pass ${route.targetUrl};
+        ${PROXY_HEADERS}`;
+    const urlShape = hostRedirect ? "" : renderUrlShape(route);
+    const redirectRules = hostRedirect ? "" : renderRedirectRules(route, "        ");
+    const extraLocations = hostRedirect ? "" : renderProxyLocations(route, { httpsUpgrade: false });
+    const upgradingExtraLocations = hostRedirect ? "" : renderProxyLocations(route, { httpsUpgrade: true });
+    const serverHeaders = hostRedirect ? "" : renderServerHeaders(route, slug);
+    const prelude = hostRedirect ? "" : renderHeaderMaps(route, slug);
+    const proxyOpts = renderProxyOptions(route.proxy, this.nginxVersion);
+    const proxyTlsOpts = renderProxyTlsOptions(route.proxy, this.nginxVersion);
+    const preamble = isCloudFrontedHost(route.domain) ? `${cloudEdgeRealIpConf()}
+${FORWARD_VARS}` : FORWARD_VARS;
+    const webhookLocation = route.webhookProxy && !hostRedirect ? `
+    location ^~ ${WEBHOOK_LOCATION_PREFIX} {
+        proxy_pass ${route.webhookProxy};
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $kraft_fwd_proto;
+    }
+` : "";
+    const edgeLua = luaSourceAvailable();
+    const luaProxy = edgeLua ? `    log_by_lua_file ${LUA_LOGGER_PATH};
+    access_by_lua_file ${RULES_GUARD_PATH};` : "";
+    const slashFallback = !hostRedirect && "staticRoot" in route && route.staticRoot && route.trailingSlash === true ? `
+
+${renderSlashFallback(route.staticRoot)}` : "";
+    const serveLocation = `    location / {
+        ${redirectRules}${urlShape}${locationBody}
+    }${slashFallback}`;
+    const redirectOrServeLocation = hostRedirect ? serveLocation : `    location / {
+        ${HTTPS_UPGRADE}${redirectRules}${urlShape}${locationBody}
+    }${slashFallback}`;
+    const sharedBody = `${serverHeaders}${proxyOpts}
+${webhookLocation}${extraLocations}`;
+    const httpsUpgradeBody = `${serverHeaders}${proxyOpts}
+${webhookLocation}${upgradingExtraLocations}`;
+    const httpOnlyBlock = `${GENERATED_HEADER}
+server {
+    listen 80;
+    server_name ${route.domain};
+
+${preamble}
+
+${luaProxy}
+
+${ACME_CHALLENGE_LOCATION}
+
+${EDGE_CHALLENGE_LOCATION}
+${sharedBody}
+${serveLocation}
+}
+`;
+    let serverBlock;
+    let bootstrapServed = false;
+    if (route.tls && await this.certsExist(route.domain)) {
+      const certPath = join(this.certDir, route.domain, "fullchain.pem");
+      const keyPath = join(this.certDir, route.domain, "privkey.pem");
+      serverBlock = `${GENERATED_HEADER}
+server {
+    listen 80;
+    server_name ${route.domain};
+
+${preamble}
+
+${luaProxy}
+
+${ACME_CHALLENGE_LOCATION}
+
+${EDGE_CHALLENGE_LOCATION}
+${httpsUpgradeBody}
+${redirectOrServeLocation}
+}
+
+server {
+    listen 443 ssl;
+    server_name ${route.domain};
+
+${preamble}
+
+${luaProxy}
+
+    ssl_certificate ${certPath};
+    ssl_certificate_key ${keyPath};${proxyTlsOpts}
+${sharedBody}
+${serveLocation}
+}
+`;
+    } else if (route.tls && route.terminatesTlsLocally) {
+      const bootstrap = await this.ensureBootstrapCert(route.domain);
+      bootstrapServed = !!bootstrap;
+      serverBlock = bootstrap ? `${GENERATED_HEADER}
+# kraft-bootstrap-tls: ${route.domain} is serving a TEMPORARY self-signed
+# certificate because its real certificate has not been issued yet. Kraft
+# replaces this file automatically once it lands. Do not adopt this material.
+server {
+    listen 80;
+    server_name ${route.domain};
+
+${preamble}
+
+${luaProxy}
+
+${ACME_CHALLENGE_LOCATION}
+
+${EDGE_CHALLENGE_LOCATION}
+${sharedBody}
+${serveLocation}
+}
+
+server {
+    listen 443 ssl;
+    server_name ${route.domain};
+
+${preamble}
+
+${luaProxy}
+
+    ssl_certificate ${bootstrap.certPath};
+    ssl_certificate_key ${bootstrap.keyPath};${proxyTlsOpts}
+${sharedBody}
+${serveLocation}
+}
+` : httpOnlyBlock;
+    } else {
+      serverBlock = httpOnlyBlock;
+    }
+    const snapshot = await this._captureFile(configPath);
+    await this._writeFile(configPath, `${prelude}${serverBlock}`);
+    try {
+      await this.reload();
+    } catch (err) {
+      await this._restoreFile(configPath, snapshot);
+      await this.reload().catch(() => void 0);
+      throw err;
+    }
+    if (!bootstrapServed) {
+      await this._rm(this.bootstrapCertDir(route.domain)).catch(
+        () => void 0
+      );
+    }
+    await this._writeFile(
+      this.routeStatePath(slug),
+      JSON.stringify(route)
+    ).catch(() => void 0);
+  }
+  routeStatePath(slug) {
+    return join(this.sitesDir, `${slug}.route.json`);
+  }
+  /**
+   * Re-emit every vhost an older generator wrote, from its own persisted RouteConfig.
+   *
+   * Why this exists: a fix to the EMITTED shape otherwise never reaches a running box.
+   * `registerRoute` is the only writer, and the only things that call it are a deploy, a
+   * domain save, a Retry, and cert issuance — so a project nobody redeploys keeps the vhost
+   * it was first given for as long as it lives. That is how the Cloud-fronted `X-Real-IP`
+   * block shipped and then applied to nothing: correct code, upgraded box, unchanged file.
+   *
+   * Cheap and idempotent by construction: a vhost already stamped at
+   * {@link VHOST_GENERATION} is read and skipped, so the pass writes nothing and reloads
+   * nothing once converged. Only the FIRST run after a bump does work.
+   *
+   * That first run is not free, and the release that introduced the marker is its worst
+   * case: every conf written before it is unstamped, so a box with N routes reapplies all
+   * N. `registerRoute` writes and reloads per route by design — a conf that fails
+   * `openresty -t` is rolled back and reloaded on its own, which is why one bad route
+   * cannot take the other N-1 down — so that run costs N whole-config tests and N reloads,
+   * serially, on a deploy. Batching them behind a single test would trade that isolation
+   * for the seconds it saves once per box, which is the wrong trade. What it does mean is
+   * that a VHOST_GENERATION bump is a fleet-wide cost, not a free redeploy: bump it for a
+   * fix that has to reach existing boxes, not to tidy the emitted text.
+   *
+   * Never throws and never aborts the sweep. One route whose sidecar is unreadable, or
+   * whose re-render fails `openresty -t` (registerRoute rolls that file back on its own),
+   * must not stop the rest — a half-converged edge with a reported failure is strictly
+   * better than a wedged one. A route with no sidecar is left ALONE rather than
+   * reconstructed from its conf: the scrape recovers only the primary target, so replaying
+   * it would drop composite locations and the webhook proxy.
+   */
+  async reapplyStoredRoutes() {
+    const repaired = [];
+    const failed = [];
+    let entries;
+    try {
+      entries = await this._lsSites();
+    } catch (err) {
+      return {
+        scanned: 0,
+        repaired,
+        failed: [{ slug: "*", reason: safeErrorMessage(err) }]
+      };
+    }
+    const slugs = entries.filter((name) => name.endsWith(".route.json")).map((name) => name.slice(0, -".route.json".length));
+    const stale = await this._staleVhostSlugs().catch(() => null);
+    for (const slug of slugs) {
+      if (stale && !stale.has(slug)) continue;
+      try {
+        const conf = await this._readFile(
+          join(this.sitesDir, `${slug}.conf`)
+        ).catch(() => null);
+        if (conf === null) continue;
+        const gen = readVhostGeneration(conf);
+        if (gen !== null && gen >= VHOST_GENERATION) continue;
+        const saved = JSON.parse(
+          await this._readFile(this.routeStatePath(slug))
+        );
+        if (!saved?.domain) {
+          failed.push({ slug, reason: "sidecar has no domain" });
+          continue;
+        }
+        await this.registerRoute(saved);
+        repaired.push(saved.domain);
+      } catch (err) {
+        failed.push({ slug, reason: safeErrorMessage(err) });
+      }
+    }
+    return { scanned: slugs.length, repaired, failed };
+  }
+  /**
+   * Names in the sites directory.
+   *
+   * Listing goes through the COMMAND channel, so on a container edge it must name the
+   * path commands see: `sitesDir` is the HOST side of the bind mount and does not exist
+   * inside the container. Same directory either way, and only basenames are used — the
+   * reads that follow go back through the file channel at the host path.
+   */
+  async _lsSites() {
+    if (!this.executor) return fsReaddir(this.sitesDir);
+    const out = await this.executor.exec(
+      `ls -1 ${sq(this._commandSitesDir())} 2>/dev/null || true`
+    );
+    return out.split("\n").map((l) => l.trim()).filter(Boolean);
+  }
+  /**
+   * Slugs whose `.conf` does not carry the CURRENT generation marker — `null` when the
+   * question can't be answered in one command and the caller should fall back to reading.
+   *
+   * `grep -L` on the whole directory, so the steady state (everything current) costs one
+   * round trip instead of one per route. The pattern is anchored on both ends and built from
+   * the same constant the writer emits, so `gen: 1` cannot pass for `gen: 10` and the two
+   * halves cannot drift apart.
+   */
+  async _staleVhostSlugs() {
+    if (!this.executor) return null;
+    const dir = this._commandSitesDir();
+    const out = await this.executor.exec(
+      `grep -L ${sq(`^${GENERATION_MARKER}$`)} ${sq(dir)}/*.conf 2>/dev/null || true`
+    );
+    const slugs = /* @__PURE__ */ new Set();
+    for (const line of out.split("\n")) {
+      const name = line.trim().split("/").pop();
+      if (name?.endsWith(".conf")) slugs.add(name.slice(0, -".conf".length));
+    }
+    return slugs;
+  }
+  /**
+   * The sites directory as COMMANDS see it.
+   *
+   * On a container edge `sitesDir` is the HOST side of the bind mount and does not exist
+   * inside the container, where `exec` runs. Same directory, two names; only basenames are
+   * used, and the reads that follow go back through the file channel at the host path.
+   */
+  _commandSitesDir() {
+    return this.containerEdge ? OPENRESTY_DEFAULT_PATHS.sitesDir : this.sitesDir;
+  }
+  /**
+   * Recover the proxy tunables from a vhost we already wrote, for the legacy
+   * no-sidecar re-register below. Rewriting the conf without them would silently
+   * revert a site to nginx's 1 MB / 60 s defaults as a side effect of issuing a
+   * certificate — the one moment an operator is least likely to look for it.
+   *
+   * Same table as the renderer, read backwards, so the two cannot drift.
+   */
+  scrapeProxySettings(conf) {
+    const found = {};
+    for (const spec of PROXY_DIRECTIVES) {
+      const m = conf.match(
+        new RegExp(`^\\s*${spec.directive}\\s+([^;\\n]+);`, "m")
+      );
+      if (!m?.[1]) continue;
+      const parsed = parseProxyValue(spec, m[1].trim());
+      if (parsed !== void 0) found[spec.key] = parsed;
+    }
+    return sanitizeProxySettings(found);
+  }
+  /**
+   * Remove a route by deleting its conf + route-state files, then reload.
+   *
+   * Self-rollback (same pattern as registerRoute): snapshot both files first, and
+   * if the post-removal `openresty -t`/reload fails — usually because an UNRELATED
+   * vhost is broken — restore them so the edge on disk == the running config.
+   * Without this, a failed reload left the route GONE from disk but still served
+   * from the old in-memory config (an inconsistent half-state that would silently
+   * vanish on the next unrelated reload). The error is re-thrown for retry.
+   */
+  async removeRoute(domain, opts) {
+    assertValidDomain(domain);
+    if (opts?.signal?.aborted) {
+      throw new Error(`Route removal aborted before it started: ${domain}`);
+    }
+    const slug = await this.resolveSlug(domain);
+    const configPath = join(this.sitesDir, `${slug}.conf`);
+    const statePath = this.routeStatePath(slug);
+    const confSnapshot = await this._captureFile(configPath);
+    const stateSnapshot = await this._captureFile(statePath);
+    await this._rm(configPath);
+    await this._rm(statePath).catch(() => void 0);
+    try {
+      await this.reload({ allowStopped: true });
+    } catch (err) {
+      try {
+        if (!opts?.signal?.aborted)
+          await this._restoreFile(configPath, confSnapshot);
+        if (!opts?.signal?.aborted)
+          await this._restoreFile(statePath, stateSnapshot);
+        if (!opts?.signal?.aborted) {
+          await this.reload({ allowStopped: true }).catch(() => void 0);
+        }
+      } finally {
+        if (opts?.signal?.aborted) {
+          await this._rm(configPath).catch(() => void 0);
+          await this._rm(statePath).catch(() => void 0);
+        }
+      }
+      throw err;
+    }
+    await this._rm(this.bootstrapCertDir(domain)).catch(() => void 0);
+  }
+  // ── Edge-target challenge ────────────────────────────────────────────
+  /** Filename for a host's challenge vhost. The leading `_` is a namespace
+   *  `resolveSlug` can never produce (`domainSlug` emits only `[A-Za-z0-9-]`), so no
+   *  `registerRoute`/`removeRoute` for any domain can overwrite or delete it —
+   *  matching the existing `_default.conf` / `_management.conf` convention. */
+  challengeVhostPath(host) {
+    return join(
+      this.sitesDir,
+      `_oblien-challenge-${this.domainSlug(host)}.conf`
+    );
+  }
+  /**
+   * Make `host` able to answer edge-target challenges, and serve any tokens given.
+   *
+   * Called TWO ways, and the split is the point:
+   *   - `{ host }` alone, from edge-ensure (install + every deploy) — writes only the
+   *     vhost, so the box can answer before any verification exists.
+   *   - `{ host, tokens }`, from the verify flow — writes the token files too.
+   *
+   * That the first form is possible at all is what makes this ready from first
+   * install rather than only once a challenge is in flight: the location serves a
+   * DIRECTORY, so it is valid with nothing in it (a missing token is a 404, which is
+   * the right answer). And because the vhost lands in the bind-mounted sites-enabled
+   * written by our own code, it works on ANY edge image — including one predating
+   * this feature, and including a rollback. The baked image's catch-all cannot make
+   * that claim, which is why it is not the mechanism.
+   *
+   * Idempotent: skips the vhost write AND the reload when what is on disk already
+   * matches, so re-asserting on every deploy costs a couple of stats.
+   *
+   * `tokens` is a list because a re-issued verification resets the token while an
+   * older record may still be probed, and because two orgs can target one box. All
+   * are served; none is ever removed — Oblien re-probes the SAME token near its
+   * 90-day expiry, so dropping one silently kills that route ~83 days later.
+   */
+  async serveEdgeChallenge(input) {
+    const host = input.host.trim().toLowerCase().replace(/\.$/, "");
+    assertValidDomain(host);
+    const tokens = input.tokens ?? [];
+    for (const token of tokens) assertValidChallengeToken(token);
+    for (const token of tokens) {
+      await this._writeFile(join(this.challengeDir, token), token);
+    }
+    const base = this.domainSlug(host);
+    for (const stem of [base, `${base}-${this.slugSuffix(host)}`]) {
+      const path2 = join(this.sitesDir, `${stem}.conf`);
+      const conf = await this._readFile(path2).catch(() => "");
+      if (!conf || !this.serverNamesIn(conf).includes(host)) continue;
+      if (conf.includes(`${EDGE_CHALLENGE_URL_PREFIX} {`)) {
+        return { served: true, via: "existing-vhost" };
+      }
+      return {
+        served: false,
+        via: null,
+        claimedBy: path2,
+        reason: `${host} is already served by ${path2}, which predates edge-target challenge support. Re-register that domain (a deploy or a Domains-tab save) to refresh its vhost, then retry.`
+      };
+    }
+    const vhost = edgeChallengeVhostConf(host);
+    const path = this.challengeVhostPath(host);
+    const existing = await this._readFile(path).catch(() => "");
+    if (existing === vhost) return { served: true, via: "challenge-vhost" };
+    const snapshot = await this._captureFile(path);
+    await this._writeFile(path, vhost);
+    try {
+      await this.reload();
+    } catch (err) {
+      await this._restoreFile(path, snapshot);
+      await this.reload().catch(() => void 0);
+      throw err;
+    }
+    return { served: true, via: "challenge-vhost" };
+  }
+  // ── SSL ──────────────────────────────────────────────────────────────
+  /**
+   * Provision a TLS certificate using certbot.
+   *
+   * HTTP-01 ONLY — there is no DNS-01 path anywhere in this file, and the DNS credentials the
+   * product stores are for record MANAGEMENT, not for challenges.
+   *
+   * The authenticator is `--standalone` on {@link ACME_HTTP01_PORT} (a loopback alt-port), with
+   * the edge proxying `/.well-known/acme-challenge/` to it — see `ACME_CHALLENGE_LOCATION`. So
+   * Let's Encrypt fetches the challenge over :80 from OpenResty, which forwards it to certbot's
+   * transient listener. No port-80 fight, no webroot directory to keep in sync, and zero
+   * downtime: certbot holds that port only while issuing.
+   *
+   * THIS COMMENT USED TO DESCRIBE `--webroot`, and argued that `--standalone` was dead code
+   * because "certbot --standalone binds to port 80 itself, but OpenResty already owns 80". That
+   * was true of plain `--standalone`, and it is exactly the problem `--http-01-port` solves —
+   * the two sat contradicting each other in one file, with the doc describing a mechanism the
+   * code below had stopped using. Left recorded because the stale version's reasoning is
+   * persuasive enough to "fix" the code back.
+   *
+   * The caller (route-registration.ts) wraps this in try/catch, so a failure becomes a "deploy
+   * continues on HTTP, retry from the Domains tab" warning rather than a deploy abort.
+   */
+  async provisionCert(domain, opts) {
+    assertValidDomain(domain);
+    if (!opts?.force && await this.certsExist(domain)) {
+      return this.readCertInfo(domain);
+    }
+    const validEmail = !!this.acmeEmail && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(this.acmeEmail);
+    const emailArgs = validEmail ? ["--email", this.acmeEmail] : ["--register-unsafely-without-email"];
+    let certonlyOut = "";
+    const eabConfig = await this.createEphemeralEabConfig();
+    let generatedDnsHooks = null;
+    try {
+      generatedDnsHooks = await this.createEphemeralDnsHooks(opts);
+      const isDnsChallenge = opts?.challenge === "dns-01" || domain.startsWith("*.");
+      const challengeArgs = isDnsChallenge ? [
+        "certonly",
+        "--manual",
+        "--preferred-challenges",
+        "dns",
+        ...generatedDnsHooks?.authCommand || opts?.dnsAuthHook ? [
+          "--manual-auth-hook",
+          generatedDnsHooks?.authCommand ?? opts.dnsAuthHook
+        ] : [],
+        ...generatedDnsHooks?.cleanupCommand || opts?.dnsCleanupHook ? [
+          "--manual-cleanup-hook",
+          generatedDnsHooks?.cleanupCommand ?? opts.dnsCleanupHook
+        ] : []
+      ] : [
+        "certonly",
+        "--standalone",
+        "--http-01-port",
+        String(ACME_HTTP01_PORT)
+      ];
+      certonlyOut = await this._execCertbot(
+        [
+          ...eabConfig ? ["--config", eabConfig] : [],
+          ...challengeArgs,
+          "--cert-name",
+          domain,
+          "-d",
+          domain,
+          ...this.acmeDirectoryUrl ? ["--server", this.acmeDirectoryUrl] : [],
+          ...acmeKeyArgs(this.acmeKeyType),
+          ...emailArgs,
+          ...this.acmeTosAgreed ? ["--agree-tos"] : [],
+          "--non-interactive",
+          // Forced reissue: certbot would otherwise print "not due for renewal"
+          // (exit 0) when a lineage exists, leaving the stale cert in place.
+          ...opts?.force ? ["--force-renewal"] : []
+        ],
+        opts?.onLog
+      );
+    } catch (err) {
+      const raw = this.redactAcmeSecrets(safeErrorMessage(err));
+      let summary = summarizeCertbotFailure(raw, domain);
+      if (isAcmePortBindFailure(raw) && this.executor) {
+        const occupant = await probeListeningPort(
+          this.executor,
+          ACME_HTTP01_PORT
+        ).catch(() => null);
+        if (occupant) {
+          summary += ` Currently held by ${occupant.command}` + (occupant.pid !== null ? ` (pid ${occupant.pid})` : "") + (occupant.systemdUnit ? ` via ${occupant.systemdUnit}` : "") + `.`;
+        }
+      }
+      throw new Error(summary);
+    } finally {
+      if (eabConfig) await this._rm(dirname(eabConfig)).catch(() => void 0);
+      if (generatedDnsHooks)
+        await this._rm(generatedDnsHooks.dir).catch(() => void 0);
+    }
+    const slug = await this.resolveSlug(domain);
+    const configPath = join(this.sitesDir, `${slug}.conf`);
+    try {
+      const state = await this._readFile(this.routeStatePath(slug));
+      const saved = JSON.parse(state);
+      await this.registerRoute({ ...saved, domain, tls: true });
+      return this.ensureIssued(domain, certonlyOut);
+    } catch {
+    }
+    try {
+      const existing = await this._readFile(configPath);
+      const scraped = this.scrapeProxySettings(existing);
+      const targetMatch = existing.match(/proxy_pass\s+([^;]+);/);
+      if (targetMatch) {
+        await this.registerRoute({
+          domain,
+          targetUrl: targetMatch[1],
+          tls: true,
+          ...scraped ? { proxy: scraped } : {}
+        });
+        return this.ensureIssued(domain, certonlyOut);
+      }
+      const rootMatch = existing.match(/root\s+([^;]+);/);
+      if (rootMatch) {
+        await this.registerRoute({
+          domain,
+          staticRoot: rootMatch[1],
+          staticRootAdopted: true,
+          tls: true,
+          ...scraped ? { proxy: scraped } : {}
+        });
+        return this.ensureIssued(domain, certonlyOut);
+      }
+    } catch {
+    }
+    return this.ensureIssued(domain, certonlyOut);
+  }
+  /**
+   * After a certbot run that DIDN'T throw, confirm a usable cert actually landed
+   * at the expected path. certbot can exit 0 while producing nothing readable
+   * there (a lineage written elsewhere, "not due for renewal", 0 domains
+   * authenticated) — a silent `{missing}` hides why.
+   *
+   * The exit code plus this read of `live/<domain>` is the WHOLE verdict. certbot's
+   * stdout is evidence for the operator, never the test: a zero-exit run ends with
+   * the donation footer, and running the failure summarizer over it reported
+   * "Donating to ISRG / Let's Encrypt: …" as the cause of a cert that had in fact
+   * been issued. Only a diagnosis that matches a KNOWN failure shape is quoted.
+   */
+  async ensureIssued(domain, certbotOutput) {
+    const result = await this.readCertInfo(domain);
+    if (result.verified) return result;
+    const dir = join(this.certDir, domain);
+    const onDisk = result.reason === "read_error" ? `a certificate is at ${dir} but couldn't be read (permissions, or a partial write)` : result.reason === "invalid" ? `the certificate at ${dir} isn't usable for ${domain} (expired, wrong hostname, or the key doesn't match)` : `no certificate is at ${dir}`;
+    const diagnosis = certbotDiagnosis(certbotOutput, domain);
+    const tail = certbotOutput.trim().slice(-1200);
+    throw new Error(
+      `certbot exited without an error but ${onDisk}.` + (diagnosis ? ` ${diagnosis}` : "") + (tail ? `
+
+certbot said:
+${tail}` : "")
+    );
+  }
+  /**
+   * Renew a TLS certificate using certbot.
+   */
+  async renewCert(domain, opts) {
+    assertValidDomain(domain);
+    if (opts?.challenge === "dns-01" || domain.startsWith("*.")) {
+      return this.provisionCert(domain, {
+        ...opts,
+        challenge: "dns-01",
+        force: true
+      });
+    }
+    if (!await this.certsExist(domain)) {
+      return this.provisionCert(domain, opts);
+    }
+    if (!await this.hasCertbotLineage(domain)) {
+      return this.provisionCert(domain, { ...opts, force: true });
+    }
+    if (!await this.lineageServerMatches(domain)) {
+      return this.provisionCert(domain, { ...opts, force: true });
+    }
+    await this._execCertbot(
+      [
+        "renew",
+        "--cert-name",
+        domain,
+        ...acmeKeyArgs(this.acmeKeyType),
+        "--non-interactive"
+      ],
+      opts?.onLog
+    );
+    await this.reload();
+    return this.readCertInfo(domain);
+  }
+  /**
+   * Does certbot track a renewal lineage for this domain? `/etc/letsencrypt/renewal/
+   * <domain>.conf` is the per-lineage record certbot writes on first issuance and
+   * reads on every `renew`, so its presence is the authoritative answer — the cert
+   * FILES existing is not (they can be adopted, or copied in by hand).
+   */
+  renewalConfPath(domain) {
+    return join(dirname(this.certDir), "renewal", `${domain}.conf`);
+  }
+  async hasCertbotLineage(domain) {
+    return this._exists(this.renewalConfPath(domain));
+  }
+  /**
+   * Was this lineage issued by the CURRENTLY configured ACME directory? The
+   * renewal conf records the issuing `server`, and `certbot renew` only holds an
+   * account for THAT server — after the operator points at a different CA, renewing
+   * a pre-switch lineage would need an account registration `renew` cannot perform
+   * (and EAB material it is never given). An unreadable/unparsable conf answers
+   * `true` so the plain renew still runs and surfaces certbot's own error.
+   */
+  async lineageServerMatches(domain) {
+    let conf;
+    try {
+      conf = await this._readFile(this.renewalConfPath(domain));
+    } catch {
+      return true;
+    }
+    const recorded = conf.match(/^\s*server\s*=\s*(\S+)\s*$/m)?.[1];
+    if (!recorded) return true;
+    const effective = this.acmeDirectoryUrl ?? LETSENCRYPT_PRODUCTION_DIRECTORY;
+    return recorded === effective;
+  }
+  /**
+   * Install an operator-supplied or adopted certificate (no ACME). Validates the
+   * PEM pair against the domain, writes it to the same on-disk path certbot uses,
+   * then re-registers the vhost with TLS — mirroring provisionCert's tail so
+   * composite routes are preserved.
+   *
+   * The validation is deliberately here, at the last gate before disk, and not
+   * only in the callers: every path that puts a cert on this box (operator upload,
+   * migration carry, cert reuse) funnels through this method, so a check here can't
+   * be bypassed by a new caller that forgets it.
+   */
+  async installCert(domain, cert) {
+    assertValidDomain(domain);
+    const candidate = validateCertFor(domain, cert, "supplied certificate");
+    if (!candidate.cert)
+      throw new Error(`Invalid certificate: ${candidate.reason}`);
+    const { expiresAt } = candidate.cert;
+    const dir = join(this.certDir, domain);
+    await this.stageCertDir(dir, cert);
+    const slug = await this.resolveSlug(domain);
+    try {
+      const state = await this._readFile(this.routeStatePath(slug));
+      const saved = JSON.parse(state);
+      await this.registerRoute({ ...saved, domain, tls: true });
+    } catch {
+    }
+    return {
+      domain,
+      expiresAt,
+      issuer: candidate.cert.renewable ? candidate.cert.issuer : "manual",
+      verified: true,
+      reason: "issued"
+    };
+  }
+  // ── Helpers ──────────────────────────────────────────────────────────
+  /**
+   * Filename stem for a domain. NOT injective — see `resolveSlug`.
+   *
+   * Kept exactly as-is on purpose: it names every vhost file on every existing
+   * install, so changing it would rename the lot and leave the old names behind
+   * still serving. `resolveSlug` handles the collisions instead.
+   */
+  domainSlug(domain) {
+    return domain.replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-");
+  }
+  /** Deterministic per-domain disambiguator for a slug collision. */
+  slugSuffix(domain) {
+    return createHash("sha1").update(domain).digest("hex").slice(0, 8);
+  }
+  /** Every `server_name` token declared in a vhost body. */
+  serverNamesIn(conf) {
+    const names = [];
+    for (const m of conf.matchAll(/server_name\s+([^;]+);/g)) {
+      for (const tok of m[1].trim().split(/\s+/)) {
+        if (tok) names.push(tok.toLowerCase().replace(/\.$/, ""));
+      }
+    }
+    return names;
+  }
+  /**
+   * The slug THIS domain's files live under.
+   *
+   * `domainSlug` folds every non-alphanumeric to `-`, so a dot and a literal dash
+   * collapse together and two different, separately-claimable hostnames land on
+   * one filename:
+   *
+   *     staging.app.example.com  ->  staging-app-example-com
+   *     staging-app.example.com  ->  staging-app-example-com
+   *
+   * Both are ordinary hostnames and can belong to different projects — even
+   * different orgs, since one edge fronts the whole box. Whichever registered last
+   * silently overwrote the other's vhost, and the loser's traffic fell through to
+   * `default_server`: a silent outage of somebody else's domain. `removeRoute` on
+   * either one deleted the shared file and took out both.
+   *
+   * Resolution, in this order, and the order is the whole correctness argument:
+   *
+   *   1. A disambiguated file for this domain already exists → keep using it.
+   *      MUST come first. If the incumbent is later removed, step 3 would hand
+   *      this domain the now-free base name while its real conf stayed on disk
+   *      under the suffixed name — two files serving one hostname, which is the
+   *      exact orphan class this whole change exists to remove.
+   *   2. The base file exists and does NOT list this domain in its `server_name`
+   *      → it is someone else's. Take a suffixed name; the incumbent is untouched.
+   *   3. Otherwise the base name is ours (free, or already ours).
+   *
+   * Containment, not equality, in step 2 — and the reason is narrower than it
+   * looks. Everything WE write carries exactly one `server_name` (see the server
+   * blocks above), and a takeover fans out one `registerRoute` per hostname
+   * (`registerImportedSites`), so no Kraft-managed conf ever lists two. The
+   * only file that can is one the operator placed in `sites-enabled` themselves.
+   *
+   * For that file, reusing it is the lesser evil, not a free win: we rewrite it
+   * with a single `server_name`, so a sibling hostname it also served stops being
+   * served. The alternative is worse — a second vhost answering a name the first
+   * one already claims makes OpenResty warn "conflicting server name" and silently
+   * keep the FIRST, so the route we were asked to create would not take effect at
+   * all. Losing the sibling is at least the outcome the caller asked for.
+   */
+  async resolveSlug(domain) {
+    const base = this.domainSlug(domain);
+    const suffixed = `${base}-${this.slugSuffix(domain)}`;
+    const host = domain.toLowerCase().replace(/\.$/, "");
+    if (await this._exists(join(this.sitesDir, `${suffixed}.conf`)).catch(
+      () => false
+    )) {
+      return suffixed;
+    }
+    const basePath = join(this.sitesDir, `${base}.conf`);
+    if (await this._exists(basePath).catch(() => false)) {
+      const conf = await this._readFile(basePath).catch(() => "");
+      if (conf) {
+        const names = this.serverNamesIn(conf);
+        if (names.length > 0 && !names.includes(host)) return suffixed;
+      }
+    }
+    return base;
+  }
+  /**
+   * Re-detect OpenResty paths and reload.
+   *
+   * Paths can become stale after an OpenResty reinstall (the binary or
+   * config may move). Re-detecting on every reload keeps the provider
+   * in sync without requiring an API restart.
+   */
+  async reload(opts = {}) {
+    if (this.executor) {
+      if (!this.pinPaths) {
+        try {
+          const freshPaths = await detectOpenRestyPaths(this.executor);
+          this.paths = freshPaths;
+          this.sitesDir = freshPaths.sitesDir;
+          this.nginxVersion = freshPaths.nginxVersion ?? this.nginxVersion;
+          this.reloadCommand = buildReloadCommand(freshPaths);
+        } catch {
+        }
+      }
+      if (this.containerEdge) {
+        await this.executor.exec(this.reloadCommand, { timeout: 15e3 });
+      } else {
+        await reloadBareOpenResty(this.executor, this.paths, {
+          allowStopped: opts.allowStopped ?? false
+        });
+      }
+      return;
+    }
+    if (this.containerEdge) {
+      await execFileAsync("sh", ["-lc", this.reloadCommand], {
+        timeout: 15e3
+      });
+      return;
+    }
+    const localExecutor = {
+      exec: async (command, execOpts) => {
+        const { stdout } = await execFileAsync("sh", ["-lc", command], {
+          timeout: execOpts?.timeout
+        });
+        return String(stdout);
+      }
+    };
+    await reloadBareOpenResty(localExecutor, this.paths, {
+      allowStopped: opts.allowStopped ?? false
+    });
+  }
+  async certsExist(domain) {
+    const certPath = join(this.certDir, domain, "fullchain.pem");
+    if (this.executor) {
+      return this.executor.exists(certPath);
+    }
+    try {
+      await fsReadFile(certPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Read the on-disk cert and report its validity. Distinguishes three cases so
+   * the caller never downgrades a healthy domain on a transient hiccup:
+   *   - file present + parses  → verified, real expiry
+   *   - file ABSENT            → not verified, reason "missing"  (no cert yet)
+   *   - file present, unreadable/unparseable → not verified, reason "read_error"
+   */
+  async readCertInfo(domain) {
+    if (!await this.certsExist(domain)) {
+      return {
+        domain,
+        expiresAt: "",
+        issuer: "certbot",
+        verified: false,
+        reason: "missing"
+      };
+    }
+    let certPem;
+    let keyPem;
+    try {
+      certPem = await this._readFile(
+        join(this.certDir, domain, "fullchain.pem")
+      );
+      keyPem = await this._readFile(join(this.certDir, domain, "privkey.pem"));
+    } catch {
+      return {
+        domain,
+        expiresAt: "",
+        issuer: "certbot",
+        verified: false,
+        reason: "read_error"
+      };
+    }
+    const candidate = validateCertFor(
+      domain,
+      { certPem, keyPem },
+      "on-disk certificate"
+    );
+    if (!candidate.cert) {
+      console.warn(
+        `[SSL] unusable cert on disk for ${domain}: ${candidate.reason}`
+      );
+      return {
+        domain,
+        expiresAt: "",
+        issuer: "certbot",
+        verified: false,
+        reason: "invalid"
+      };
+    }
+    return {
+      domain,
+      expiresAt: candidate.cert.expiresAt,
+      issuer: candidate.cert.issuer || "certbot",
+      verified: true
+    };
+  }
+  /**
+   * Read-only check that the Let's Encrypt cert is actually present + valid on
+   * the serving host. No certbot, no config rewrite — safe to call any time
+   * (deploy, "Recheck SSL" button).
+   */
+  async verifyCert(domain) {
+    assertValidDomain(domain);
+    return this.readCertInfo(domain);
+  }
+  // ── Rate Limiting ──────────────────────────────────────────────────
+  /** Dedicated include dir for Kraft-managed OpenResty snippets. */
+  get rateLimitIncludeDir() {
+    return join(dirname(this.sitesDir), "kraft-includes");
+  }
+  /** Path to the managed rate-limit snippet inside the dedicated include dir. */
+  get rateLimitConfPath() {
+    return join(this.rateLimitIncludeDir, "ratelimit.conf");
+  }
+  /**
+   * Apply rate limit configuration to OpenResty.
+   *
+   * Writes a `ratelimit.conf` snippet with geo whitelist, map, and
+   * limit_req_zone directives. Ensures an `include` for it exists in
+   * nginx.conf's http block. Then validates + reloads.
+   *
+   * Pass rps=0 to disable rate limiting entirely.
+   */
+  async applyRateLimit(config) {
+    const confPath = this.rateLimitConfPath;
+    const nginxConfPath = join(dirname(this.sitesDir), "nginx.conf");
+    const snapshots = {
+      nginx: await this._captureFile(nginxConfPath),
+      current: await this._captureFile(confPath)
+    };
+    const geoEntries = renderGeoEntries(config.whitelist);
+    const snippet = `# Auto-generated by Kraft - rate limit config
+# Edit via Settings > Rate Limiting in the dashboard
+
+geo $whitelist {
+${geoEntries.join("\n")}
+    }
+
+    map $whitelist $limit_key {
+        1   "";
+        0   $binary_remote_addr;
+    }
+
+    limit_req_zone $limit_key zone=global_limit:10m rate=${config.rps}r/s;
+    limit_req zone=global_limit burst=${config.burst} nodelay;
+    limit_req_status 429;
+`;
+    try {
+      await this.ensureRateLimitInclude();
+      if (config.rps <= 0) {
+        await this._rm(confPath);
+      } else {
+        await this._mkdir(this.rateLimitIncludeDir);
+        await this._writeFile(confPath, snippet);
+      }
+      await this.reload();
+    } catch (err) {
+      let rollbackError = null;
+      try {
+        await this._restoreFile(confPath, snapshots.current);
+        await this._restoreFile(nginxConfPath, snapshots.nginx);
+        await this.reload();
+      } catch (restoreErr) {
+        rollbackError = safeErrorMessage(restoreErr);
+      }
+      const message = safeErrorMessage(err);
+      if (rollbackError) {
+        throw new Error(`${message}; rollback failed: ${rollbackError}`);
+      }
+      throw err;
+    }
+  }
+  /**
+   * Read the current rate limit config from the snippet file.
+   * Returns a disabled config when the snippet doesn't exist yet.
+   * Returns null only when the file exists but couldn't be read or parsed.
+   */
+  async getRateLimitConfig() {
+    try {
+      const confPath = this.rateLimitConfPath;
+      if (!await this._exists(confPath)) {
+        return { rps: 0, burst: 0, whitelist: [] };
+      }
+      const content = await this._readFile(confPath);
+      if (content.includes("disabled"))
+        return { rps: 0, burst: 0, whitelist: [] };
+      const rpsMatch = content.match(/rate=(\d+)r\/s/);
+      const rps = rpsMatch ? parseInt(rpsMatch[1], 10) : 50;
+      const burstMatch = content.match(/burst=(\d+)/);
+      const burst = burstMatch ? parseInt(burstMatch[1], 10) : 20;
+      const whitelist = [];
+      const geoBlock = content.match(/geo \$whitelist \{([\s\S]*?)\}/);
+      if (geoBlock) {
+        const lines = geoBlock[1].split("\n");
+        for (const line of lines) {
+          const m = line.match(/^\s+([\da-fA-F.:\/]+)\s+1;/);
+          if (m && !["127.0.0.1/32", "::1/128"].includes(m[1]) && m[1] !== "default") {
+            whitelist.push(m[1]);
+          }
+        }
+      }
+      return { rps, burst, whitelist };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Ensure nginx.conf includes the rate limit snippet in its http block.
+   */
+  async ensureRateLimitInclude() {
+    const confDir = dirname(this.sitesDir);
+    const confPath = join(confDir, "nginx.conf");
+    const desiredIncludeLine = `include ${this.rateLimitIncludeDir}/*.conf;`;
+    const content = await this._readFile(confPath);
+    const trailingNewline = content.endsWith("\n");
+    const lines = content.split("\n");
+    const nextLines = [];
+    let foundDesiredInclude = false;
+    let changed = false;
+    await this._mkdir(this.rateLimitIncludeDir);
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed === desiredIncludeLine) {
+        if (foundDesiredInclude) {
+          changed = true;
+          continue;
+        }
+        foundDesiredInclude = true;
+      }
+      nextLines.push(line);
+    }
+    if (!foundDesiredInclude) {
+      const httpIndex = nextLines.findIndex(
+        (line) => /^\s*http\s*\{\s*$/.test(line)
+      );
+      if (httpIndex === -1) {
+        throw new Error(
+          `Failed to ensure rate-limit include: ${confPath} is missing an http block`
+        );
+      }
+      const indent = nextLines[httpIndex].match(/^\s*/)?.[0] ?? "";
+      nextLines.splice(httpIndex + 1, 0, `${indent}    ${desiredIncludeLine}`);
+      changed = true;
+    }
+    if (changed) {
+      const nextContent = nextLines.join("\n");
+      await this._writeFile(
+        confPath,
+        trailingNewline ? `${nextContent}
+` : nextContent
+      );
+    }
+  }
+};
+
+export {
+  containerCommand,
+  readMaybeInContainer,
+  edgeContainerExecutor,
+  validateCertFor,
+  isSafeCertPath,
+  readDeclaredPair,
+  VHOST_GENERATION,
+  readVhostGeneration,
+  renderProxyOptions,
+  renderProxyTlsOptions,
+  renderGeoEntries,
+  acmeKeyArgs,
+  assertValidChallengeToken,
+  MANAGED_STATIC_BASE,
+  isAcmePortBindFailure,
+  summarizeCertbotFailure,
+  NginxProvider
+};