@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/runtime/docker/ingress/build-config.ts

@@ -0,0 +1,819 @@
+// Relative imports, not the package's own subpaths: this entry is on the SDK's
+// exports map, so an author bundle can pull it into QuickJS, and everything it
+// reaches must be a leaf that touches no host global
+// (`worker-protocol/quickjs-safe.test.ts` keeps that honest).
+import { HOME_COOKIE_PREFIX } from "../../../home-cookie.ts";
+import { structuredHost } from "../../../service-url.ts";
+import type { IngressInput } from "../../../worker-protocol/ingress.ts";
+// The leaf, never `worker-protocol/uplink/index.ts`: the barrel pulls the
+// session layer and `@yourrealm/noise` in, neither of which belongs in a
+// bundle this module can be reached from.
+import { REKEY_INTERVAL_MS, REKEY_JITTER_MS } from "../../../worker-protocol/uplink/constants.ts";
+import type {
+  CaddyConfig,
+  CaddyDynamicDns,
+  CaddyHandler,
+  CaddyHeaderRewrite,
+  CaddyIssuer,
+  CaddyProvider,
+  CaddyErrorRoute,
+  CaddyRoute,
+  CaddyTlsPolicy,
+} from "./types.ts";
+
+// Caddy JSON builder - the Docker worker's ingress renderer, the `ingress`
+// half of what `convertToDockerCompose` is for `apps`.
+//
+// Every routed service gets an authenticated subdomain on the worker's
+// wildcard (`{appId}-{service}.{workerId}.{baseDomain}`), gated by Home
+// ForwardAuth. A `router.publicDomain`, if present, is an *additional*
+// ungated public route.
+
+// Home ForwardAuth verify endpoint. Caddy can't dial Home itself: Home's
+// container name (`realm-home`) only resolves on the box that runs Home, and a
+// remote worker reaches Home over its own uplink — so a direct upstream would
+// 503 every gated route there. Caddy dials the local worker's verify relay over
+// the management bridge instead, and the worker forwards this one path to Home.
+const VERIFY_UPSTREAM = "realm-worker:6021";
+const VERIFY_PATH = "/api/access/verify";
+
+// `X-Realm-*` is the platform's own header namespace: Home and the worker
+// stamp into it and containers are told to trust what arrives there, so no
+// client may set any of it — including the platform headers an app never
+// declared, which the declared keys alone would miss. Caddy's `delete` takes
+// prefix, suffix and substring wildcards, so one entry covers the namespace,
+// and it never overlaps the declared keys beside it: `getTrustedHeaders`
+// rejects a name in this namespace at sampling time.
+const REALM_HEADER_WILDCARD = "X-Realm-*";
+
+// Matches any of Home's cookies (the `realm-home.*` namespace Home's
+// better-auth config claims via HOME_COOKIE_PREFIX) in a `Cookie` header,
+// with or without the `__Secure-` prefix. The namespace holds two: the
+// host-only session cookie that drives the dashboard, and the identity cookie
+// scoped to `.{workerSlug}.{baseDomain}` that the forward_auth hop reads.
+// Caddy's regexp replace removes every match, so an app sees neither, while
+// the app's own cookies pass through — including an app's better-auth cookies
+// under the library's default `better-auth.*` names, which is why Home does
+// not use them.
+const HOME_COOKIE_REGEX = `(__Secure-)?${HOME_COOKIE_PREFIX}\\.[^=]+=[^;]*;?\\s*`;
+
+// Matches a whole `Set-Cookie` value whose cookie NAME is one of Home's.
+// Anchored at both ends so an app cookie that merely contains the string
+// somewhere in its value is left alone; only a cookie actually named
+// `realm-home.*` is blanked.
+//
+// The response-direction twin of HOME_COOKIE_REGEX. The identity cookie is
+// scoped to `.{workerSlug}.{baseDomain}` and minted by the gate itself
+// (`access-gate.ts`, on a response served at the app host, which is the only
+// place that scope can be set from). A cookie may be set for any parent of the
+// setting host that isn't a public suffix, so WITHOUT this an app on
+// `{appId}-{service}.{workerSlug}.{baseDomain}` can answer with `Set-Cookie:
+// realm-home.app_identity=…; Domain=.{workerSlug}.{baseDomain}` and replace the
+// operator's real one — a forced logout at minimum, and at worst a fixated
+// value the gate resolves to whoever the app chose. The blank is
+// namespace-wide, so the session cookie's name is covered by the same pattern.
+// `__Host-` would forbid the Domain attribute outright, but the identity
+// cookie needs that Domain to reach the gate at all; the session cookie is
+// host-only already.
+//
+// Both regexes key on the cookie NAME, so the per-worker scope changed nothing
+// here — no ingress config moves with it.
+const HOME_SET_COOKIE_REGEX = `^(__Secure-)?${HOME_COOKIE_PREFIX}\\.[^=]*=.*$`;
+
+// Must stay brace-free: Caddy runs a static_response body through its
+// placeholder replacer, where `{` opens a placeholder, so a `<style>` block
+// would be parsed as one rather than served. Hence inline styles, and
+// `color-scheme` + the `Canvas`/`CanvasText` system colors for light and dark
+// without a media query.
+//
+// Reflects nothing from the request: `Host` is attacker-controlled and Home's
+// identity cookie is scoped to `.{workerSlug}.{baseDomain}`, so echoing it
+// would put an XSS inside that cookie's scope.
+function holdingPage(title: string, headline: string, detail: string): string {
+  return [
+    `<!doctype html>`,
+    `<html lang="en" style="color-scheme: light dark">`,
+    `<meta charset="utf-8">`,
+    `<meta name="viewport" content="width=device-width,initial-scale=1">`,
+    `<meta http-equiv="refresh" content="5">`,
+    `<title>${title}</title>`,
+    `<body style="background: Canvas; color: CanvasText; font-family: system-ui, sans-serif;` +
+      ` display: grid; place-items: center; min-height: 100vh; margin: 0; padding: 2rem;` +
+      ` box-sizing: border-box; text-align: center">`,
+    `<main style="max-width: 32rem">`,
+    `<h1 style="font-size: 1.25rem; font-weight: 600; margin: 0 0 0.75rem">${headline}</h1>`,
+    `<p style="margin: 0; opacity: 0.7; line-height: 1.5">${detail}</p>`,
+    `</main>`,
+  ].join("");
+}
+
+// Route present, upstream not answering: real app, container not up yet.
+const DEPLOYING_PAGE = holdingPage(
+  "Starting up",
+  "This app is starting up",
+  "Its container is not answering yet. This page reloads on its own.",
+);
+
+// Set on the request once Home has answered the forward_auth hop AND approved.
+// Absent on a route that has one means the dial to Home itself failed, which is
+// what separates "this app is down" from "Realm's control plane is down".
+const AUTH_OK_VAR = "realm_auth_ok";
+
+// The forward_auth dial failed, so Home never answered. The app may well be
+// fine — every subdomain on this worker fails the same way, because they all
+// verify against the same Home.
+const HOME_UNREACHABLE_PAGE = holdingPage(
+  "Realm is unreachable",
+  "Realm's control plane is not responding",
+  "Apps cannot be reached until it is back, even the ones still running.",
+);
+
+// No route at all: a name that never existed, or an app removed since the link
+// was made. Says less because Caddy knows less.
+const NOT_ROUTED_PAGE = holdingPage(
+  "Nothing here",
+  "Nothing is serving this address",
+  "No app on this worker answers to this name.",
+);
+
+// The Digital Asset Links statement the companion app's Trusted Web Activity
+// is verified against. Chrome fetches `/.well-known/assetlinks.json` from the
+// exact origin it is opening, without cookies, and drops its toolbar only when
+// the statement names the app's package and signing key. Every host the
+// ingress serves has to answer it - the dashboard, each app subdomain, each
+// public domain - because the upstream apps never will and the ingress cannot
+// inject one.
+//
+// The package name is a constant - a property of the published app, the same
+// wherever it is installed. The fingerprints are not: which certificate signs
+// the APK an operator's users actually run depends on how they got it, so they
+// are operator-set on Home and ride the wire, identical on every box of one
+// realm. An empty list is a valid statement that matches no app, so the route,
+// its ordering and its anonymity hold on a realm that has set none.
+//
+// The body is JSON, braces and all: static_response runs it through Caddy's
+// ReplaceKnown, which writes a brace span back verbatim unless the whole span
+// names a placeholder it knows. The span IS the key - Caddy's replacer does not
+// split it on the `:` a JSON object is full of, and its three providers answer
+// only `env.*`, `file.*`, a handful of `system.*`/`time.*` names and what the
+// HTTP server put in the request's own table. The only interpolated value is
+// schema-validated hex and colons, which can never form a placeholder either.
+// No span here resolves, so the statement reaches the wire byte for byte.
+const ASSET_LINKS_PATH = "/.well-known/assetlinks.json";
+const COMPANION_PACKAGE = "eu.yourrealm.companion";
+
+function assetLinksBody(fingerprints: readonly string[]): string {
+  return JSON.stringify([
+    {
+      relation: ["delegate_permission/common.handle_all_urls"],
+      target: {
+        namespace: "android_app",
+        package_name: COMPANION_PACKAGE,
+        sha256_cert_fingerprints: fingerprints,
+      },
+    },
+  ]);
+}
+
+const DEFAULT_SECURITY_HEADERS: Record<string, string> = {
+  "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+  "X-Frame-Options": "SAMEORIGIN",
+  "X-Content-Type-Options": "nosniff",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+};
+
+// The same defaults in Caddy's header-map shape (one list per name). Every
+// response the ingress writes itself - the holding pages, the asset links
+// statement - is a static_response outside `buildContentHandlers`, so each one
+// carries them from here rather than from a route chain.
+function securityHeaderLists(): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(DEFAULT_SECURITY_HEADERS).map(([k, v]) => [k, [v]]));
+}
+
+// In-container path the issuer below points at for the ACME root PEM.
+// Exported because whoever materializes that file (the worker, into the
+// directory the ingress mounts at /etc/caddy) has to use the same string.
+export const ACME_CA_ROOT_PATH = "/etc/caddy/acme-ca-root.pem";
+
+// How long an in-flight upgraded stream outlives a config reload. Remote
+// workers hold their uplink through the dashboard route, and every deploy on
+// Home's box reloads Caddy, which force-closes upgraded streams; without this
+// every deploy would bounce every remote worker. The bound is the longest a
+// session is allowed to live - the rekey interval plus its jitter - rounded up
+// to whole hours, so a stream is never cut before it would have reconnected
+// anyway.
+const STREAM_CLOSE_DELAY = `${Math.ceil((REKEY_INTERVAL_MS + REKEY_JITTER_MS) / 3_600_000)}h`;
+
+// The credential half of the acme-dns DNS-01 issuer. Creds are inlined into the
+// issuer config (see buildAcmeDnsIssuer for why the env-placeholder form can't
+// be used).
+type AcmeIssuerInput = NonNullable<IngressInput["acmeDns"]>;
+
+type IngressRoutedApp = IngressInput["routedApps"][number];
+type IngressRouter = IngressRoutedApp["services"][number]["router"];
+type PublicProviderInput = IngressInput["publicProviders"][number];
+
+/**
+ * The renderer's parameter: the wire's `ingress` field.
+ *
+ * `IngressInput` verbatim - the point of the wire being typed is that this
+ * function's input IS the protocol, not a parallel shape that can drift from
+ * it. The three arrays are re-declared only to accept `readonly` ones, since
+ * nothing here mutates its input.
+ */
+export type BuildInput = Omit<
+  IngressInput,
+  "routedApps" | "publicProviders" | "companionFingerprints"
+> & {
+  readonly routedApps: readonly IngressRoutedApp[];
+  readonly publicProviders: readonly PublicProviderInput[];
+  readonly companionFingerprints: readonly string[];
+};
+
+export function buildCaddyConfig(input: BuildInput): CaddyConfig {
+  const { routedApps, dashboardHost, workerId, baseDomain, acmeDns, publicProviders } = input;
+  const { cdnProviders, companionFingerprints } = input;
+  const routes: CaddyRoute[] = [];
+
+  // The placeholder upstreams + the rate-limiter read the client IP from.
+  // Caddy stores the resolved client IP in the request's vars table under
+  // "client_ip" when server-level `trusted_proxies` is configured. The
+  // JSON-config placeholder is `{http.vars.client_ip}` — `{client_ip}` is a
+  // Caddyfile-only shorthand that doesn't exist in JSON config. With no
+  // trusted proxies the placeholder stays literal, so on the default path
+  // (Caddy IS the edge) `{http.request.remote.host}` always resolves.
+  const clientIp = cdnProviders.length > 0 ? "{http.vars.client_ip}" : "{http.request.remote.host}";
+
+  // First route, matched on path alone, so it answers on every host ahead of
+  // the dashboard proxy, the forward_auth hop and the wildcard holding page.
+  // Chrome fetches it anonymously from each origin it opens: behind the gate
+  // it would bounce to login, behind the wildcard it would be the not-routed
+  // page on any host without an app.
+  routes.push({
+    match: [{ path: [ASSET_LINKS_PATH] }],
+    handle: [
+      {
+        handler: "static_response",
+        status_code: 200,
+        headers: {
+          "Content-Type": ["application/json"],
+          ...securityHeaderLists(),
+        },
+        body: assetLinksBody(companionFingerprints),
+      },
+    ],
+    terminal: true,
+  });
+
+  // Home dashboard route, on the box that runs Home and nowhere else. The
+  // upstream `realm-home:3100` only resolves there, on the management bridge
+  // both containers join; elsewhere the dial misses and the request falls into
+  // the `errors` block below, which would serve a page saying the control plane
+  // is down - about a box that has no control plane to be down. Under BYO
+  // public providers it would also cost a real per-host certificate per worker.
+  //
+  // This is also the route every remote worker's uplink rides, which is why it
+  // is the one route carrying `stream_close_delay`.
+  if (dashboardHost !== null) {
+    routes.push({
+      match: [{ host: [dashboardHost] }],
+      handle: [homeProxy("realm-home:3100", clientIp)],
+      terminal: true,
+    });
+  }
+
+  for (const app of routedApps) {
+    for (const svc of app.services) {
+      const router = svc.router;
+      const upstream = `${app.appId}_${svc.serviceId}:${router.containerPort}`;
+      const host = structuredHost(app.appId, svc.serviceId, workerId, baseDomain);
+      routes.push(buildAuthRoute(host, router, upstream, app.trustedHeaderKeys ?? [], clientIp));
+      // An *additional*, ungated public route on the operator's own domain.
+      // Broker headers are stripped there so the bypass can't spoof identity.
+      if (router.publicDomain) {
+        const domains = Array.isArray(router.publicDomain)
+          ? router.publicDomain.map(String)
+          : [String(router.publicDomain)];
+        pushRoutes(routes, domains, router, upstream, app.trustedHeaderKeys ?? [], clientIp);
+      }
+    }
+  }
+
+  // Last route, so every specific host above wins: the worker's own wildcard,
+  // answering for a structured name that has no route yet (NOT_ROUTED_PAGE).
+  // Scoped to the names this worker mints — an unrelated Host still falls to
+  // Caddy's no-match default, which is an empty 200.
+  //
+  // 503 + Retry-After rather than 404, because the common way to land here is
+  // clicking a dashboard tile for an app whose reconcile is still running. A
+  // deleted or mistyped name gets the generous answer in exchange, which is
+  // cheap: these hostnames are generated and clicked, not typed.
+  //
+  // The wildcard also joins Caddy's managed-cert set by appearing in a matcher:
+  // a no-op when acme-dns already lists it in `certificates.automate` below,
+  // otherwise the catch-all policy issues it like any structured host.
+  if (workerId && baseDomain) {
+    routes.push({
+      match: [{ host: [`*.${workerId}.${baseDomain}`] }],
+      handle: [holdingResponse(NOT_ROUTED_PAGE)],
+      terminal: true,
+    });
+  }
+
+  // TLS policies are built up additively; at most two reach Caddy.
+  //
+  //   1. Realm DNS slug policy (specific subjects via acme-dns) - present
+  //      iff `acmeDns` is configured. Covers `*.{workerBaseDomain}` only
+  //      - the same shape on every worker, including the one that runs
+  //      Home (whose dashboard lives at `home-{nanoid}.{workerBaseDomain}`,
+  //      one label under that wildcard). No bare-slug wildcard, so the
+  //      dashboard URL is not derivable from the slug alone.
+  //   2. Catch-all for everything outside the slug wildcard, and there is
+  //      always exactly one. BYO public providers (cloudflare/hetzner) take it
+  //      if configured - Caddy races the issuers and wrong-zone failures bail
+  //      locally before LE is signaled. Otherwise the internal CA, so an
+  //      uncovered domain gets a self-signed cert (browser warning) rather
+  //      than a hard TLS failure or a doomed public-ACME attempt.
+  const policies: CaddyTlsPolicy[] = [];
+  // Names Caddy proactively obtains and serves certs for. The wildcard (via
+  // acme-dns) covers the dashboard host + every app subdomain; listing it in
+  // `certificates.automate` below is what stops Caddy from instead managing a
+  // per-host cert per route, whose DNS-01 challenge the shim never writes.
+  const automate: string[] = [];
+  if (acmeDns != null && workerId) {
+    const wildcard = `*.${workerId}.${acmeDns.baseDomain}`;
+    automate.push(wildcard);
+    policies.push({ subjects: [wildcard], issuers: [buildAcmeDnsIssuer(workerId, acmeDns)] });
+  }
+  if (publicProviders.length > 0) {
+    policies.push({ issuers: publicProviders.map(buildPublicIssuer) });
+  } else {
+    policies.push({ issuers: [{ module: "internal" }] });
+  }
+
+  // Self-register the worker's wildcard A. Same guard as the acme-dns TLS
+  // policy above (a slug base to own + a worker label): caddy-dynamicdns drives
+  // the `realm` provider, which POSTs `{subdomain: workerId}` to the shim's /a,
+  // and the shim points `*.{workerId}.{baseDomain}` at the request source IP.
+  // The `simple_http` ip_source is the shim's /ip echo, so the IP the tool
+  // detects == the IP /a records.
+  const dynamicDns: CaddyDynamicDns | undefined =
+    acmeDns != null && workerId
+      ? {
+          domains: { [acmeDns.baseDomain]: [workerId] },
+          dns_provider: {
+            name: "realm",
+            server_url: acmeDns.serverUrl,
+            username: acmeDns.username,
+            api_key: acmeDns.apiKey,
+          },
+          ip_sources: [{ source: "simple_http", endpoints: [`${acmeDns.serverUrl}/ip`] }],
+          check_interval: "5m",
+          versions: { ipv4: true, ipv6: false },
+        }
+      : undefined;
+
+  return {
+    admin: { listen: "127.0.0.1:2019" },
+    apps: {
+      http: {
+        servers: {
+          main: {
+            listen: [":443", ":80"],
+            routes,
+            // With a CDN declared in front, resolve `{client_ip}`
+            // right-to-left (strict) past its edge addresses from
+            // X-Forwarded-For. Omitted entirely otherwise: Caddy then ignores
+            // inbound XFF and uses the direct peer, so a client can't spoof
+            // its address when nothing is in front. The module fails soft - an
+            // unreachable provider yields no ranges, degrading to that same
+            // direct-peer behaviour rather than trusting anything.
+            ...(cdnProviders.length > 0 && {
+              trusted_proxies: { source: "cdn" as const, providers: [...cdnProviders] },
+              trusted_proxies_strict: 1 as const,
+              client_ip_headers: ["X-Forwarded-For"],
+            }),
+            ...(workerId &&
+              baseDomain && {
+                errors: {
+                  // Ordered pair, splitting on which dial failed. The marker is
+                  // set only once Home has answered and approved, so its absence
+                  // means Home itself was unreachable. Every app route under
+                  // this wildcard carries a forward_auth hop (checkPublicDomains
+                  // refuses a granted publicDomain under baseDomain at eval
+                  // time), while the dashboard route has none and proxies
+                  // straight to Home, so it falls to the second page.
+                  //
+                  // The first page is true on every box: the marker proves Home
+                  // answered, so the dial that failed was the app's. The second
+                  // names Home as the thing that is down, a claim only the box
+                  // running it can make - the same gate as the dashboard route.
+                  // A worker-only box leaves an unmarked 502 to Caddy's default.
+                  routes: [
+                    buildFallbackRoute(
+                      workerId,
+                      baseDomain,
+                      ` && {http.vars.${AUTH_OK_VAR}} == "1"`,
+                      DEPLOYING_PAGE,
+                    ),
+                    ...(dashboardHost !== null
+                      ? [buildFallbackRoute(workerId, baseDomain, "", HOME_UNREACHABLE_PAGE)]
+                      : []),
+                  ],
+                },
+              }),
+          },
+        },
+      },
+      tls: {
+        ...(automate.length > 0 && { certificates: { automate } }),
+        automation: { policies },
+      },
+      ...(dynamicDns && { dynamic_dns: dynamicDns }),
+    },
+  };
+}
+
+// acme-dns creds are inlined into the JSON, NOT passed as `{env.X}`
+// placeholders: the caddy-dns/acmedns module reads its libdns struct fields
+// verbatim and does not run Caddy's placeholder replacer, so an `{env.X}`
+// value reaches the HTTP client as a literal string. These creds are
+// Home-provisioned plain strings (not user secret refs), and the config file
+// lives inside the container, no more exposed than the env would have been.
+//
+// `subdomain` is the label the caller owns under acme-dns: this worker's
+// slug-relative label. The PEM in `acme.caRootPem` is materialized at
+// ACME_CA_ROOT_PATH.
+function buildAcmeDnsIssuer(subdomain: string, acme: AcmeIssuerInput): CaddyIssuer {
+  return {
+    module: "acme",
+    // Default ACME endpoint (Let's Encrypt prod) unless overridden to a
+    // staging endpoint or a test CA (Pebble) in the e2e.
+    ...(acme.ca && { ca: acme.ca }),
+    ...(acme.caRootPem && { trusted_roots_pem_files: [ACME_CA_ROOT_PATH] }),
+    challenges: {
+      dns: {
+        provider: {
+          name: "acmedns",
+          server_url: acme.serverUrl,
+          username: acme.username,
+          password: acme.apiKey,
+          // Static at config-gen time: the worker's own label under acme-dns.
+          subdomain,
+        },
+        // Wait for the Hetzner write to propagate before asking LE to
+        // validate. Too short and LE's multi-perspective validation races
+        // propagation: it queries an anycast PoP still serving the previous
+        // challenge value and fails with "Incorrect TXT record". Convergence
+        // measures ~30s from one vantage point and LE checks worldwide, so the
+        // delay sits above that with margin. Polling can't substitute — Caddy
+        // sees only its own resolver, never the stale PoP LE hits.
+        propagation_delay: "60s",
+      },
+    },
+  };
+}
+
+function buildPublicIssuer(provider: PublicProviderInput): CaddyIssuer {
+  const dnsProvider: CaddyProvider =
+    provider.name === "cloudflare"
+      ? { name: "cloudflare", api_token: provider.apiToken }
+      : { name: "hetzner", api_token: provider.apiToken };
+  return { module: "acme", challenges: { dns: { provider: dnsProvider } } };
+}
+
+// Every upstream proxy overwrites X-Forwarded-For + X-Real-IP with the single
+// resolved client IP (`clientIp`, computed once in buildCaddyConfig), so
+// upstreams always see one trustworthy address - never a spoofable chain.
+// `set` overwrites, so this also strips whatever XFF chain the CDN appended.
+function proxy(
+  upstream: string,
+  clientIp: string,
+  response?: CaddyHeaderRewrite,
+): Extract<CaddyHandler, { handler: "reverse_proxy" }> {
+  return {
+    handler: "reverse_proxy",
+    upstreams: [{ dial: upstream }],
+    headers: {
+      request: {
+        set: {
+          "X-Forwarded-For": [clientIp],
+          "X-Real-IP": [clientIp],
+        },
+      },
+      ...(response ? { response } : {}),
+    },
+  };
+}
+
+/**
+ * Proxy to an app container.
+ *
+ * Blanks any Home-session (`realm-home.*`) `Set-Cookie` the app emits, so an
+ * app can neither read the Home session (the inbound strip in
+ * `buildAuthRoute`) nor write one (here). See HOME_SET_COOKIE_REGEX for why a
+ * subdomain can otherwise overwrite the operator's session outright. Blanking
+ * rather than deleting the whole `Set-Cookie` field keeps the app's own
+ * cookies, exactly as the inbound strip keeps the app's own request cookies; a
+ * `Set-Cookie` with no `=` is discarded by the browser.
+ */
+function appProxy(upstream: string, clientIp: string): CaddyHandler {
+  return proxy(upstream, clientIp, {
+    replace: { "Set-Cookie": [{ search_regexp: HOME_SET_COOKIE_REGEX, replace: "" }] },
+  });
+}
+
+/**
+ * Proxy to Home itself (the dashboard host).
+ *
+ * Deliberately does NOT strip session cookies: this is the hop that mints them.
+ * Kept as its own function so the exemption is a named decision rather than a
+ * flag someone can pass wrongly at a fourth call site.
+ *
+ * The one route with `stream_close_delay`: remote workers' uplinks are upgraded
+ * streams on this host, and a deploy on Home's box reloads Caddy. App routes go
+ * without - they are ordinary HTTP, and a deploy is allowed to bounce them.
+ */
+function homeProxy(upstream: string, clientIp: string): CaddyHandler {
+  return { ...proxy(upstream, clientIp), stream_close_delay: STREAM_CLOSE_DELAY };
+}
+
+function pushRoutes(
+  routes: CaddyRoute[],
+  domains: string[],
+  router: IngressRouter,
+  upstream: string,
+  trustedHeaderKeys: string[],
+  clientIp: string,
+): void {
+  if (domains.length === 0) return;
+  if (domains.length === 1 || router.domainMode === "all") {
+    routes.push(buildPrimaryRoute(domains, router, upstream, trustedHeaderKeys, clientIp));
+    return;
+  }
+  // Redirect mode: primary serves; the rest 301 to it.
+  const [primary, ...rest] = domains;
+  if (!primary) return;
+  routes.push(buildPrimaryRoute([primary], router, upstream, trustedHeaderKeys, clientIp));
+  routes.push(buildRedirectRoute(rest, primary, router.pathPrefix));
+}
+
+function buildPrimaryRoute(
+  domains: string[],
+  router: IngressRouter,
+  upstream: string,
+  trustedHeaderKeys: string[],
+  clientIp: string,
+): CaddyRoute {
+  const handle: CaddyHandler[] = [];
+  // Reject early before doing any other work.
+  const rateLimitHandler = buildRateLimitHandler(router.rateLimit, clientIp);
+  if (rateLimitHandler) handle.push(rateLimitHandler);
+  // This route has no forward_auth, so no verified identity reaches it.
+  // Strip the platform namespace and every broker header the client may have
+  // set — otherwise the public route would be a trivial identity-spoof bypass.
+  handle.push({
+    handler: "headers",
+    request: { delete: [REALM_HEADER_WILDCARD, ...trustedHeaderKeys] },
+  });
+  handle.push(...buildContentHandlers(router));
+  handle.push(appProxy(upstream, clientIp));
+  return { match: [buildMatcher(domains, router.pathPrefix)], handle, terminal: true };
+}
+
+function buildAuthRoute(
+  host: string,
+  router: IngressRouter,
+  upstream: string,
+  trustedHeaderKeys: string[],
+  clientIp: string,
+): CaddyRoute {
+  const handle: CaddyHandler[] = [];
+  // Reject early before doing any other work — including the verify hop.
+  const rateLimitHandler = buildRateLimitHandler(router.rateLimit, clientIp);
+  if (rateLimitHandler) handle.push(rateLimitHandler);
+  // Strip the client's own copy of the platform namespace and every broker
+  // header BEFORE the verify hop, so a logged-in user can't smuggle in
+  // another user's identity — nor a header Home stamps on its other door.
+  // The verified values are re-added by forward_auth's copy_headers below
+  // (on 2xx), so this delete must run first.
+  handle.push({
+    handler: "headers",
+    request: { delete: [REALM_HEADER_WILDCARD, ...trustedHeaderKeys] },
+  });
+  // Gate on a logged-in Home session. On 2xx the chain continues to the app
+  // proxy; on a bounce Caddy relays Home's 302/401 to the client.
+  handle.push(...buildForwardAuthHandlers(VERIFY_UPSTREAM, VERIFY_PATH, trustedHeaderKeys));
+  handle.push(...buildContentHandlers(router));
+  // Strip the Home session cookie on the app hop ONLY — the verify sub-request
+  // above needed it; a downstream app seeing it is a Home-session-takeover
+  // vector. Snip just the better-auth cookies via regex so the app keeps its
+  // OWN cookies; deleting the whole `Cookie` header would break any app that
+  // sets cookies on its subdomain. Ordering: after forward_auth, before the
+  // app proxy.
+  handle.push({
+    handler: "headers",
+    request: { replace: { Cookie: [{ search_regexp: HOME_COOKIE_REGEX, replace: "" }] } },
+  });
+  handle.push(appProxy(upstream, clientIp));
+  return { match: [buildMatcher([host], router.pathPrefix)], handle, terminal: true };
+}
+
+// encode + response security headers + request-body limit — the middle of
+// the handler chain, shared by the public and authenticated route variants.
+function buildContentHandlers(router: IngressRouter): CaddyHandler[] {
+  const handle: CaddyHandler[] = [];
+  if (router.compress) {
+    handle.push({ handler: "encode", encodings: { gzip: {} }, prefer: ["gzip"] });
+  }
+  const headerHandler = buildHeaderHandler(router.headers);
+  if (headerHandler) handle.push(headerHandler);
+  if (router.maxRequestSizeMb != null) {
+    handle.push({
+      handler: "request_body",
+      max_size: router.maxRequestSizeMb * 1024 * 1024,
+    });
+  }
+  return handle;
+}
+
+// The forward_auth seam — the single swappable unit, so a different access
+// model only changes what Home returns. One reverse_proxy handler that
+// sub-requests the Home verify endpoint (forwarding the Cookie that the default
+// reverse_proxy already adds, plus the original host, method and uri). On any
+// non-2xx Caddy relays Home's response (302 → login, or 401) to the client
+// verbatim. On 2xx the handle_response routes run before the chain falls
+// through to the app proxy: the first sets the auth-ok marker, and when the
+// app brokers headers (`getTrustedHeaders`) one guarded route per header lifts
+// the verified value from the verify response
+// (`{http.reverse_proxy.header.<name>}`, the copy_headers placeholder) onto the
+// upstream request.
+//
+// The guard is the point. Caddy's `headers` handler leaves an unresolved
+// placeholder as its literal text, and an anonymous admit is a 2xx with no
+// identity headers - so an unguarded set would hand the container the string
+// `{http.reverse_proxy.header.X-Forwarded-User}` as the user. The `vars`
+// matcher resolves an absent placeholder to "", so `not vars {p} == ""` runs
+// the set only when Home actually sent the header. The client's own copy was
+// deleted before the hop, so on an anonymous admit the app sees no header at
+// all, which is what access-gate.ts promises.
+function buildForwardAuthHandlers(
+  verifyUpstream: string,
+  verifyPath: string,
+  trustedHeaderKeys: string[],
+): CaddyHandler[] {
+  // Unconditional, and first: it must be set whether or not the app brokers
+  // headers, because the error routes below read it to decide which of the two
+  // dials on this route failed.
+  const onAuthed: Array<{
+    match?: Array<{ not: Array<{ vars: Record<string, string[]> }> }>;
+    handle: CaddyHandler[];
+  }> = [{ handle: [{ handler: "vars", [AUTH_OK_VAR]: "1" }] }];
+  for (const k of trustedHeaderKeys) {
+    const placeholder = `{http.reverse_proxy.header.${k}}`;
+    onAuthed.push({
+      match: [{ not: [{ vars: { [placeholder]: [""] } }] }],
+      handle: [{ handler: "headers", request: { set: { [k]: [placeholder] } } }],
+    });
+  }
+  return [
+    {
+      handler: "reverse_proxy",
+      rewrite: { method: "GET", uri: verifyPath },
+      headers: {
+        request: {
+          // Host is pinned, not forwarded. Home picks the anonymous gate and
+          // the brokered-header mapping from this header alone, and Caddy
+          // keeps a client-supplied value once server-level `trusted_proxies`
+          // is configured (a declared `cdn`) — which would let a caller borrow
+          // another app's gate. `set` is overwrite, so the route's host wins.
+          set: {
+            "X-Forwarded-Host": ["{http.request.host}"],
+            "X-Forwarded-Method": ["{http.request.method}"],
+            "X-Forwarded-Uri": ["{http.request.uri}"],
+          },
+        },
+      },
+      // `[2]` is Caddy's shorthand for the whole 2xx class.
+      handle_response: [{ match: { status_code: [2] }, routes: onAuthed }],
+      upstreams: [{ dial: verifyUpstream }],
+    },
+  ];
+}
+
+// caddy-ratelimit is sliding-window: no more than `max_events` in any
+// `window`. The SDK speaks the same model — a bare number is requests/second.
+function buildRateLimitHandler(
+  rateLimit: number | { requests: number; window: string } | null | undefined,
+  clientIp: string,
+): CaddyHandler | undefined {
+  if (rateLimit == null) return undefined;
+  const { max_events, window } =
+    typeof rateLimit === "number"
+      ? { max_events: rateLimit, window: "1s" }
+      : { max_events: rateLimit.requests, window: rateLimit.window };
+  return {
+    handler: "rate_limit",
+    rate_limits: {
+      // `clientIp` must be a placeholder Caddy actually expands — an
+      // unresolved literal would collapse every client into one bucket.
+      per_ip: { key: clientIp, window, max_events },
+    },
+  };
+}
+
+// The one response every fallback page ships as. Carries the default security
+// headers because these routes bypass `buildContentHandlers`, and for a newly
+// minted app subdomain this is often the first response a browser ever sees for
+// that hostname — which is exactly the response that should set HSTS.
+function holdingResponse(body: string): CaddyHandler {
+  return {
+    handler: "static_response",
+    status_code: 503,
+    headers: {
+      "Content-Type": ["text/html; charset=utf-8"],
+      "Retry-After": ["5"],
+      ...securityHeaderLists(),
+    },
+    body,
+  };
+}
+
+// One error-handler route: a page served for a failed dial on this worker's own
+// wildcard. `extraExpr` is appended to the status narrowing to split the two
+// causes; "" makes the route the catch-all of the pair, so it must come last.
+function buildFallbackRoute(
+  workerId: string,
+  baseDomain: string,
+  extraExpr: string,
+  body: string,
+): CaddyErrorRoute {
+  return {
+    match: [
+      {
+        host: [`*.${workerId}.${baseDomain}`],
+        expression: `{http.error.status_code} in [502, 504]${extraExpr}`,
+      },
+    ],
+    handle: [holdingResponse(body)],
+    terminal: true,
+  };
+}
+
+function buildRedirectRoute(
+  domains: string[],
+  primary: string,
+  pathPrefix: string | undefined,
+): CaddyRoute {
+  return {
+    match: [buildMatcher(domains, pathPrefix)],
+    handle: [
+      {
+        handler: "static_response",
+        headers: { Location: [`https://${primary}{http.request.orig_uri}`] },
+        status_code: 301,
+      },
+    ],
+    terminal: true,
+  };
+}
+
+function buildMatcher(
+  domains: string[],
+  pathPrefix: string | undefined,
+): { host: string[]; path?: string[] } {
+  return { host: domains, ...(pathPrefix ? { path: [`${pathPrefix}*`] } : {}) };
+}
+
+// Sorted, and that is load-bearing rather than tidy. This function's output is
+// order-sensitive in two places - the `delete` array, and where a non-default
+// key lands in `set` - while `router.headers` is a `z.record` whose key order
+// the wire does not preserve: `canonicalJsonStringify` sorts every key at every
+// depth, so the record an author wrote reaches the renderer in lexicographic
+// order regardless. Iterating insertion order would therefore make the rendered
+// document depend on which side of the wire the input came from - identical to
+// Caddy, but not to anything comparing bytes or diffing config revisions.
+function buildHeaderHandler(
+  overrides: Record<string, string | null> | undefined,
+): CaddyHandler | undefined {
+  const set: Record<string, string> = { ...DEFAULT_SECURITY_HEADERS };
+  const del: string[] = [];
+  if (overrides) {
+    for (const [k, v] of Object.entries(overrides).sort(([a], [b]) => (a < b ? -1 : 1))) {
+      if (v === null) {
+        delete set[k];
+        del.push(k);
+      } else {
+        set[k] = v;
+      }
+    }
+  }
+  if (Object.keys(set).length === 0 && del.length === 0) return undefined;
+  const setArr: Record<string, string[]> = {};
+  for (const [k, v] of Object.entries(set)) setArr[k] = [v];
+  const response: { set?: Record<string, string[]>; delete?: string[] } = {};
+  if (Object.keys(setArr).length > 0) response.set = setArr;
+  if (del.length > 0) response.delete = del;
+  return { handler: "headers", response };
+}