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/tests/display-app.test.tsx

@@ -35,8 +35,16 @@ afterEach(async () => {
   consoleError.mockRestore();
 });
 
-function descriptorPayload(id = "announcements", version = "1.2.0") {
+function descriptorPayload(
+  id = "announcements",
+  version = "1.2.0",
+  viewer: unknown = {
+    kind: "authenticated",
+    userId: "user-1",
+  },
+) {
   return {
+    viewer,
     module: {
       api: { baseUrl: `/api/v1/modules/${id}` },
       display: { url: `/api/v1/module-ui/${id}/${version}/display` },
@@ -71,6 +79,15 @@ function platform(options: PlatformOptions = {}) {
     if (url.endsWith("/api/v1/module-displays/announcements")) {
       return json(descriptorPayload(), options.descriptorStatus ?? 200);
     }
+    if (url.endsWith("/api/v1/device-pairing/requests")) {
+      return json(
+        { code: "482731", expiresAt: new Date().toISOString(), pollIntervalMs: 60_000 },
+        201,
+      );
+    }
+    if (url.endsWith("/api/v1/device-pairing/claims")) {
+      return json({ status: "pending" });
+    }
     if (url.endsWith("/api/v1/modules/announcements/slides")) {
       return json([{ id: "slide-1" }]);
     }
@@ -394,26 +411,44 @@ describe("display host — full-viewport boundary", () => {
 });
 
 describe("display host — authentication and controlled failures", () => {
-  it("mounts nothing and never requests a descriptor for an anonymous browser", async () => {
-    const server = platform({ principal: { kind: "anonymous" } });
+  it("shows a pairing code instead of a human login when it has no identity", async () => {
+    const server = platform({ descriptorStatus: 403 });
     const importer = vi.fn(async () => artifact());
 
     await render({ apiBaseUrl, fetch: server.fetch }, importer);
 
-    expect(query("display-host-signed-out")).not.toBeNull();
+    // An unattended screen must never be sent to an email/password form: nobody is standing at it.
+    expect(query("display-host-signed-out")).toBeNull();
+    expect(query("display-pairing")).not.toBeNull();
+    expect(query("display-pairing-code")?.textContent).toBe("482731");
+    // The protected artifact is still not fetched, which is the invariant that matters.
     expect(importer).not.toHaveBeenCalled();
-    expect(server.calls.map((call) => call.url)).toEqual([`${apiBaseUrl}/api/v1/principal`]);
+    // And the display never asks the human principal endpoint at all.
+    expect(server.calls.some((call) => call.url.endsWith("/api/v1/principal"))).toBe(false);
   });
 
-  it("does not import protected display code when the descriptor is denied or unavailable", async () => {
-    for (const status of [403, 404]) {
-      const server = platform({ descriptorStatus: status });
-      const importer = vi.fn(async () => artifact());
-      await render({ apiBaseUrl, fetch: server.fetch }, importer);
+  it("puts no request id, secret, or permission on a screen anyone can read", async () => {
+    const server = platform({ descriptorStatus: 403 });
+    await render(
+      { apiBaseUrl, fetch: server.fetch },
+      vi.fn(async () => artifact()),
+    );
 
-      expect(query("display-host-unavailable"), String(status)).not.toBeNull();
-      expect(importer, String(status)).not.toHaveBeenCalled();
-    }
+    const rendered = container.textContent ?? "";
+    expect(rendered).toContain("482731");
+    expect(rendered).not.toMatch(/announcements\.slideshow\.view|device-pairing|claim|token/u);
+  });
+
+  it("does not import protected display code when the display is unavailable", async () => {
+    const server = platform({ descriptorStatus: 404 });
+    const importer = vi.fn(async () => artifact());
+
+    await render({ apiBaseUrl, fetch: server.fetch }, importer);
+
+    // 404 is "there is no such display", which pairing cannot fix — so it stays a plain message.
+    expect(query("display-host-unavailable")).not.toBeNull();
+    expect(query("display-pairing")).toBeNull();
+    expect(importer).not.toHaveBeenCalled();
   });
 
   it("clears partial mount DOM, renders no caught detail, and retries in a fresh container", async () => {

surfaces/shell/tests/display-host-protocol.test.ts

@@ -11,8 +11,12 @@ const apiBaseUrl = "https://ekklesia.example.test";
 
 function displayPayload(overrides: Record<string, unknown> = {}): {
   readonly module: Record<string, unknown>;
+  readonly viewer: Record<string, unknown>;
 } {
   return {
+    // The host states who it authorized, so the display never has to infer it from the absence of a
+    // human session (ADR 0036).
+    viewer: { kind: "authenticated", userId: "user-1" },
     module: {
       api: { baseUrl: "/api/v1/modules/announcements" },
       display: { url: "/api/v1/module-ui/announcements/1.2.0/display" },
@@ -45,6 +49,7 @@ describe("display host protocol — strict descriptor", () => {
         uiUrl: "/api/v1/module-ui/announcements/1.2.0/display",
         version: "1.2.0",
       },
+      viewer: { kind: "authenticated", userId: "user-1" },
     });
     expect(Object.isFrozen(parsed)).toBe(true);
     expect(Object.isFrozen(parsed.module)).toBe(true);
@@ -124,35 +129,58 @@ describe("display host protocol — outer route", () => {
 });
 
 describe("display host protocol — authenticated bootstrap", () => {
-  it("loads principal first, then the exact descriptor, with host-owned credentials", async () => {
+  it("asks only the descriptor, which is the display's actual authorization boundary", async () => {
     const calls: Array<{ init: RequestInit | undefined; url: string }> = [];
     const fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
       const url = String(input);
       calls.push({ init, url });
-      return url.endsWith("/api/v1/principal")
-        ? json({ kind: "authenticated", userId: "user-1" })
-        : json(displayPayload());
+      return json(displayPayload());
     }) as unknown as typeof globalThis.fetch;
 
     const bootstrap = await bootstrapDisplayHost({ apiBaseUrl, fetch }, "announcements");
 
     expect(bootstrap.status).toBe("ready");
+    // Deliberately **not** principal-first, unlike the Dashboard: `/api/v1/principal` answers about
+    // people, and a paired device is anonymous to it by design, so asking it first would conclude
+    // that every display in the building was signed out (ADR 0036).
     expect(calls.map((call) => call.url)).toEqual([
-      `${apiBaseUrl}/api/v1/principal`,
       `${apiBaseUrl}/api/v1/module-displays/announcements`,
     ]);
     expect(calls.every((call) => call.init?.credentials === "include")).toBe(true);
   });
 
-  it("does not probe a display descriptor for an anonymous principal", async () => {
-    const fetch = vi.fn(async () =>
-      json({ kind: "anonymous" }),
-    ) as unknown as typeof globalThis.fetch;
+  it("reports the viewer the host authorized, for a person and for a device alike", async () => {
+    const forViewer = async (viewer: Record<string, unknown>) => {
+      const fetch = vi.fn(async () =>
+        json({ ...displayPayload(), viewer }),
+      ) as unknown as typeof globalThis.fetch;
+      return bootstrapDisplayHost({ apiBaseUrl, fetch }, "announcements");
+    };
 
-    const bootstrap = await bootstrapDisplayHost({ apiBaseUrl, fetch }, "announcements");
+    expect((await forViewer({ kind: "authenticated", userId: "user-1" })).principal).toEqual({
+      kind: "authenticated",
+      userId: "user-1",
+    });
+    expect(
+      (await forViewer({ deviceId: "3f1c8a4e-1d2b-4c3a-9e5f-6a7b8c9d0e1f", kind: "device" }))
+        .principal,
+    ).toEqual({ deviceId: "3f1c8a4e-1d2b-4c3a-9e5f-6a7b8c9d0e1f", kind: "device" });
+  });
 
-    expect(bootstrap).toEqual({ principal: { kind: "anonymous" }, status: "signed-out" });
-    expect(fetch).toHaveBeenCalledTimes(1);
+  it("refuses a descriptor that claims an anonymous or malformed viewer", async () => {
+    // A `restricted` display permission admits no anonymous principal, so a server saying it
+    // authorized one is a protocol violation rather than a state to render.
+    for (const viewer of [
+      { kind: "anonymous" },
+      { kind: "device" },
+      { kind: "authenticated" },
+      { deviceId: "", kind: "device" },
+      { kind: "device", userId: "user-1" },
+    ]) {
+      expect(() => parseHostModuleDisplay({ ...displayPayload(), viewer })).toThrowError(
+        expect.objectContaining({ code: "HOST_RESPONSE_INVALID" }),
+      );
+    }
   });
 
   it("distinguishes denied, unavailable, unauthenticated, and infrastructure failures safely", async () => {

surfaces/shell/tests/host-app.test.tsx

@@ -443,6 +443,8 @@ describe("Ekklesia shell — browser authentication", () => {
       "/api/auth/sign-in/email",
       "/api/v1/principal",
       "/api/v1/dashboard/navigation",
+      // The host-owned device panel loads with the rest of the shell for an administrator.
+      "/api/v1/devices",
     ]);
   });
 

surfaces/shell/tests/modularity.test.ts

@@ -215,8 +215,17 @@ describe("the display host is a separate generic browser bundle", () => {
   });
 
   it("knows only its host route resources, with no Dashboard application or transport coupling", () => {
-    expect(bundle).toContain('"/api/v1/principal"');
     expect(bundle).toContain('"/api/v1/module-displays"');
+    // Pairing is a display concern and lives here; the Dashboard bundle has its own management UI.
+    expect(bundle).toContain('"/api/v1/device-pairing/requests"');
+    expect(bundle).toContain('"/api/v1/device-pairing/claims"');
+    // And the display deliberately never asks the *human* principal endpoint: a paired device is
+    // anonymous to it, so consulting it would report every display in the building as signed out
+    // (ADR 0036). The descriptor reports the viewer instead.
+    expect(bundle).not.toContain('"/api/v1/principal"');
+    // A display never approves, lists, or revokes a device — that is the administrator's surface.
+    expect(bundle).not.toContain('"/api/v1/device-pairing/approvals"');
+    expect(bundle).not.toContain('"/api/v1/devices"');
     expect(bundle).not.toContain('"/api/v1/dashboard/navigation"');
     expect(bundle).not.toContain('"/api/auth/sign-in/email"');
     expect(bundle).not.toContain('"/api/auth/sign-out"');