feat: add browser auth shell

docs/architecture/decisions/0034-host-owned-browser-authentication.md

@@ -0,0 +1,257 @@
+# 0034: Dashboard browser authentication is host-owned and principal-first
+
+- Status: Accepted
+- Date: 2026-08-23
+- Amends: [0011](0011-identity-http-transport-and-public-enrollment.md)
+- Extends: [0026](0026-minimal-ekklesia-module-ui-host.md),
+  [0027](0027-dashboard-navigation-and-flat-modules.md)
+
+## Context
+
+Ekklesia already had email/password authentication, an HttpOnly session cookie, a minimal
+`GET /api/v1/principal` contract, authorization middleware, and a Dashboard shell. The shell also
+already resolved the principal before requesting protected navigation. What it did not have was a
+browser path for an anonymous person to become authenticated or for an authenticated person to end
+their session. An anonymous bootstrap stopped at a message telling the viewer to sign in, while no
+surface drove the existing authentication endpoints.
+
+Closing that gap affects more than a form. A module UI may have an active API request or realtime
+subscription when a session expires or a person signs out. Better Auth's successful email sign-in
+response also includes a session token and user object in JSON even though the browser session is
+already represented by an HttpOnly cookie. A browser flow must not expose or adopt that redundant
+token, turn every authorization denial into logout, create an open-redirect input, or move platform
+authentication into a feature module.
+
+The display host adds a second important boundary. It is permission-gated today, but unattended
+device identity is explicitly deferred by ADR 0033. Adding Dashboard sign-in must not silently make
+the display application a device enrollment flow or add Dashboard chrome to its bundle.
+
+## Decision
+
+### The host owns authentication UX; modules retain the host-neutral context
+
+`surfaces/shell` owns the Dashboard's sign-in form, pending and failure states, sign-out control,
+session-transition behavior, and credential submission. A module never renders the platform login,
+imports an authentication client, receives a session token, or chooses how the host authenticates.
+
+The public module UI contract remains exactly the five-member, host-neutral
+`ModuleUiHostContext`: `moduleId`, `api`, `principal`, `permissions`, and `realtime`. No sign-in,
+sign-out, credential, cookie, token, or Ekklesia-specific session callback is added to it. The host
+may observe authorization responses from the API client it supplies, but that observation remains
+host-private and the module still receives the original response.
+
+This keeps one module artifact runnable under Ekklesia and a future standalone host. A standalone
+application will own its authentication experience just as the Ekklesia Dashboard owns this one;
+the module will continue to see only the same narrow principal and permission hints.
+
+### Dashboard bootstrap remains principal-first
+
+The Dashboard resolves `GET /api/v1/principal` before requesting navigation or rendering any module
+UI:
+
+```text
+loading
+  -> anonymous -> host-owned login
+  -> authenticated -> protected Dashboard navigation -> selected module
+  -> unavailable/invalid -> sanitized failure with explicit retry
+```
+
+An anonymous principal is an ordinary, successful identity result, not an application failure. A
+principal infrastructure failure is not anonymous and does not reveal a login form that would
+misrepresent the outage as a missing session. No protected Dashboard request is made and no module
+code is loaded until the authenticated branch is established.
+
+After a successful sign-in mutation, the host does not trust an authentication response as a
+principal. It resolves `/api/v1/principal` again and only then loads Dashboard navigation. This
+changes the rendered state in place; a full page reload is not required.
+
+### Email/password uses the native endpoint behind two narrow browser-safe exceptions
+
+The browser submits JSON credentials with `credentials: "include"` to Better Auth's existing
+native endpoint:
+
+```text
+POST /api/auth/sign-in/email
+```
+
+ADR 0011 made normal Better Auth responses pass through the Core identity runtime unchanged. That
+remains true inside Core. This decision introduces exactly two browser-facing exceptions at the
+`apps/api` transport boundary:
+
+1. When the exact email sign-in endpoint returns any body-bearing successful `2xx`, `apps/api`
+   preserves that status and the headers — including `Set-Cookie` — but replaces the body with the
+   fixed response below.
+2. The token-bearing native session inspection/mutation paths `/api/auth/get-session`,
+   `/api/auth/list-sessions`, `/api/auth/update-session`, and `/api/auth/change-password` are
+   unavailable. The API returns the same sanitized `404 {"code":"NOT_FOUND"}` as an unsupported
+   route without invoking Better Auth. Password/account management is outside this pass; the pinned
+   change-password route can return a new raw token when it revokes other sessions, so it cannot be
+   left as an unused bypass.
+
+```json
+{ "ok": true }
+```
+
+Sign-in failures and every other supported Better Auth endpoint keep their existing response
+semantics. These exceptions are not a second authentication protocol: supported requests still
+reach Better Auth, Better Auth still creates and invalidates the session, and its HttpOnly cookie
+remains the only browser session authority. The normalization discards the redundant session token
+and user object before browser application JavaScript can read them. The denylist prevents a caller
+from bypassing the narrow Ekklesia identity contract to inspect or mutate native session objects.
+The supported browser identity read is exclusively `GET /api/v1/principal`; the shell treats
+`{ "ok": true }` only as permission to re-resolve it and does not persist, log, or derive identity
+from the body.
+
+The form exposes only email and password. It is a semantic browser form with labelled inputs,
+`username` and `current-password` autocomplete hints, keyboard submission, one in-flight attempt,
+and a visible pending state. A completed attempt clears the password while retaining the email for
+correction. Credential rejection has one generic message; service and malformed-response failures
+have a separate fixed generic message. Raw response bodies, caught exceptions, credentials, and
+request URLs never reach the DOM or console.
+
+### Sign-out invalidates first, then asks the principal authority
+
+The host submits an empty JSON object with `credentials: "include"` to the existing endpoint:
+
+```text
+POST /api/auth/sign-out
+```
+
+After the sign-out mutation succeeds, the host resolves `/api/v1/principal` instead of assuming
+that hiding the Dashboard equals logout. An anonymous result shows the login form. If the sign-out
+request throws or the subsequent principal resolution fails, protected UI stays removed and the
+host shows a sanitized failure with actions to retry sign-out or explicitly rebootstrap. It neither
+claims that the session ended nor automatically restores an authenticated state it has not
+revalidated.
+
+While the transition is in progress, the authenticated Dashboard subtree is removed. The generic
+module loader therefore invokes the selected module's existing unmount cleanup, and the module's
+host-owned realtime subscriptions close through their ordinary cleanup path. No module-specific
+logout event or teardown API is introduced.
+
+### Platform bootstrap and module responses use different status policies
+
+A `401` from a platform-owned bootstrap request is an authentication challenge in the host's own
+fixed contract. The platform request helper maps it directly to `HOST_UNAUTHENTICATED`, and the
+principal-first Dashboard returns to login without treating it as an arbitrary module response. A
+platform navigation `403` remains an access denial and receives the existing principal recheck so
+the host can distinguish an authenticated denial from a session that expired between the principal
+and navigation requests.
+
+A module owns its response semantics and may return `401` or `403` for reasons that do not invalidate
+the host session. Either status observed through the module API facade therefore triggers one
+deduplicated `/api/v1/principal` revalidation while the module still receives its original response:
+
+- anonymous means the session ended, so the host unmounts the active module and shows login;
+- authenticated means the session and mounted module remain in place and the original module
+  response remains that module's result;
+- an infrastructure failure becomes a sanitized retryable host failure, never a fabricated logout.
+
+A burst of module denials shares the in-flight principal revalidation. A response retained by a
+module frame that has already unmounted cannot start or overwrite a newer auth transition. A network
+error, malformed response, `404`, or `5xx` never clears authentication merely because it occurred.
+Realtime retains ADR 0032's native reconnect and five-minute server reauthorization; when a verified
+anonymous principal moves the host out of the authenticated state, normal module unmount closes its
+EventSource.
+
+### There is no return URL or redirect sink in this pass
+
+Login renders at the current Dashboard URL and successful authentication replaces that state in
+place. The host accepts no `return`, `returnTo`, `callbackURL`, or equivalent request/query value,
+passes no callback URL to Better Auth, and performs no script-driven navigation. External,
+protocol-relative, backslash-prefixed, or scheme-bearing input therefore has no path to become a
+redirect target.
+
+A future client router may define an internal return-location contract, but it must be a separately
+validated, same-origin route decision. This pass does not create one speculatively.
+
+### Cookie and origin policy does not broaden for the Dashboard
+
+The session cookie keeps the identity platform's existing properties: HttpOnly, SameSite=Lax,
+Secure when the canonical identity base URL uses HTTPS, Path `/`, and no `Domain` attribute. It is
+host-only. Ekklesia does not broaden it to a parent domain merely so sibling subdomains can share a
+session.
+
+The simplest production shape is a Dashboard whose `/api` traffic is reverse-proxied on the same
+origin. A deliberately split browser/API origin remains possible only through the exact canonical
+trusted-origin allowlist and credentialed CORS already defined by ADR 0011, ADR 0012, and ADR 0018.
+Wildcards remain invalid. Better Auth's origin and CSRF checks remain explicitly enabled in every
+environment; the browser supplies its real `Origin` naturally rather than manufacturing or
+weakening it.
+
+The repository still provides no production Dashboard hostname, DNS, TLS, reverse-proxy rule,
+Content-Security-Policy, or static-asset deployment. Host-only cookies mean any eventual choice to
+place the API and Dashboard on different sibling subdomains must be designed and tested rather than
+assumed to share a session.
+
+### Enrollment, recovery, throttling, and first ownership remain explicit gaps
+
+The login page is for an existing account. It contains no create-account link because public signup
+is disabled by default and prohibited in production by ADR 0017. It contains no forgot-password or
+verification flow because Ekklesia has no email sender, recovery delivery, or verified-email
+contract. Their absence is visible product scope, not a hidden link to a non-operational endpoint.
+
+Better Auth's sign-in limiter remains enabled with its strict per-path production rule of three
+attempts per ten seconds. Its store is in-memory and per API process: counters do not span multiple
+instances and do not survive restart. The server-owned client-address boundary prevents a caller
+from choosing a new bucket with a spoofed forwarding header, but it does not turn this into a shared
+or durable brute-force defense. A multi-instance or publicly launched deployment still needs a
+proven shared or edge limiter.
+
+The platform-owner bootstrap command still accepts only an **existing** Ekklesia user ID. Because
+production public signup is prohibited and no invitation or operator-owned user-creation command
+exists, this repository does not yet provide a supported way to create the first production
+identity that bootstrap needs. Tests may create a development identity, bootstrap it, and prove the
+owner's browser session reaches protected Dashboard resources; that evidence must not be described
+as production first-user provisioning.
+
+## Consequences
+
+- An anonymous Dashboard visit reaches a real, accessible email/password login without exposing
+  Better Auth's session token to browser application JavaScript.
+- `/api/v1/principal` is the only supported browser session read; token-bearing native session and
+  password mutation routes cannot become an accidental parallel contract.
+- Reload uses the existing cookie and principal endpoint; sign-in and sign-out do not require a
+  client router or full-page navigation.
+- Authentication transitions tear down the selected module through the generic loader's existing
+  lifecycle, including its realtime cleanup.
+- A module remains ignorant of Ekklesia's credentials, auth endpoints, cookies, and response-status
+  policy.
+- An authorization denial does not automatically become logout, while an expired session can still
+  return to login without a reload.
+- The host-only cookie preserves the narrow existing trust boundary and leaves deployment topology
+  as explicit future work.
+
+## Rejected alternatives
+
+- **Put login in a module or add auth methods to `ModuleUiHostContext`.** Authentication is
+  platform shell policy and would make portable module UI depend on its Ekklesia host.
+- **Let the browser consume Better Auth's native sign-in success JSON.** Its token and user object
+  duplicate the cookie authority and unnecessarily expose identity/session material to same-realm
+  JavaScript.
+- **Leave native session endpoints mounted because this UI does not call them.** Same-realm code can
+  call an available route directly; unused token-bearing inspection/mutation endpoints would bypass
+  the principal contract, and `change-password` can issue a raw replacement token.
+- **Trust the sign-in response as the current user.** `/api/v1/principal` is the narrow Ekklesia
+  identity contract and remains the only authority for host state.
+- **Treat every module `401` or `403` as session expiry.** A valid authenticated session may receive
+  either status from module-owned behavior; automatic logout would let an untrusted response erase
+  host authentication without consulting the principal authority.
+- **Accept a callback or return URL for convenience.** The Dashboard has no client router in this
+  pass, so such an input creates redirect risk without a product need.
+- **Set a parent-domain cookie.** It broadens which hosts receive the credential and prejudges a
+  deployment topology that does not exist.
+- **Add signup or password-reset links that point to incomplete flows.** Production enrollment and
+  email delivery are not implemented.
+
+## Deferred
+
+- invitation or operator-driven production enrollment, verified email, password recovery,
+  authenticated account/password management, and production first-user creation;
+- shared/durable authentication throttling and proof against the deployed reverse proxy;
+- a production Dashboard origin, built-asset hosting, CSP, DNS, TLS, and proxy configuration;
+- a client router and any validated internal post-login return-location contract;
+- device registration, pairing, unattended credentials, and public-display policy from ADR 0033;
+- public Website authentication and routing;
+- standalone-host authentication UX;
+- every Phase 7B pass 2 product capability.