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]>

scripts/lib/deploy-smoke-browser.mjs

@@ -0,0 +1,287 @@
+// Real-browser assertions for scripts/smoke-deploy.sh in the split topology (ADR 0045). Runs inside a
+// disposable container on the deployment's `edge` network and drives a headless Chromium, itself a
+// disposable container on the same network, over the Chrome DevTools Protocol, with Node.js's own
+// fetch and WebSocket and no other dependency.
+//
+//   node deploy-smoke-browser.mjs
+//
+// What only a browser can prove: that a person signing in on the Dashboard's hostname gets a session
+// cookie on the API's hostname alone, that the Dashboard then imports a module's UI from the API's
+// origin and the module's credentialed requests succeed under CORS, that the module's display page
+// mounts on the API's origin with that same session, and that sign-out ends it. Output is one line
+// per check; nothing printed carries a credential, cookie value, or response body.
+
+function required(name) {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`${name} is required.`);
+  }
+  return value;
+}
+
+const apiOrigin = `https://${required("SMOKE_HOSTNAME")}`;
+const dashboardOrigin = `https://${required("SMOKE_DASHBOARD_HOSTNAME")}`;
+const apiHostname = new URL(apiOrigin).hostname;
+const devtools = required("SMOKE_CDP_ADDRESS");
+const timeoutMs = 30_000;
+
+let failures = 0;
+function check(condition, description) {
+  console.log(`${condition ? "ok  " : "FAIL"} ${description}`);
+  if (!condition) {
+    failures += 1;
+  }
+}
+
+/** The smallest Chrome DevTools Protocol client: numbered commands, flat sessions, and events. */
+async function connect() {
+  // The browser container was started moments ago; give it time to listen.
+  // One overall deadline, with every attempt bounded, so a browser that never comes up fails the
+  // run in seconds rather than waiting out TCP timeouts.
+  const deadline = Date.now() + 30_000;
+  let version;
+  while (version === undefined) {
+    try {
+      const response = await fetch(`http://${devtools}/json/version`, {
+        signal: AbortSignal.timeout(2_000),
+      });
+      version = await response.json();
+    } catch {
+      if (Date.now() > deadline) {
+        throw new Error("The headless browser never answered.");
+      }
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+  }
+  // Chromium names its WebSocket after the Host it was asked on; ask on the same address.
+  const socketUrl = version.webSocketDebuggerUrl.replace(/^ws:\/\/[^/]+/u, `ws://${devtools}`);
+  const socket = new WebSocket(socketUrl);
+  await new Promise((resolve, reject) => {
+    socket.addEventListener("open", resolve, { once: true });
+    socket.addEventListener("error", () => reject(new Error("DevTools connection failed.")), {
+      once: true,
+    });
+  });
+  let nextId = 1;
+  const pending = new Map();
+  const listeners = [];
+  socket.addEventListener("message", (event) => {
+    const message = JSON.parse(String(event.data));
+    if (message.id !== undefined) {
+      const waiter = pending.get(message.id);
+      pending.delete(message.id);
+      if (message.error) {
+        waiter?.reject(new Error(`DevTools ${waiter.method} failed.`));
+      } else {
+        waiter?.resolve(message.result);
+      }
+      return;
+    }
+    for (const listener of listeners) {
+      listener(message);
+    }
+  });
+  return {
+    close: () => socket.close(),
+    on: (listener) => listeners.push(listener),
+    send(method, params = {}, sessionId = undefined) {
+      const id = nextId;
+      nextId += 1;
+      socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+      return new Promise((resolve, reject) => pending.set(id, { method, reject, resolve }));
+    },
+  };
+}
+
+const cdp = await connect();
+const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
+const { sessionId } = await cdp.send("Target.attachToTarget", { flatten: true, targetId });
+const send = (method, params) => cdp.send(method, params, sessionId);
+
+/** Every response and failure the page sees, for the API's origin. A CORS refusal is a
+ * `loadingFailed` here, never a response. */
+const responses = [];
+const failed = [];
+cdp.on((message) => {
+  if (message.sessionId !== sessionId) {
+    return;
+  }
+  if (message.method === "Network.responseReceived") {
+    const { response, type } = message.params;
+    responses.push({ status: response.status, type, url: response.url });
+  } else if (message.method === "Network.loadingFailed") {
+    failed.push(message.params);
+  }
+});
+await send("Network.enable");
+await send("Page.enable");
+await send("Runtime.enable");
+// A desktop-sized window: a module may reasonably decline to render its management UI on a small one.
+await send("Emulation.setDeviceMetricsOverride", {
+  deviceScaleFactor: 1,
+  height: 1080,
+  mobile: false,
+  width: 1920,
+});
+
+async function evaluate(expression) {
+  const result = await send("Runtime.evaluate", {
+    awaitPromise: true,
+    expression,
+    returnByValue: true,
+  });
+  if (result.exceptionDetails) {
+    throw new Error("A page expression threw.");
+  }
+  return result.result.value;
+}
+
+async function waitFor(expression, description) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await evaluate(`Boolean(${expression})`).catch(() => false)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  console.log(`FAIL timed out waiting for ${description}`);
+  failures += 1;
+  return false;
+}
+
+async function navigate(url) {
+  await send("Page.navigate", { url });
+}
+
+const selector = (testId) => `document.querySelector('[data-testid="${testId}"]')`;
+
+async function cookiesFor(origin) {
+  const { cookies } = await send("Network.getCookies", { urls: [`${origin}/`] });
+  return cookies;
+}
+
+// --- Sign in on the Dashboard's hostname -------------------------------------------------------
+await navigate(`${dashboardOrigin}/`);
+await waitFor(selector("login-email"), "the sign-in form on the Dashboard hostname");
+await evaluate(`(() => {
+  // React tracks input values through the native setter; assigning .value alone is invisible to it.
+  const setValue = (element, value) => {
+    Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value").set.call(element, value);
+    element.dispatchEvent(new Event("input", { bubbles: true }));
+  };
+  setValue(${selector("login-email")}, ${JSON.stringify(required("SMOKE_OWNER_EMAIL"))});
+  setValue(${selector("login-password")}, ${JSON.stringify(required("SMOKE_OWNER_PASSWORD"))});
+  ${selector("login-email")}.form.requestSubmit();
+})()`);
+check(
+  await waitFor(selector("host-shell"), "the signed-in Dashboard"),
+  "a person signs in through the real form on the Dashboard hostname",
+);
+
+const apiCookies = await cookiesFor(apiOrigin);
+const dashboardCookies = await cookiesFor(dashboardOrigin);
+check(
+  apiCookies.some((cookie) => cookie.httpOnly && cookie.secure && cookie.domain === apiHostname) &&
+    dashboardCookies.length === 0,
+  "the session cookie is host-only on the API hostname, and the Dashboard hostname holds none",
+);
+
+// --- A module UI, imported from the API's origin -------------------------------------------------
+const moduleButton = "document.querySelector('[data-testid^=\"select-\"]')";
+const hasModule = await waitFor(moduleButton, "a module in the Dashboard navigation");
+if (hasModule) {
+  const moduleId = await evaluate(`${moduleButton}.dataset.testid.slice("select-".length)`);
+  await evaluate(`${moduleButton}.click()`);
+  const mounted = await waitFor(
+    `${selector("module-container")}?.childElementCount > 0 && !${selector("module-loading")} && !${selector("module-error")}`,
+    "the module UI to mount",
+  );
+  check(
+    mounted && !(await evaluate(`Boolean(${selector("module-error")})`)),
+    `the ${moduleId} module UI mounts`,
+  );
+  // Give the module's first requests a moment to settle before judging them.
+  await new Promise((resolve) => setTimeout(resolve, 1_000));
+  check(
+    responses.some(
+      (response) =>
+        response.url.startsWith(`${apiOrigin}/api/v1/module-ui/${moduleId}/`) &&
+        response.status === 200,
+    ),
+    "its UI artifact was imported from the API's origin",
+  );
+  check(
+    responses.some(
+      (response) =>
+        response.url.startsWith(`${apiOrigin}/api/v1/modules/${moduleId}`) &&
+        response.status >= 200 &&
+        response.status < 300,
+    ),
+    "its own credentialed API request to the API's origin succeeded under CORS",
+  );
+  const streams = responses.filter((response) => response.type === "EventSource");
+  check(
+    streams.every((response) => response.status === 200),
+    `every realtime stream it opened was accepted (${streams.length} opened)`,
+  );
+}
+// A CORS refusal or a blocked request is always a failure. A request the page itself cancelled (a
+// module unmounting, a navigation) is not.
+const refused = failed.filter(
+  (failure) =>
+    failure.corsErrorStatus !== undefined ||
+    failure.blockedReason !== undefined ||
+    !(failure.canceled || failure.errorText === "net::ERR_ABORTED"),
+);
+check(
+  refused.length === 0,
+  `no request from the Dashboard failed or was refused by CORS (${refused.length} refused)`,
+);
+
+// --- The display host, on the API's origin, with the same session --------------------------------
+const displayPath =
+  await evaluate(`fetch(${JSON.stringify(`${apiOrigin}/api/v1/dashboard/navigation`)}, {
+  credentials: "include",
+}).then((response) => response.json()).then((navigation) => {
+  const entries = [...navigation.ungrouped, ...navigation.groups.flatMap((group) => group.modules)];
+  return entries.find((entry) => entry.module.display !== null)?.module.display.url ?? null;
+})`);
+if (displayPath === null) {
+  console.log("skip no installed module publishes a display");
+} else {
+  await navigate(`${apiOrigin}${displayPath}`);
+  check(
+    await waitFor(
+      `${selector("display-module-container")}?.childElementCount > 0 && !${selector("display-error")}`,
+      "the display to mount",
+    ),
+    "the module's display page mounts on the API hostname with the same session",
+  );
+  check(
+    await waitFor(
+      "navigator.serviceWorker.getRegistrations().then((registrations) => registrations.length > 0)",
+      "the display's service worker",
+    ),
+    "the display's offline service worker registers on the API's origin",
+  );
+}
+
+// --- Sign out on the Dashboard -------------------------------------------------------------------
+await navigate(`${dashboardOrigin}/`);
+await waitFor(selector("host-logout"), "the sign-out control");
+await evaluate(`${selector("host-logout")}.click()`);
+check(
+  await waitFor(selector("login-email"), "the sign-in form after sign-out"),
+  "sign-out returns the Dashboard to the sign-in form",
+);
+const principal = await evaluate(`fetch(${JSON.stringify(`${apiOrigin}/api/v1/principal`)}, {
+  credentials: "include",
+}).then((response) => response.json()).then((body) => body.kind)`);
+check(principal === "anonymous", "after sign-out, the API answers anonymous to the same browser");
+
+await cdp.send("Target.closeTarget", { targetId });
+cdp.close();
+if (failures > 0) {
+  console.error(`${failures} check(s) failed`);
+  process.exit(1);
+}

scripts/lib/deploy-smoke-client.mjs

@@ -7,12 +7,20 @@
 //   node deploy-smoke-client.mjs tunnel   the Cloudflare Tunnel connector's fixed address
 //   node deploy-smoke-client.mjs session  the initial owner signing in and out through the proxy
 //
+// Either topology (ADR 0045): SMOKE_HOSTNAME is the API's hostname, and SMOKE_DASHBOARD_HOSTNAME,
+// when set, the Dashboard's. Unset means the same-origin topology, where both are one hostname. Every
+// request goes to the API's origin and carries the Dashboard's origin as `Origin`, as a browser would.
+//
 // Output is one line per check; any failed check exits non-zero. Nothing printed carries a
 // credential, cookie, signed URL, or response body beyond the fixed shapes asserted here.
 
 const mode = process.argv[2];
-const hostname = required("SMOKE_HOSTNAME");
-const origin = `https://${hostname}`;
+const apiOrigin = `https://${required("SMOKE_HOSTNAME")}`;
+const dashboardOrigin = process.env.SMOKE_DASHBOARD_HOSTNAME
+  ? `https://${process.env.SMOKE_DASHBOARD_HOSTNAME}`
+  : apiOrigin;
+const split = dashboardOrigin !== apiOrigin;
+const untrustedOrigin = "https://untrusted.smoke.test";
 
 function required(name) {
   const value = process.env[name];
@@ -34,9 +42,9 @@ function check(condition, description) {
 /** A sign-in attempt that can only fail authentication; what matters is whether the API's
  * per-client limiter (3 attempts per 10 seconds) counts it against the expected client. */
 async function signInAttempt(headers = {}) {
-  const response = await fetch(`${origin}/api/auth/sign-in/email`, {
+  const response = await fetch(`${apiOrigin}/api/auth/sign-in/email`, {
     body: JSON.stringify({ email: "[email protected]", password: "definitely-not-the-password" }),
-    headers: { "content-type": "application/json", origin, ...headers },
+    headers: { "content-type": "application/json", origin: dashboardOrigin, ...headers },
     method: "POST",
   });
   await response.arrayBuffer();
@@ -44,13 +52,13 @@ async function signInAttempt(headers = {}) {
 }
 
 async function edgeChecks() {
-  const ready = await fetch(`${origin}/api/v1/health/ready`);
+  const ready = await fetch(`${apiOrigin}/api/v1/health/ready`);
   check(
     ready.status === 200 && (await ready.text()) === '{"status":"ready"}',
     "GET /api/v1/health/ready through the proxy is 200 ready",
   );
 
-  const page = await fetch(`${origin}/`);
+  const page = await fetch(`${dashboardOrigin}/`);
   const html = await page.text();
   check(page.status === 200, "GET / through the proxy is 200");
   check(
@@ -66,22 +74,32 @@ async function edgeChecks() {
     "the Dashboard page keeps its security headers through the proxy",
   );
 
-  const script = await fetch(`${origin}/assets/ekklesia-dashboard/app.js`);
+  check(
+    html.includes(`<meta content="${apiOrigin}" name="ekklesia-api-origin" />`),
+    "the Dashboard page names the API's origin, rendered at run time (ADR 0045)",
+  );
+
+  const script = await fetch(`${dashboardOrigin}/assets/ekklesia-dashboard/app.js`);
   await script.arrayBuffer();
   check(script.status === 200, "GET /assets/ekklesia-dashboard/app.js is 200");
 
-  const outside = await fetch(`${origin}/favicon.ico`);
+  const outside = await fetch(`${dashboardOrigin}/favicon.ico`);
   check(
     outside.status === 404 && !(outside.headers.get("content-type") ?? "").includes("json"),
     "a path the API does not serve is refused by the proxy, never forwarded",
   );
 
-  const unknownApi = await fetch(`${origin}/api/v1/does-not-exist`);
+  const unknownApi = await fetch(`${apiOrigin}/api/v1/does-not-exist`);
   check(
     unknownApi.status === 404 && (await unknownApi.text()) === '{"code":"NOT_FOUND"}',
     "an unknown /api/* path reaches the API and gets its sanitized 404",
   );
 
+  if (split) {
+    await splitRoutingChecks();
+    await splitCorsChecks();
+  }
+
   await storageDeliveryCheck();
 
   // Every caller-supplied forwarding header rotates on every attempt. If any of them reached the
@@ -106,6 +124,74 @@ async function edgeChecks() {
   );
 }
 
+/** A proxy refusal: Caddy's own empty `404`, never the API's JSON one, so the request was not
+ * forwarded at all. */
+async function refusedByProxy(url) {
+  const response = await fetch(url);
+  const body = await response.text();
+  return response.status === 404 && body === "";
+}
+
+/** Each hostname serves exactly its own paths (ADR 0045, "Routing per hostname"). */
+async function splitRoutingChecks() {
+  check(
+    await refusedByProxy(`${dashboardOrigin}/api/v1/health/ready`),
+    "the Dashboard hostname refuses /api/*, so the session cookie has one home",
+  );
+  check(
+    await refusedByProxy(`${dashboardOrigin}/display/example`),
+    "the Dashboard hostname refuses /display/*",
+  );
+  check(await refusedByProxy(`${apiOrigin}/`), "the API hostname serves nothing at /");
+  check(
+    await refusedByProxy(`${apiOrigin}/assets/ekklesia-dashboard/app.js`),
+    "the API hostname refuses the Dashboard's script",
+  );
+  const display = await fetch(`${apiOrigin}/display/does-not-exist`);
+  check(
+    display.status === 404 && (await display.text()) === '{"code":"NOT_FOUND"}',
+    "the API hostname forwards /display/* to the API (the display host's origin)",
+  );
+}
+
+/** Credentialed CORS for exactly the Dashboard's origin, and for nothing else. */
+async function splitCorsChecks() {
+  const preflight = await fetch(`${apiOrigin}/api/auth/sign-in/email`, {
+    headers: {
+      "access-control-request-headers": "content-type",
+      "access-control-request-method": "POST",
+      origin: dashboardOrigin,
+    },
+    method: "OPTIONS",
+  });
+  await preflight.arrayBuffer();
+  check(
+    preflight.status === 204 &&
+      preflight.headers.get("access-control-allow-origin") === dashboardOrigin &&
+      preflight.headers.get("access-control-allow-credentials") === "true",
+    "a preflight from the Dashboard's origin is allowed, with credentials",
+  );
+  const foreignPreflight = await fetch(`${apiOrigin}/api/auth/sign-in/email`, {
+    headers: { "access-control-request-method": "POST", origin: untrustedOrigin },
+    method: "OPTIONS",
+  });
+  await foreignPreflight.arrayBuffer();
+  check(
+    foreignPreflight.headers.get("access-control-allow-origin") === null,
+    "a preflight from any other origin gets no CORS permission",
+  );
+  const principal = await fetch(`${apiOrigin}/api/v1/principal`, {
+    headers: { origin: dashboardOrigin },
+  });
+  await principal.arrayBuffer();
+  check(
+    principal.headers.get("access-control-allow-origin") === dashboardOrigin &&
+      principal.headers.get("access-control-allow-credentials") === "true" &&
+      (principal.headers.get("vary") ?? "").includes("Origin"),
+    "an API response to the Dashboard's origin reflects exactly that origin, with credentials",
+  );
+}
+
 async function storageDeliveryCheck() {
   // Core's own provider, from the image, exactly as the API composes it: it reaches object-storage
   // over HTTPS on the private network and signs read URLs for the storage hostname.
@@ -184,9 +270,9 @@ async function sessionChecks() {
     "/api/auth/update-session",
     "/api/auth/change-password",
   ]) {
-    const response = await fetch(`${origin}${path}`, {
+    const response = await fetch(`${apiOrigin}${path}`, {
       method: path.endsWith("get-session") || path.endsWith("list-sessions") ? "GET" : "POST",
-      headers: { origin },
+      headers: { origin: dashboardOrigin },
     });
     check(
       response.status === 404 && (await response.text()) === '{"code":"NOT_FOUND"}',
@@ -194,12 +280,12 @@ async function sessionChecks() {
     );
   }
 
-  const signIn = await fetch(`${origin}/api/auth/sign-in/email`, {
+  const signIn = await fetch(`${apiOrigin}/api/auth/sign-in/email`, {
     body: JSON.stringify({
       email: required("SMOKE_OWNER_EMAIL"),
       password: required("SMOKE_OWNER_PASSWORD"),
     }),
-    headers: { "content-type": "application/json", origin },
+    headers: { "content-type": "application/json", origin: dashboardOrigin },
     method: "POST",
   });
   const signInBody = await signIn.text();
@@ -218,20 +304,24 @@ async function sessionChecks() {
   );
   const cookie = setCookie.split(";")[0] ?? "";
 
-  const principal = await fetch(`${origin}/api/v1/principal`, { headers: { cookie, origin } });
+  const principal = await fetch(`${apiOrigin}/api/v1/principal`, {
+    headers: { cookie, origin: dashboardOrigin },
+  });
   const principalBody = await principal.json();
   check(
     principal.status === 200 && principalBody.kind === "authenticated",
     "the session resolves an authenticated principal through the proxy",
   );
 
-  const signOut = await fetch(`${origin}/api/auth/sign-out`, {
+  const signOut = await fetch(`${apiOrigin}/api/auth/sign-out`, {
     body: "{}",
-    headers: { "content-type": "application/json", cookie, origin },
+    headers: { "content-type": "application/json", cookie, origin: dashboardOrigin },
     method: "POST",
   });
   await signOut.arrayBuffer();
-  const after = await fetch(`${origin}/api/v1/principal`, { headers: { cookie, origin } });
+  const after = await fetch(`${apiOrigin}/api/v1/principal`, {
+    headers: { cookie, origin: dashboardOrigin },
+  });
   check(
     signOut.status === 200 && (await after.json()).kind === "anonymous",
     "sign-out ends the session",