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/browser/DevicePanel.tsx

@@ -0,0 +1,207 @@
+import { type FormEvent, type ReactElement, useCallback, useEffect, useState } from "react";
+import {
+  approveDevicePairing,
+  type EkklesiaHostConfig,
+  type HostDeviceSummary,
+  listHostDevices,
+  lookupDevicePairing,
+  revokeHostDevice,
+} from "../host-protocol.js";
+
+/**
+ * The administrator's whole device surface: type the code from a screen, name it, approve it, and
+ * later take it away again.
+ *
+ * Deliberately small. Device identity belongs to the platform rather than to any module, so it has
+ * to live in the host — but this is infrastructure plumbing, not a fleet-management product, and
+ * there is no grouping, filtering, bulk action, targeting, health, or remote control here on
+ * purpose (ADR 0036). It renders only for an administrator who actually holds `core.devices.manage`:
+ * a viewer without it is told nothing about which devices exist.
+ */
+const panelStyles = {
+  action: {
+    background: "transparent",
+    border: "1px solid #d6d3d1",
+    borderRadius: "0.25rem",
+    cursor: "pointer",
+    font: "inherit",
+    padding: "0.25rem 0.5rem",
+  },
+  input: {
+    border: "1px solid #d6d3d1",
+    borderRadius: "0.25rem",
+    font: "inherit",
+    minWidth: 0,
+    padding: "0.25rem 0.5rem",
+    width: "100%",
+  },
+  meta: { color: "#78716c", fontSize: "0.8125rem", margin: 0 },
+  row: {
+    alignItems: "center",
+    borderTop: "1px solid #e7e5e4",
+    display: "flex",
+    gap: "0.5rem",
+    justifyContent: "space-between",
+    padding: "0.375rem 0",
+  },
+  section: { display: "grid", gap: "0.5rem" },
+  title: { fontSize: "0.8125rem", fontWeight: 600, letterSpacing: "0.04em", margin: 0 },
+} as const;
+
+type PairingStep =
+  | { readonly step: "idle" }
+  | { readonly step: "busy" }
+  | { readonly step: "found"; readonly moduleId: string; readonly permissionId: string }
+  | { readonly step: "error"; readonly message: string };
+
+export interface DevicePanelProps {
+  readonly config: EkklesiaHostConfig;
+}
+
+export function DevicePanel(props: DevicePanelProps): ReactElement | undefined {
+  const { config } = props;
+  const [devices, setDevices] = useState<readonly HostDeviceSummary[] | undefined>(undefined);
+  const [permitted, setPermitted] = useState(true);
+  const [code, setCode] = useState("");
+  const [name, setName] = useState("");
+  const [pairing, setPairing] = useState<PairingStep>({ step: "idle" });
+
+  const refresh = useCallback(async (): Promise<void> => {
+    try {
+      setDevices(await listHostDevices(config));
+    } catch {
+      // The panel simply does not render for someone who may not manage devices; it never explains
+      // what it would have shown.
+      setPermitted(false);
+    }
+  }, [config]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  if (!permitted) {
+    return undefined;
+  }
+
+  const lookUp = async (event: FormEvent): Promise<void> => {
+    event.preventDefault();
+    setPairing({ step: "busy" });
+    try {
+      const found = await lookupDevicePairing(config, code.trim());
+      setPairing({ moduleId: found.moduleId, permissionId: found.permissionId, step: "found" });
+    } catch {
+      // One message for expired, consumed, mistyped, and never-existed alike.
+      setPairing({ message: "That code is not waiting for approval.", step: "error" });
+    }
+  };
+
+  const approve = async (): Promise<void> => {
+    setPairing({ step: "busy" });
+    try {
+      await approveDevicePairing(config, code.trim(), name.trim());
+      setCode("");
+      setName("");
+      setPairing({ step: "idle" });
+      await refresh();
+    } catch {
+      setPairing({ message: "That code could not be approved.", step: "error" });
+    }
+  };
+
+  const revoke = async (deviceId: string): Promise<void> => {
+    try {
+      await revokeHostDevice(config, deviceId);
+      await refresh();
+    } catch {
+      // Left to the next refresh rather than asserting a failure the operator cannot act on.
+    }
+    await refresh();
+  };
+
+  return (
+    <section data-testid="host-devices" style={panelStyles.section}>
+      <h2 style={panelStyles.title}>DISPLAY DEVICES</h2>
+
+      <form onSubmit={(event) => void lookUp(event)} style={{ display: "grid", gap: "0.375rem" }}>
+        <label htmlFor="device-pairing-code" style={panelStyles.meta}>
+          Pairing code shown on the screen
+        </label>
+        <input
+          autoComplete="off"
+          data-testid="device-pairing-code-input"
+          id="device-pairing-code"
+          inputMode="numeric"
+          maxLength={6}
+          onChange={(event) => setCode(event.target.value)}
+          style={panelStyles.input}
+          value={code}
+        />
+        <button data-testid="device-pairing-lookup" style={panelStyles.action} type="submit">
+          Find display
+        </button>
+      </form>
+
+      {pairing.step === "found" ? (
+        <div data-testid="device-pairing-found" style={{ display: "grid", gap: "0.375rem" }}>
+          <p style={panelStyles.meta}>
+            A display is asking to show <strong>{pairing.moduleId}</strong>.
+          </p>
+          <label htmlFor="device-pairing-name" style={panelStyles.meta}>
+            Name this display
+          </label>
+          <input
+            autoComplete="off"
+            data-testid="device-pairing-name"
+            id="device-pairing-name"
+            maxLength={128}
+            onChange={(event) => setName(event.target.value)}
+            placeholder="Foyer TV"
+            style={panelStyles.input}
+            value={name}
+          />
+          <button
+            data-testid="device-pairing-approve"
+            disabled={name.trim().length === 0}
+            onClick={() => void approve()}
+            style={panelStyles.action}
+            type="button"
+          >
+            Approve
+          </button>
+        </div>
+      ) : undefined}
+
+      {pairing.step === "error" ? (
+        <p data-testid="device-pairing-error" style={panelStyles.meta}>
+          {pairing.message}
+        </p>
+      ) : undefined}
+
+      {devices !== undefined && devices.length === 0 ? (
+        <p data-testid="device-list-empty" style={panelStyles.meta}>
+          No displays are paired.
+        </p>
+      ) : undefined}
+
+      {devices?.map((device) => (
+        <div data-testid={`device-${device.id}`} key={device.id} style={panelStyles.row}>
+          <span>
+            {device.name}
+            {device.revoked ? " (revoked)" : ""}
+          </span>
+          {device.revoked ? undefined : (
+            <button
+              data-testid={`device-revoke-${device.id}`}
+              onClick={() => void revoke(device.id)}
+              style={panelStyles.action}
+              type="button"
+            >
+              Revoke
+            </button>
+          )}
+        </div>
+      ))}
+    </section>
+  );
+}

surfaces/shell/src/browser/HostApp.tsx

@@ -14,6 +14,7 @@ import {
   HostProtocolError,
   loadHostPrincipal,
 } from "../host-protocol.js";
+import { DevicePanel } from "./DevicePanel.js";
 import { LoginForm } from "./LoginForm.js";
 import { ModuleUiFrame } from "./ModuleUiFrame.js";
 
@@ -157,9 +158,13 @@ async function resolveBootstrapState(
 ): Promise<ResolvedBootstrapState> {
   try {
     const bootstrap = await bootstrapHost(config, signal);
-    return bootstrap.principal.kind === "anonymous"
-      ? { status: "anonymous" }
-      : { bootstrap, status: "ready" };
+    // Only a person signs into the Dashboard. The test is `=== "authenticated"` and never "not
+    // anonymous", so a principal class added later cannot quietly become a Dashboard login — which
+    // is precisely how a paired display device would otherwise have walked in (ADR 0036). In
+    // practice `/api/v1/principal` never reports a device at all; this is the second lock.
+    return bootstrap.principal.kind === "authenticated"
+      ? { bootstrap: { ...bootstrap, principal: bootstrap.principal }, status: "ready" }
+      : { status: "anonymous" };
   } catch (error) {
     if (error instanceof HostProtocolError && error.code === "HOST_UNAUTHENTICATED") {
       return { status: "anonymous" };
@@ -167,9 +172,9 @@ async function resolveBootstrapState(
     if (error instanceof HostProtocolError && error.code === "HOST_ACCESS_DENIED") {
       try {
         const principal = await loadHostPrincipal(config, signal);
-        return principal.kind === "anonymous"
-          ? { status: "anonymous" }
-          : { principal, status: "access-denied" };
+        return principal.kind === "authenticated"
+          ? { principal, status: "access-denied" }
+          : { status: "anonymous" };
       } catch {
         return { status: "failed" };
       }
@@ -454,6 +459,7 @@ export function HostApp(props: HostAppProps): ReactElement {
         </button>
       </header>
       <aside style={shellStyles.aside}>
+        <DevicePanel config={config} />
         {entries.length === 0 && groups.length === 0 ? (
           <p data-testid="host-empty" style={{ color: "#57534e", margin: 0 }}>
             No installed module provides a user interface.