feat: support split Dashboard and API origins (ADR 0045)

An installation can now serve the Dashboard and the API on sibling
hostnames (dash./api.) beside the default same-origin topology, from one
image and with configuration alone.

- The Dashboard learns its API origin at run time: the built page carries
  one empty <meta name="ekklesia-api-origin">, which the API fills with its
  identity base URL's origin at startup, before computing the page's ETag.
  The shell accepts only a canonical http(s) origin and otherwise fails
  closed without making a request. The build-time EKKLESIA_API_BASE_URL is
  gone from the bundle; the development server injects the same element.
- The display host stays on the API's origin, so its device cookies,
  requests, and offline cache are unchanged.
- The API trusts its own origin (trusted origins plus the identity base
  URL), as Better Auth already does, so the display page's mutations pass
  the origin check without operators listing it.
- Doctor validates EKKLESIA_DASHBOARD_ORIGIN exactly as the API's startup
  does (it previously skipped it), reports the topology without printing
  hostnames, and warns when split hostnames are not siblings.
- The module UI contract states the CORS header limit (safelisted headers
  plus Content-Type, safelisted response headers only).
- Reference deployment: Caddyfile.split.example (Dashboard hostname serves
  / and its script; API hostname serves /api/*, /display/*, and the
  display script; each refuses the other's paths) and
  EKKLESIA_DASHBOARD_HOSTNAME in the proxy overlay and env examples.
- The deploy smoke test runs either topology (CI runs both). The split run
  installs the module template as a test-only module, checks per-hostname
  routing and exact CORS, then drives a digest-pinned headless Chromium
  over the DevTools protocol, with no added dependency: sign-in on the
  Dashboard hostname, the session cookie host-only on the API hostname,
  the module UI imported cross-origin and its credentialed request
  succeeding, the display and its service worker on the API hostname, and
  sign-out.

ADR 0045 is marked Accepted.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

deploy/Caddyfile.split.example

@@ -0,0 +1,109 @@
+# Ekklesia reference proxy configuration for the split topology (ADR 0045): the Dashboard and the API
+# on separate hostnames of one site, for example dash.example.org and api.example.org. For the
+# default same-origin topology use Caddyfile.example instead. Copy this file to deploy/Caddyfile.
+#
+# Hostnames, the ACME contact, and the tunnel connector's address come from the proxy service's
+# environment (deploy/.env): EKKLESIA_DASHBOARD_HOSTNAME is the Dashboard's, EKKLESIA_HOSTNAME the
+# API's (which also serves the display host), EKKLESIA_STORAGE_HOSTNAME the storage origin's. Only
+# the two site blocks below differ from Caddyfile.example.
+{
+	# ACME account contact. Certificates use the HTTP-01 challenge on port 80 by default, which needs
+	# all three hostnames to resolve publicly to this host with 80 and 443 reachable.
+	email {$EKKLESIA_ACME_EMAIL}
+
+	# DNS-01, for an installation that keeps Ekklesia off the public Internet, serves only a LAN
+	# (split-horizon DNS), or is reachable only through Cloudflare Tunnel. Cloudflare terminates TLS at
+	# its edge, so HTTP-01 cannot reach this proxy through a tunnel.
+	#
+	# DNS-01 needs a DNS provider module that the stock Caddy image does not contain. Build an image
+	# with it (for example `xcaddy build --with github.com/caddy-dns/cloudflare`), pin that image by
+	# digest in your own overlay, give it CLOUDFLARE_API_TOKEN through a root-owned env file, then
+	# enable:
+	#
+	# acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
+
+	servers {
+		# A client-address header is honored only from the tunnel connector's fixed address
+		# (compose.tunnel.yaml). From every other peer, the client address is the TCP peer itself and
+		# any such header is ignored. Without a tunnel, nothing has this address.
+		trusted_proxies static {$EKKLESIA_TUNNEL_ADDRESS}/32
+		client_ip_headers CF-Connecting-IP
+		trusted_proxies_strict
+	}
+
+	# Access logs are off unless enabled. If you enable them, keep request headers out: they carry
+	# cookies and forwarding chains (docs/development/security.md, launch checklist item 7).
+}
+
+# What every request to the API carries upstream: exactly one forwarding header, overwritten with
+# the client address Caddy resolved, and none of the headers a caller could use to choose its own.
+(ekklesia_forwarding) {
+	header_up X-Forwarded-For {client_ip}
+	header_up -CF-Connecting-IP
+	header_up -X-Real-IP
+	header_up -Forwarded
+	header_up -True-Client-IP
+}
+
+# The Dashboard: its page and its one script, nothing else. Emailed verification and reset links land
+# on `/` with a query. `/api/*` is refused here on purpose, so the session cookie has exactly one
+# home, the API hostname, and the Dashboard can never fall back to a same-origin API.
+{$EKKLESIA_DASHBOARD_HOSTNAME} {
+	@dashboard path / /assets/ekklesia-dashboard/*
+
+	handle @dashboard {
+		reverse_proxy api:3000 {
+			import ekklesia_forwarding
+		}
+	}
+
+	handle {
+		respond 404
+	}
+}
+
+# The API, and the display host on the API's own origin: a screen's pages, service worker, device
+# cookies, and requests are all same-origin (ADR 0045). Nothing is served at `/`.
+{$EKKLESIA_HOSTNAME} {
+	@api path /api/* /display/* /assets/ekklesia-display/*
+
+	# Module realtime is Server-Sent Events: flush every event immediately.
+	@realtime path /api/v1/module-realtime/*
+
+	handle @realtime {
+		reverse_proxy api:3000 {
+			import ekklesia_forwarding
+			flush_interval -1
+		}
+	}
+
+	handle @api {
+		# Request bodies stream through unbuffered and unlimited here; the API enforces the platform's
+		# ceilings itself (8 KiB for authentication, up to 32 MiB for a streamed module route).
+		reverse_proxy api:3000 {
+			import ekklesia_forwarding
+		}
+	}
+
+	handle {
+		respond 404
+	}
+}
+
+# Browsers fetch signed object URLs here (S3_DELIVERY_ENDPOINT, ADR 0031).
+{$EKKLESIA_STORAGE_HOSTNAME} {
+	reverse_proxy https://object-storage:8443 {
+		# An S3 signature covers the Host header: pass the original through unchanged, or every signed
+		# URL fails verification.
+		header_up Host {host}
+		header_up -CF-Connecting-IP
+		header_up -X-Real-IP
+		header_up -Forwarded
+		header_up -True-Client-IP
+		transport http {
+			# object-storage presents a certificate from the installation-private CA.
+			tls_trust_pool file /etc/caddy/ekklesia-ca.crt
+			tls_server_name object-storage
+		}
+	}
+}

deploy/README.md

@@ -10,7 +10,8 @@ specific to one organization.
 | [`compose.yaml`](compose.yaml) | The base: `api`, `postgres`, `object-storage`, and the operator-only `migrate`. Publishes no port. |
 | [`compose.proxy.yaml`](compose.proxy.yaml) | Overlay: Caddy as the TLS proxy, the only service with published ports. |
 | [`compose.tunnel.yaml`](compose.tunnel.yaml) | Overlay on top of the proxy: a Cloudflare Tunnel connector. |
-| [`Caddyfile.example`](Caddyfile.example) | The proxy's configuration; copy to `Caddyfile`. |
+| [`Caddyfile.example`](Caddyfile.example) | The proxy's configuration for the default same-origin topology; copy to `Caddyfile`. |
+| [`Caddyfile.split.example`](Caddyfile.split.example) | The proxy's configuration when the Dashboard and the API have separate hostnames ([Split Dashboard and API origins](#split-dashboard-and-api-origins)); copy to `Caddyfile` instead. |
 | [`postgres/pg_hba.conf`](postgres/pg_hba.conf) | PostgreSQL client authentication: TLS only, SCRAM passwords. |
 | [`env/`](env/) | Commented examples of every env file. No values. |
 | [`scripts/init-tls.sh`](scripts/init-tls.sh) | Creates the installation-private CA and the `postgres` and `object-storage` server certificates. |
@@ -142,6 +143,41 @@ image, because it was not built for the newer schema.
 Slice 6 adds the scheduled backup job and the restore procedure (ADR 0044, Backups). Until then,
 take a `pg_dump` and a copy of every bucket before each upgrade by hand.
 
+### Split Dashboard and API origins
+
+By default one hostname serves the Dashboard (`/`), the API (`/api/*`), and displays (`/display/*`).
+An installation may instead give the Dashboard its own hostname, for example `dash.example.org`
+beside `api.example.org` ([ADR 0045](../docs/architecture/decisions/0045-split-dashboard-and-api-origins.md)).
+The same image serves both; only configuration differs.
+
+| Hostname | Serves | Refuses (`404`) |
+| --- | --- | --- |
+| Dashboard (`EKKLESIA_DASHBOARD_HOSTNAME`) | `/` and `/assets/ekklesia-dashboard/*` | everything else, including `/api/*` |
+| API (`EKKLESIA_HOSTNAME`) | `/api/*`, `/display/*`, `/assets/ekklesia-display/*` | everything else, including `/` |
+| Storage (`EKKLESIA_STORAGE_HOSTNAME`) | signed object URLs, unchanged | |
+
+Displays live on the API's hostname (`https://api.example.org/display/<module>`), because their
+device cookies are bound to it and their offline cache keeps only same-origin responses. That
+hostname is what every screen and paired device depends on: choose it once.
+
+To run split:
+
+1. Copy `Caddyfile.split.example` to `Caddyfile` instead of `Caddyfile.example`.
+2. In `deploy/.env`, set `EKKLESIA_HOSTNAME` to the API's hostname and `EKKLESIA_DASHBOARD_HOSTNAME`
+   to the Dashboard's.
+3. In `ekklesia.env`, set `EKKLESIA_IDENTITY_BASE_URL` to `https://` and the API's hostname,
+   `EKKLESIA_DASHBOARD_ORIGIN` to `https://` and the Dashboard's, and
+   `EKKLESIA_IDENTITY_TRUSTED_ORIGINS` to the Dashboard's origin. The API always trusts its own
+   origin, so it need not be listed.
+
+**Both hostnames must belong to one registrable domain** (`dash.example.org` and `api.example.org`,
+not `dash.example.org` and `api.example.net`). The session cookie stays host-only on the API's
+hostname; browsers send it from the Dashboard only between origins of the same site. Doctor reports
+the topology and warns when the two hostnames are not siblings.
+
+The Dashboard learns the API's origin at run time: the API writes its identity base URL into the page
+it serves (`<meta name="ekklesia-api-origin">`). Nothing about the topology is built into the image.
+
 ### Behind an existing reverse proxy
 
 Run the base alone and attach `api` and `object-storage` to your proxy's network with an overlay of
@@ -203,8 +239,9 @@ dashboard. No Cloudflare API is called from here.
    the Ekklesia hostname. Service type **HTTPS**, URL `proxy:443`.
 3. Under that hostname's **TLS** settings, set **Origin Server Name** to the same Ekklesia hostname,
    and leave **No TLS Verify** off. The connector then verifies the proxy's certificate for that name.
-4. Add a second public hostname for the storage hostname, the same way, with its own origin server
-   name.
+4. Add a public hostname for the storage hostname, the same way, with its own origin server name.
+   In the [split topology](#split-dashboard-and-api-origins), add one for the Dashboard's hostname
+   too: three in all, each with its own origin server name.
 5. Start with all three files. The proxy honors `CF-Connecting-IP` only from the connector's fixed
    address. From any other peer it is stripped.
 
@@ -232,7 +269,7 @@ deployment:
 
 | # | Item | Where it is met |
 | --- | --- | --- |
-| 1 | The proxy forwards the Dashboard and `/api` on the intended origin | `Caddyfile.example` routes `/`, `/api/*`, `/display/*`, `/assets/*` on one hostname to `api`; the API serves the Dashboard itself. |
+| 1 | The proxy forwards the Dashboard and `/api` on the intended origin | `Caddyfile.example` routes `/`, `/api/*`, `/display/*`, `/assets/*` on one hostname to `api`; the API serves the Dashboard itself. In the split topology, `Caddyfile.split.example` gives each hostname exactly its own paths and the exact trusted-origin CORS of ADR 0045 covers the rest. |
 | 2 | The origin port is unreachable from the Internet | The base publishes no port; only `proxy` publishes 80 and 443. |
 | 3 | The origin port is unreachable from untrusted networks | `api` is reachable only on Docker networks; `EKKLESIA_PUBLISH_ADDRESS` limits the proxy to one interface. Firewall the host itself. |
 | 4 | The proxy overwrites the trusted client-IP header | `header_up X-Forwarded-For {client_ip}` in `Caddyfile.example`. |
@@ -258,7 +295,15 @@ deployment:
     wrong host name;
   - Doctor.
 
-  CI runs it on every change.
+  `EKKLESIA_SMOKE_TOPOLOGY=split` runs the [split topology](#split-dashboard-and-api-origins)
+  instead: an image with the repository's module template installed as a test-only module, every
+  hostname's served and refused paths, exact CORS for the Dashboard's origin and none for others,
+  and then a real headless Chromium (pinned by digest, driven over the DevTools protocol) that signs
+  in on the Dashboard's hostname, checks the session cookie lives only on the API's, mounts the
+  module's UI from the API's origin and sees its own credentialed requests succeed, mounts its display
+  on the API's hostname with its service worker, and signs out.
+
+  CI runs both topologies on every change.
 - **Test-only:** the smoke test runs Caddy with its internal CA (`local_certs`), because a test run
   has no public hostname. Never use it in an installation; `Caddyfile.example` does not contain it.
 

deploy/compose.proxy.yaml

@@ -35,6 +35,10 @@ services:
     environment:
       EKKLESIA_HOSTNAME: ${EKKLESIA_HOSTNAME:?EKKLESIA_HOSTNAME is required, for example ekklesia.example.org}
       EKKLESIA_STORAGE_HOSTNAME: ${EKKLESIA_STORAGE_HOSTNAME:?EKKLESIA_STORAGE_HOSTNAME is required, for example storage.ekklesia.example.org}
+      # The split topology only (ADR 0045, Caddyfile.split.example), where EKKLESIA_HOSTNAME is the
+      # API's hostname and this is the Dashboard's. Caddyfile.example ignores it; the split
+      # configuration refuses to start without it.
+      EKKLESIA_DASHBOARD_HOSTNAME: ${EKKLESIA_DASHBOARD_HOSTNAME:-}
       EKKLESIA_ACME_EMAIL: ${EKKLESIA_ACME_EMAIL:?EKKLESIA_ACME_EMAIL is required for ACME account notices}
       EKKLESIA_TUNNEL_ADDRESS: ${EKKLESIA_TUNNEL_ADDRESS:-10.249.250.253}
     volumes:

deploy/env/compose.env.example

@@ -10,9 +10,14 @@ EKKLESIA_ENV_DIR=/etc/ekklesia
 EKKLESIA_TLS_DIR=/etc/ekklesia/tls
 
 # --- compose.proxy.yaml ---------------------------------------------------------------------------
-# The Ekklesia hostname (Dashboard, API, displays) and the storage hostname (signed object URLs).
+# The Ekklesia hostname and the storage hostname (signed object URLs). In the default same-origin
+# topology (Caddyfile.example) EKKLESIA_HOSTNAME serves the Dashboard, the API, and displays.
 EKKLESIA_HOSTNAME=
 EKKLESIA_STORAGE_HOSTNAME=
+# The split topology only (ADR 0045, Caddyfile.split.example): the Dashboard's own hostname, while
+# EKKLESIA_HOSTNAME is the API's and the displays'. Both must share one registrable domain, for
+# example dash.example.org and api.example.org. Leave empty for the same-origin topology.
+EKKLESIA_DASHBOARD_HOSTNAME=
 # Contact address for the ACME account (certificate expiry notices).
 EKKLESIA_ACME_EMAIL=
 # EKKLESIA_CADDYFILE=./Caddyfile

deploy/env/ekklesia.env.example

@@ -23,15 +23,19 @@ EKKLESIA_DATABASE_TLS_MODE=verify-full
 # scripts/init-tls.sh prints this exact line. It is the only CA the database connection trusts.
 EKKLESIA_DATABASE_CA=
 
-# --- Identity (ADR 0011, ADR 0018, ADR 0034) ----------------------------------------------------
-# The public https origin of the Ekklesia hostname, with no path. Production rejects http and
-# loopback origins.
+# --- Identity (ADR 0011, ADR 0018, ADR 0034, ADR 0045) -----------------------------------------
+# The public https origin of the API, with no path: the Ekklesia hostname in the same-origin
+# topology, the API's hostname in the split one. Production rejects http and loopback origins.
 EKKLESIA_IDENTITY_BASE_URL=
-# Comma-separated exact origins allowed to make credentialed requests. Normally just the base URL.
+# Comma-separated exact origins allowed to make credentialed requests. The API's own origin is
+# always trusted and need not be listed. Same-origin topology: the base URL. Split topology: the
+# Dashboard's origin.
 EKKLESIA_IDENTITY_TRUSTED_ORIGINS=
 # At least 32 random characters. Rotating it signs every user out.
 EKKLESIA_IDENTITY_SECRET=
-# Leave unset: the Dashboard is served from the base URL (ADR 0044).
+# Same-origin topology: leave unset; the Dashboard is served from the base URL (ADR 0044).
+# Split topology: the Dashboard's https origin, which must also be in the trusted origins. Emailed
+# verification and reset links land here (ADR 0045).
 # EKKLESIA_DASHBOARD_ORIGIN=
 # Production refuses public sign-up. Leave unset.
 # EKKLESIA_PUBLIC_SIGNUP_ENABLED=