openship 0.2.3 → 0.4.0

package/dist/chunk-JUJBBF5U.js

@@ -0,0 +1,746 @@
+import {
+  sq
+} from "./chunk-4CQWT2WL.js";
+import {
+  ACME_CHALLENGE_LOCATION,
+  ACME_HTTP01_PORT,
+  LUA_LOGGER_PATH,
+  RULES_GUARD_PATH,
+  buildReloadCommand,
+  detectOpenRestyPaths,
+  luaSourceAvailable
+} from "./chunk-E6W2JMMU.js";
+import {
+  PROXY_GZIP_TYPES,
+  safeErrorMessage,
+  sanitizeProxySettings
+} from "./chunk-JZLNHGLW.js";
+
+// ../../packages/adapters/src/infra/nginx.ts
+import {
+  access as fsAccess,
+  writeFile as fsWriteFile,
+  rm as fsRm,
+  mkdir as fsMkdir,
+  readFile as fsReadFile,
+  rename as fsRename
+} from "fs/promises";
+import { execFile as cpExecFile } from "child_process";
+import { randomBytes, X509Certificate, createPrivateKey } from "crypto";
+import { promisify } from "util";
+import { dirname, join } from "path";
+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 $scheme;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";`;
+function renderProxyLocations(route) {
+  if (!route.proxyLocations || route.proxyLocations.length === 0) return "";
+  return route.proxyLocations.map((loc) => {
+    assertValidUpstream(loc.targetUrl);
+    return `
+    location ${loc.pathPrefix} {
+        proxy_pass ${loc.targetUrl};
+        ${PROXY_HEADERS}
+    }`;
+  }).join("");
+}
+function renderRedirects(route) {
+  if (!route.redirects || route.redirects.length === 0) return "";
+  return route.redirects.map(
+    (r) => `
+    location ${r.exact ? "= " : ""}${r.path} {
+        return ${r.statusCode} ${r.destination};
+    }`
+  ).join("");
+}
+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;`)
+  );
+  return lines.length > 0 ? `
+${lines.join("\n")}` : "";
+}
+function renderProxyOptions(proxy) {
+  const p = sanitizeProxySettings(proxy);
+  if (!p) return "";
+  const lines = [];
+  if (p.clientMaxBodySize) lines.push(`    client_max_body_size ${p.clientMaxBodySize};`);
+  if (p.proxyReadTimeout) lines.push(`    proxy_read_timeout ${p.proxyReadTimeout};`);
+  if (p.proxySendTimeout) lines.push(`    proxy_send_timeout ${p.proxySendTimeout};`);
+  if (p.clientBodyTimeout) lines.push(`    client_body_timeout ${p.clientBodyTimeout};`);
+  if (p.proxyBuffering !== void 0) {
+    lines.push(`    proxy_buffering ${p.proxyBuffering ? "on" : "off"};`);
+  }
+  if (p.gzip !== void 0) {
+    lines.push(`    gzip ${p.gzip ? "on" : "off"};`);
+    if (p.gzip) {
+      lines.push(`    gzip_types ${PROXY_GZIP_TYPES};`);
+      lines.push(`    gzip_min_length 1024;`);
+    }
+  }
+  return lines.length > 0 ? `
+${lines.join("\n")}` : "";
+}
+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 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 assertValidUpstream(targetUrl) {
+  assertNoNginxInjection(targetUrl, "proxy target");
+  if (!/^https?:\/\/.+/.test(targetUrl)) {
+    throw new Error(`Invalid proxy target (must be http/https URL): ${targetUrl}`);
+  }
+}
+function assertValidStaticRoot(root) {
+  assertNoNginxInjection(root, "static root");
+  if (!root.startsWith("/") || root.includes("..")) {
+    throw new Error(`Invalid static root (must be an absolute path, no traversal): ${root}`);
+  }
+}
+var execFileAsync = promisify(cpExecFile);
+function summarizeCertbotFailure(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);
+  let diagnosis;
+  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 (/404|invalid response|unauthorized|"?status"?:?\s*40\d/i.test(text)) {
+    diagnosis = `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);
+  if (parts.length > 0) return parts.join(" \u2014 ");
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  return lines.slice(-3).join(" \xB7 ") || `certbot failed to issue a certificate for ${domain}`;
+}
+var NginxProvider = class {
+  sitesDir;
+  acmeEmail;
+  certDir;
+  executor;
+  reloadCommand;
+  constructor(opts) {
+    this.sitesDir = opts.paths.sitesDir;
+    this.acmeEmail = opts.acmeEmail;
+    this.certDir = opts.certDir ?? DEFAULT_CERT_DIR;
+    this.executor = opts.executor ?? null;
+    this.reloadCommand = buildReloadCommand(opts.paths);
+  }
+  // ── File operation helpers (dual-path: local or remote) ──────────────
+  async _writeFile(path, content) {
+    const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}-${randomBytes(4).toString("hex")}`;
+    if (this.executor) {
+      try {
+        await this.executor.writeFile(tmpPath, content);
+        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, "utf-8");
+        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);
+      } catch {
+      }
+    }
+  }
+  async _mkdir(path) {
+    if (this.executor) {
+      await this.executor.mkdir(path);
+    } else {
+      await fsMkdir(path, { recursive: true });
+    }
+  }
+  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));
+    }
+  }
+  /**
+   * 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) {
+    if (!onLog || !this.executor) {
+      const out = await this._exec("certbot", args);
+      if (out) onLog?.(out);
+      return out;
+    }
+    const full = `certbot ${args.map(sq).join(" ")}`;
+    let output = "";
+    const { code } = await this.executor.streamExec(full, (log) => {
+      output += log.message;
+      onLog(log.message);
+    });
+    if (code !== 0) throw new Error(output.trim() || `certbot exited ${code}`);
+    return output;
+  }
+  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 = this.domainSlug(route.domain);
+    const configPath = join(this.sitesDir, `${slug}.conf`);
+    if ("staticRoot" in route && route.staticRoot) {
+      assertValidStaticRoot(route.staticRoot);
+    } else {
+      assertValidUpstream(route.targetUrl);
+    }
+    const locationBody = "staticRoot" in route && route.staticRoot ? `root ${route.staticRoot};
+        index index.html;
+        try_files $uri $uri/ /index.html;` : `proxy_pass ${route.targetUrl};
+        ${PROXY_HEADERS}`;
+    const extraLocations = `${renderRedirects(route)}${renderProxyLocations(route)}`;
+    const serverHeaders = renderServerHeaders(route);
+    const proxyOpts = renderProxyOptions(route.proxy);
+    const webhookLocation = route.webhookProxy ? `
+    location /_openship/hooks/ {
+        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 $scheme;
+    }
+` : "";
+    const edgeLua = luaSourceAvailable();
+    const luaLogOnly = edgeLua ? `    log_by_lua_file ${LUA_LOGGER_PATH};` : "";
+    const luaProxy = edgeLua ? `    log_by_lua_file ${LUA_LOGGER_PATH};
+    access_by_lua_file ${RULES_GUARD_PATH};` : "";
+    let serverBlock;
+    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
+server {
+    listen 80;
+    server_name ${route.domain};
+
+${luaLogOnly}
+
+${ACME_CHALLENGE_LOCATION}
+
+    location / {
+        return 301 https://$server_name$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl;
+    server_name ${route.domain};
+
+${luaProxy}
+
+    ssl_certificate ${certPath};
+    ssl_certificate_key ${keyPath};
+${serverHeaders}${proxyOpts}
+${webhookLocation}${extraLocations}
+    location / {
+        ${locationBody}
+    }
+}
+`;
+    } else {
+      serverBlock = `# Auto-generated by Openship - do not edit manually
+server {
+    listen 80;
+    server_name ${route.domain};
+
+${luaProxy}
+${serverHeaders}${proxyOpts}
+${ACME_CHALLENGE_LOCATION}
+${webhookLocation}${extraLocations}
+    location / {
+        ${locationBody}
+    }
+}
+`;
+    }
+    const snapshot = await this._captureFile(configPath);
+    await this._writeFile(configPath, serverBlock);
+    try {
+      await this.reload();
+    } catch (err) {
+      await this._restoreFile(configPath, snapshot);
+      await this.reload().catch(() => void 0);
+      throw err;
+    }
+    await this._writeFile(this.routeStatePath(slug), JSON.stringify(route)).catch(() => void 0);
+  }
+  routeStatePath(slug) {
+    return join(this.sitesDir, `${slug}.route.json`);
+  }
+  /**
+   * 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) {
+    assertValidDomain(domain);
+    const slug = this.domainSlug(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();
+    } catch (err) {
+      await this._restoreFile(configPath, confSnapshot);
+      await this._restoreFile(statePath, stateSnapshot);
+      await this.reload().catch(() => void 0);
+      throw err;
+    }
+  }
+  // ── SSL ──────────────────────────────────────────────────────────────
+  /**
+   * Provision a TLS certificate using certbot.
+   *
+   * Runs `certbot certonly` in webroot mode using the ACME challenge
+   * directory served by OpenResty, then rewrites the config to include
+   * SSL and reloads.
+   *
+   * Only --webroot is attempted. The previous --standalone fallback was
+   * dead code on any normal install: certbot --standalone binds to port
+   * 80 itself, but OpenResty already owns 80 on the same box, so the
+   * fallback would always fail with EADDRINUSE — amplifying a transient
+   * --webroot failure into an immediate hard error. The caller
+   * (route-registration.ts) already wraps provisionCert in try/catch so
+   * a webroot failure becomes a "deploy continues on HTTP, retry from
+   * Domains tab" warning instead of 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 = "";
+    try {
+      certonlyOut = await this._execCertbot([
+        "certonly",
+        "--standalone",
+        "--http-01-port",
+        String(ACME_HTTP01_PORT),
+        "--cert-name",
+        domain,
+        "-d",
+        domain,
+        ...emailArgs,
+        "--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) {
+      throw new Error(summarizeCertbotFailure(safeErrorMessage(err), domain));
+    }
+    const slug = this.domainSlug(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 targetMatch = existing.match(/proxy_pass\s+([^;]+);/);
+      if (targetMatch) {
+        await this.registerRoute({ domain, targetUrl: targetMatch[1], tls: true });
+        return this.ensureIssued(domain, certonlyOut);
+      }
+      const rootMatch = existing.match(/root\s+([^;]+);/);
+      if (rootMatch) {
+        await this.registerRoute({ domain, staticRoot: rootMatch[1], tls: true });
+        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. Surface certbot's real
+   * output so the operator sees the actual reason instead of a generic message.
+   */
+  async ensureIssued(domain, certbotOutput) {
+    const result = await this.readCertInfo(domain);
+    if (result.verified) return result;
+    const tail = certbotOutput.trim().slice(-1200);
+    throw new Error(
+      summarizeCertbotFailure(certbotOutput, domain) + (tail ? `
+
+certbot exited without an error but no readable certificate is at ${join(this.certDir, domain)}. certbot said:
+${tail}` : "")
+    );
+  }
+  /**
+   * Renew a TLS certificate using certbot.
+   */
+  async renewCert(domain) {
+    assertValidDomain(domain);
+    if (!await this.certsExist(domain)) {
+      return this.provisionCert(domain);
+    }
+    await this._exec("certbot", ["renew", "--cert-name", domain, "--non-interactive"]);
+    await this.reload();
+    return this.readCertInfo(domain);
+  }
+  /**
+   * Install an operator-supplied certificate (no ACME). Validates the PEM pair,
+   * 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.
+   */
+  async installCert(domain, cert) {
+    assertValidDomain(domain);
+    let expiresAt;
+    try {
+      const x509 = new X509Certificate(cert.certPem);
+      const key = createPrivateKey(cert.keyPem);
+      if (!x509.checkPrivateKey(key)) {
+        throw new Error("private key does not match certificate");
+      }
+      expiresAt = new Date(x509.validTo).toISOString();
+    } catch (err) {
+      throw new Error(`Invalid certificate: ${safeErrorMessage(err)}`);
+    }
+    const dir = join(this.certDir, domain);
+    await this._mkdir(dir);
+    await this._writeFile(join(dir, "fullchain.pem"), cert.certPem);
+    await this._writeFile(join(dir, "privkey.pem"), cert.keyPem);
+    const slug = this.domainSlug(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: "manual", verified: true, reason: "issued" };
+  }
+  // ── Helpers ──────────────────────────────────────────────────────────
+  domainSlug(domain) {
+    return domain.replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-");
+  }
+  /**
+   * 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() {
+    if (this.executor) {
+      try {
+        const freshPaths = await detectOpenRestyPaths(this.executor);
+        this.sitesDir = freshPaths.sitesDir;
+        this.reloadCommand = buildReloadCommand(freshPaths);
+      } catch {
+      }
+      await this.executor.exec(this.reloadCommand);
+      return;
+    }
+    await execFileAsync("sh", ["-lc", this.reloadCommand]);
+  }
+  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" };
+    }
+    try {
+      const certPath = join(this.certDir, domain, "fullchain.pem");
+      const pem = await this._readFile(certPath);
+      const { X509Certificate: X509Certificate2 } = await import("crypto");
+      const cert = new X509Certificate2(pem);
+      return {
+        domain,
+        expiresAt: new Date(cert.validTo).toISOString(),
+        issuer: "certbot",
+        verified: true
+      };
+    } catch {
+      return { domain, expiresAt: "", issuer: "certbot", verified: false, reason: "read_error" };
+    }
+  }
+  /**
+   * 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 Openship-managed OpenResty snippets. */
+  get rateLimitIncludeDir() {
+    return join(dirname(this.sitesDir), "openship-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 Openship - 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 {
+  renderProxyOptions,
+  renderGeoEntries,
+  summarizeCertbotFailure,
+  NginxProvider
+};