feat: give display devices their own paired identity

ADR 0033 gave Ekklesia a display host and ADR 0034 gave it a login page.
Together, the only way to light a television in a foyer was to sign a
human being into it and leave that session running on a screen anyone can
walk up to: a person's credentials on a wall, a person's session as the
thing signage depends on, and the display going dark when they are
revoked or their session simply expires.

A screen is not a person. Ekklesia now recognizes three principal classes
— anonymous, authenticated human, and managed device — and a device is a
first-class principal with its own credential and its own explicit
permissions. It has no email, no password, and no row in the identity
tables, and it satisfies the `authenticated` baseline never, so every
route that settles for "somebody is signed in" stays closed to it.

Device permissions live in their own table because
ekklesia_core_grant.user_id is a non-null foreign key into the user table
and making it polymorphic would rewrite the platform's central
authorization record to serve one narrow case. That is a schema decision,
not a second decision point: the evaluator gained one branch, so a device
is allowed or denied by the same function, with the same deny-by-default,
as anyone else — with no owner path it could reach and no baseline that
stands in for a grant.

The six-digit code is not the credential. It is printed across a screen in
a public hallway, so it is treated as public: it identifies a request to
an administrator and is worth nothing alone. Collecting the credential
also requires a 256-bit claim secret held only in the requesting browser's
HttpOnly cookie, and approving requires the restricted core.devices.manage
permission. Without that split, reading a code off a wall would hand over
the screen's identity.

The permission a pairing asks for is read from the module's validated
display declaration, never from the request, so a browser cannot ask to be
granted core.devices.manage or another module's permission. Approval
grants exactly that one permission.

Credentials are stored only as SHA-256; the raw value exists in the
Set-Cookie that issues it and the device's own cookie jar, and is never
logged, returned in JSON, or placed in a URL. The cookie is HttpOnly, so
the module display code running in that same page cannot read it.
Revocation is a server-side column checked on every principal resolution,
and re-pairing mints a new identity so an old credential can never come
back. State transitions are conditional updates, so one code cannot be
approved twice or claimed into two credentials under a race.

/api/v1/principal still reports a device as anonymous: it is what the
Dashboard uses to decide whether a person is signed in. Displays read
their viewer from the descriptor instead, which already performed the
authorization — so displays are descriptor-first while the Dashboard stays
principal-first, and neither infers an identity by elimination.

Proven end to end against real PostgreSQL and real HTTP: an unpaired
screen shows a code, an owner approves it, the device opens the display
descriptor and a realtime stream, and revocation closes both while the
device still holds its cookie. An already-open SSE stream is bounded by
realtime's existing five-minute reconnect rather than closed instantly,
and that bound is documented rather than called immediate.

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

surfaces/shell/src/display/DisplayApp.tsx

@@ -7,11 +7,13 @@ import {
   HostProtocolError,
 } from "../host-protocol.js";
 import { DisplayUiFrame } from "./DisplayUiFrame.js";
+import { PairingScreen } from "./PairingScreen.js";
 
 type DisplayState =
   | { readonly status: "loading"; readonly generation: number }
   | { readonly status: "ready"; readonly bootstrap: DisplayHostBootstrap & { status: "ready" } }
-  | { readonly status: "signed-out" }
+  /** No identity this display can use yet: show a pairing code rather than a human login form. */
+  | { readonly status: "pairing" }
   | { readonly status: "unavailable" }
   | { readonly status: "failed" };
 
@@ -93,24 +95,26 @@ export function DisplayApp(props: DisplayAppProps): ReactElement {
         if (abort.signal.aborted) {
           return;
         }
-        setState(
-          bootstrap.status === "signed-out"
-            ? { status: "signed-out" }
-            : { bootstrap, status: "ready" },
-        );
+        setState({ bootstrap, status: "ready" });
       })
       .catch((error: unknown) => {
         if (abort.signal.aborted) {
           return;
         }
+        // A denied or unauthenticated descriptor is the ordinary state of a screen nobody has
+        // paired yet, not an error worth logging on every wall in the building.
+        if (
+          error instanceof HostProtocolError &&
+          (error.code === "DISPLAY_ACCESS_DENIED" || error.code === "HOST_UNAUTHENTICATED")
+        ) {
+          setState({ status: "pairing" });
+          return;
+        }
         console.error("[ekklesia] display host bootstrap failed", error);
         setState(
-          error instanceof HostProtocolError &&
-            (error.code === "DISPLAY_ACCESS_DENIED" || error.code === "DISPLAY_NOT_AVAILABLE")
+          error instanceof HostProtocolError && error.code === "DISPLAY_NOT_AVAILABLE"
             ? { status: "unavailable" }
-            : error instanceof HostProtocolError && error.code === "HOST_UNAUTHENTICATED"
-              ? { status: "signed-out" }
-              : { status: "failed" },
+            : { status: "failed" },
         );
       });
     return () => abort.abort();
@@ -123,10 +127,8 @@ export function DisplayApp(props: DisplayAppProps): ReactElement {
       {state.status === "loading" ? (
         <DisplayMessage testId="display-host-loading">Loading display…</DisplayMessage>
       ) : undefined}
-      {state.status === "signed-out" ? (
-        <DisplayMessage onRetry={retry} testId="display-host-signed-out">
-          Sign in to use this display.
-        </DisplayMessage>
+      {state.status === "pairing" ? (
+        <PairingScreen config={config} moduleId={moduleId} onRetry={retry} />
       ) : undefined}
       {state.status === "unavailable" ? (
         <DisplayMessage onRetry={retry} testId="display-host-unavailable">

surfaces/shell/src/display/PairingScreen.tsx

@@ -0,0 +1,154 @@
+import { type ReactElement, useEffect, useRef, useState } from "react";
+import {
+  type EkklesiaHostConfig,
+  HostProtocolError,
+  pollDevicePairing,
+  requestDevicePairing,
+} from "../host-protocol.js";
+
+/**
+ * What an unpaired screen shows: a short code, and nothing else of consequence.
+ *
+ * This page is looked at by whoever walks past a television, so it deliberately carries no request
+ * id, no claim secret, no permission id, no module internals, and no server URL beyond the one the
+ * browser is already on. The code is the only thing on it that means anything, and the code is
+ * useless on its own — approving it requires an administrator, and collecting the credential
+ * requires the HttpOnly cookie this browser holds and nobody watching can see (ADR 0036).
+ */
+const pairingStyles = {
+  code: {
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+    fontSize: "clamp(3rem, 14vw, 9rem)",
+    fontWeight: 600,
+    letterSpacing: "0.15em",
+    lineHeight: 1.1,
+    margin: 0,
+  },
+  hint: { color: "#78716c", margin: 0, maxWidth: "40ch" },
+  root: {
+    alignItems: "center",
+    background: "#0c0a09",
+    color: "#fafaf9",
+    display: "flex",
+    flexDirection: "column",
+    gap: "1.5rem",
+    height: "100%",
+    justifyContent: "center",
+    minHeight: "100dvh",
+    padding: "2rem",
+    textAlign: "center",
+  },
+  title: { fontFamily: "system-ui, sans-serif", fontSize: "1.25rem", fontWeight: 500, margin: 0 },
+} as const;
+
+type PairingState =
+  | { readonly status: "requesting" }
+  | { readonly status: "waiting"; readonly code: string }
+  | { readonly status: "unavailable" };
+
+export interface PairingScreenProps {
+  readonly config: EkklesiaHostConfig;
+  readonly moduleId: string;
+  /** Called once the host has issued this device its session, so the display mounts itself without
+   * anyone touching the television. */
+  readonly onRetry: () => void;
+}
+
+export function PairingScreen(props: PairingScreenProps): ReactElement {
+  const { config, moduleId, onRetry } = props;
+  const [state, setState] = useState<PairingState>({ status: "requesting" });
+  const pairedRef = useRef(onRetry);
+  pairedRef.current = onRetry;
+
+  useEffect(() => {
+    const abort = new AbortController();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let stopped = false;
+
+    const stop = (): void => {
+      stopped = true;
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+    };
+
+    const begin = async (): Promise<void> => {
+      let requested: { code: string; pollIntervalMs: number };
+      try {
+        requested = await requestDevicePairing(config, moduleId, abort.signal);
+      } catch (error) {
+        if (!abort.signal.aborted) {
+          // Never surfaces the underlying reason on a public screen.
+          if (!(error instanceof HostProtocolError)) {
+            console.error("[ekklesia] pairing request failed");
+          }
+          setState({ status: "unavailable" });
+        }
+        return;
+      }
+      if (stopped || abort.signal.aborted) {
+        return;
+      }
+      setState({ code: requested.code, status: "waiting" });
+
+      const poll = async (): Promise<void> => {
+        if (stopped || abort.signal.aborted) {
+          return;
+        }
+        let status: string;
+        try {
+          status = await pollDevicePairing(config, abort.signal);
+        } catch {
+          // A transient failure is not a reason to abandon a screen that may be on a wall; it asks
+          // again on the next tick.
+          timer = setTimeout(() => void poll(), requested.pollIntervalMs);
+          return;
+        }
+        if (status === "paired") {
+          stop();
+          pairedRef.current();
+          return;
+        }
+        if (status === "expired" || status === "unknown") {
+          // The code aged out before anyone approved it. Draw a fresh one rather than leaving a
+          // dead number on the screen.
+          stop();
+          void begin();
+          return;
+        }
+        timer = setTimeout(() => void poll(), requested.pollIntervalMs);
+      };
+      timer = setTimeout(() => void poll(), requested.pollIntervalMs);
+    };
+
+    void begin();
+    return () => {
+      stop();
+      abort.abort();
+    };
+  }, [config, moduleId]);
+
+  return (
+    <div data-testid="display-pairing" style={pairingStyles.root}>
+      {state.status === "waiting" ? (
+        <>
+          <p style={pairingStyles.title}>Pair this display</p>
+          <p data-testid="display-pairing-code" style={pairingStyles.code}>
+            {state.code}
+          </p>
+          <p style={pairingStyles.hint}>
+            Enter this code in the Ekklesia dashboard to connect this screen. Waiting for approval…
+          </p>
+        </>
+      ) : undefined}
+      {state.status === "requesting" ? (
+        <p style={pairingStyles.title}>Preparing this display…</p>
+      ) : undefined}
+      {state.status === "unavailable" ? (
+        <p data-testid="display-pairing-unavailable" style={pairingStyles.title}>
+          This display is not available.
+        </p>
+      ) : undefined}
+    </div>
+  );
+}