openship 0.6.0 → 0.6.5

package/dist/{chunk-QEH4QUBX.js → chunk-VLQ3UIVO.js}

@@ -9,20 +9,27 @@ import {
 } from "./chunk-I3DPMTSF.js";
 import {
   edgeFailureReason
-} from "./chunk-VZ2ZHPS2.js";
+} from "./chunk-WE7BXW6L.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
-} from "./chunk-OGY63DGD.js";
+} from "./chunk-PZRRL5PC.js";
+import {
+  EXECUTOR_DELEGATE
+} from "./chunk-WFRXYWK2.js";
 import {
   logEntry,
   sq
@@ -34,7 +41,7 @@ import {
   resolveRedirectStatus,
   safeErrorMessage,
   sanitizeProxySettings
-} from "./chunk-OTLSJYAC.js";
+} from "./chunk-LEYSL46B.js";
 
 // ../../packages/adapters/src/infra/nginx.ts
 import {
@@ -43,6 +50,7 @@ import {
   rm as fsRm,
   mkdir as fsMkdir,
   readFile as fsReadFile,
+  readdir as fsReaddir,
   rename as fsRename,
   stat as fsStat
 } from "fs/promises";
@@ -168,6 +176,7 @@ ${result.output}` };
   }
   return new Proxy(inner, {
     get(target, prop) {
+      if (prop === EXECUTOR_DELEGATE) return void 0;
       if (Object.prototype.hasOwnProperty.call(overrides, prop)) {
         return overrides[prop];
       }
@@ -305,6 +314,7 @@ async function probeStaticOutput(executor, servedPath) {
 
 // ../../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;
@@ -318,16 +328,69 @@ var FORWARD_VARS = `    set $openship_fwd_proto $scheme;
         set $openship_fwd_proto https;
         set $openship_redirect_https 0;
     }`;
-function renderProxyLocations(route) {
+var VHOST_GENERATION = 1;
+var GENERATION_MARKER = `# openship-vhost-gen: ${VHOST_GENERATION}`;
+var GENERATED_HEADER = `# Auto-generated by Openship - do not edit manually
+${GENERATION_MARKER}`;
+function readVhostGeneration(conf) {
+  const m = conf.match(/^# openship-vhost-gen: (\d+)$/m);
+  return m ? Number(m[1]) : null;
+}
+var HTTPS_UPGRADE = `if ($openship_redirect_https) {
+            return 301 https://$server_name$request_uri;
+        }
+
+        `;
+var WEBHOOK_LOCATION_PREFIX = "/_openship/hooks/";
+function renderProxyLocations(route, opts) {
   if (!route.proxyLocations || route.proxyLocations.length === 0) return "";
-  return route.proxyLocations.map((loc) => {
+  const head = `${opts.httpsUpgrade ? HTTPS_UPGRADE : ""}${renderRedirectRules(route, "        ")}`;
+  const claimed = /* @__PURE__ */ new Set(["/", WEBHOOK_LOCATION_PREFIX]);
+  const blocks = [];
+  for (const loc of route.proxyLocations) {
     assertValidUpstream(loc.targetUrl);
-    return `
-    location ${loc.pathPrefix} {
+    assertNotReservedLocation(loc.pathPrefix);
+    const headers = loc.external ? externalProxyHeaders(loc.targetUrl) : PROXY_HEADERS;
+    if (!loc.pattern || !loc.upstreamPath) {
+      assertValidLiteralPath(loc.pathPrefix, "proxy location prefix");
+      if (claimed.has(loc.pathPrefix)) continue;
+      claimed.add(loc.pathPrefix);
+      blocks.push(`
+    location ^~ ${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(`~ ${match}`)) continue;
+    claimed.add(`~ ${match}`);
+    blocks.push(`
+    location ~ ${match} {
+        ${head}rewrite ${match} ${loc.upstreamPath} break;
         proxy_pass ${loc.targetUrl};
-        ${PROXY_HEADERS}
-    }`;
-  }).join("");
+        ${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;
@@ -335,23 +398,98 @@ function renderHostRedirect(route) {
   assertValidDomain(redirect.target);
   return `return ${resolveRedirectStatus(redirect.statusCode)} https://${redirect.target}$request_uri;`;
 }
-function renderRedirects(route) {
+function renderRedirectRules(route, indent) {
   if (!route.redirects || route.redirects.length === 0) return "";
-  return route.redirects.map(
-    (r) => `
-    location ${r.exact ? "= " : ""}${r.path} {
-        return ${r.statusCode} ${r.destination};
-    }`
-  ).join("");
+  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 renderServerHeaders(route) {
-  const global = (route.headerRules ?? []).filter((rule) => rule.path === "/");
-  const lines = global.flatMap(
-    (rule) => rule.headers.map((h) => `    add_header ${h.key} "${h.value.replace(/"/g, '\\"')}" always;`)
+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",
@@ -427,16 +565,58 @@ function assertValidDomain(domain) {
   }
 }
 function assertNoNginxInjection(value, what) {
-  if (/[\s;{}#\\]/.test(value)) {
+  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("..")) {
@@ -531,10 +711,11 @@ var NginxProvider = class {
   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.executor.exec(`chmod ${sq(mode.toString(8))} ${sq(tmpPath)}`);
+          await this._chmod(tmpPath, mode);
         }
         if (this.executor.rename) {
           await this.executor.rename(tmpPath, path);
@@ -590,6 +771,46 @@ var NginxProvider = class {
       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.
    *
@@ -606,7 +827,7 @@ var NginxProvider = class {
     try {
       await this._mkdir(staging);
       await this._writeFile(join(staging, "fullchain.pem"), cert.certPem);
-      await this._writeFile(join(staging, "privkey.pem"), cert.keyPem);
+      await this._writeFile(join(staging, "privkey.pem"), cert.keyPem, 384);
       if (this.executor) {
         await this._mkdir(dir);
         await this.executor.exec(
@@ -666,6 +887,12 @@ var NginxProvider = class {
     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 };
@@ -693,6 +920,7 @@ var NginxProvider = class {
         "-addext",
         `subjectAltName=DNS:${domain}`
       ]);
+      await this._chmod(join(staging, "privkey.pem"), 384);
       await this._mkdir(dir);
       if (this.executor) {
         await this.executor.exec(
@@ -796,13 +1024,10 @@ var NginxProvider = class {
     if (!this.acmeEabKid || !this.acmeEabHmacKey) return null;
     const dir = join(dirname(this.certDir), `.openship-eab-${randomBytes(12).toString("hex")}`);
     const path = join(dir, "eab.ini");
-    if (this.executor) {
-      await this.executor.mkdir(dir);
-      await this._exec("chmod", ["700", dir]);
-    } else {
-      await fsMkdir(dir, { recursive: true, mode: 448 });
-    }
+    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}
@@ -854,14 +1079,20 @@ eab-hmac-key = ${this.acmeEabHmacKey}
     const hostRedirect = renderHostRedirect(route);
     const locationBody = hostRedirect ? hostRedirect : "staticRoot" in route && route.staticRoot ? `root ${route.staticRoot};
         index index.html;
-        try_files $uri $uri/ /index.html;` : `proxy_pass ${route.targetUrl};
+        ${renderStaticTryFiles(route)}` : `proxy_pass ${route.targetUrl};
         ${PROXY_HEADERS}`;
-    const extraLocations = hostRedirect ? "" : `${renderRedirects(route)}${renderProxyLocations(route)}`;
-    const serverHeaders = hostRedirect ? "" : renderServerHeaders(route);
+    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 /_openship/hooks/ {
+    location ^~ ${WEBHOOK_LOCATION_PREFIX} {
         proxy_pass ${route.webhookProxy};
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
@@ -872,24 +1103,25 @@ eab-hmac-key = ${this.acmeEabHmacKey}
     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 / {
-        ${locationBody}
-    }`;
+        ${redirectRules}${urlShape}${locationBody}
+    }${slashFallback}`;
     const redirectOrServeLocation = hostRedirect ? serveLocation : `    location / {
-        if ($openship_redirect_https) {
-            return 301 https://$server_name$request_uri;
-        }
-
-        ${locationBody}
-    }`;
+        ${HTTPS_UPGRADE}${redirectRules}${urlShape}${locationBody}
+    }${slashFallback}`;
     const sharedBody = `${serverHeaders}${proxyOpts}
 ${webhookLocation}${extraLocations}`;
-    const httpOnlyBlock = `# Auto-generated by Openship - do not edit manually
+    const httpsUpgradeBody = `${serverHeaders}${proxyOpts}
+${webhookLocation}${upgradingExtraLocations}`;
+    const httpOnlyBlock = `${GENERATED_HEADER}
 server {
     listen 80;
     server_name ${route.domain};
 
-${FORWARD_VARS}
+${preamble}
 
 ${luaProxy}
 
@@ -905,19 +1137,19 @@ ${serveLocation}
     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 = `# Auto-generated by Openship - do not edit manually
+      serverBlock = `${GENERATED_HEADER}
 server {
     listen 80;
     server_name ${route.domain};
 
-${FORWARD_VARS}
+${preamble}
 
 ${luaProxy}
 
 ${ACME_CHALLENGE_LOCATION}
 
 ${EDGE_CHALLENGE_LOCATION}
-${sharedBody}
+${httpsUpgradeBody}
 ${redirectOrServeLocation}
 }
 
@@ -925,7 +1157,7 @@ server {
     listen 443 ssl;
     server_name ${route.domain};
 
-${FORWARD_VARS}
+${preamble}
 
 ${luaProxy}
 
@@ -938,7 +1170,7 @@ ${serveLocation}
     } else if (route.tls && route.terminatesTlsLocally) {
       const bootstrap = await this.ensureBootstrapCert(route.domain);
       bootstrapServed = !!bootstrap;
-      serverBlock = bootstrap ? `# Auto-generated by Openship - do not edit manually
+      serverBlock = bootstrap ? `${GENERATED_HEADER}
 # openship-bootstrap-tls: ${route.domain} is serving a TEMPORARY self-signed
 # certificate because its real certificate has not been issued yet. Openship
 # replaces this file automatically once it lands. Do not adopt this material.
@@ -946,7 +1178,7 @@ server {
     listen 80;
     server_name ${route.domain};
 
-${FORWARD_VARS}
+${preamble}
 
 ${luaProxy}
 
@@ -961,7 +1193,7 @@ server {
     listen 443 ssl;
     server_name ${route.domain};
 
-${FORWARD_VARS}
+${preamble}
 
 ${luaProxy}
 
@@ -975,7 +1207,7 @@ ${serveLocation}
       serverBlock = httpOnlyBlock;
     }
     const snapshot = await this._captureFile(configPath);
-    await this._writeFile(configPath, serverBlock);
+    await this._writeFile(configPath, `${prelude}${serverBlock}`);
     try {
       await this.reload();
     } catch (err) {
@@ -991,6 +1223,112 @@ ${serveLocation}
   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
@@ -1083,7 +1421,7 @@ ${serveLocation}
       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(`location ${EDGE_CHALLENGE_URL_PREFIX}`)) {
+      if (conf.includes(`${EDGE_CHALLENGE_URL_PREFIX} {`)) {
         return { served: true, via: "existing-vhost" };
       }
       return {
@@ -1619,6 +1957,8 @@ export {
   validateCertFor,
   isSafeCertPath,
   readDeclaredPair,
+  VHOST_GENERATION,
+  readVhostGeneration,
   renderProxyOptions,
   renderProxyTlsOptions,
   renderGeoEntries,