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

apps/api/src/app.ts

@@ -10,6 +10,7 @@ import type {
   PermissionRegistry,
 } from "@ekklesia/core/authorization";
 import type { DashboardStore } from "@ekklesia/core/dashboard";
+import type { DeviceStore } from "@ekklesia/core/devices";
 import { type EkklesiaIdentityRuntime, IdentityRuntimeError } from "@ekklesia/core/identity";
 import type {
   DiscoveredModule,
@@ -27,6 +28,7 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { AUTH_REQUEST_MAX_BODY_BYTES, platformBodyLimit } from "./body-limits.js";
 import { createDashboardRoutes } from "./dashboard-routes.js";
+import { createDeviceRoutes } from "./device-routes.js";
 import type { DisplayHostAssets } from "./display-host-assets.js";
 import { createGrantsRoutes } from "./grants-routes.js";
 import { createModuleConfigurationRoutes } from "./module-configuration-routes.js";
@@ -68,6 +70,17 @@ export interface CreateApiAppOptions {
    * is: a caller that publishes no module UI must say so explicitly with an empty registry, never
    * fall through to an implicit one. See `./module-ui-routes.js`. */
   readonly moduleUi: ModuleUiPublicationRegistry;
+  /**
+   * Managed display devices. Optional so every existing composition — and every test that has no
+   * interest in devices — builds unchanged; when it is absent no pairing route is mounted, no
+   * device cookie is ever read, and a device principal simply cannot come into being.
+   */
+  readonly devices?: {
+    readonly store: DeviceStore;
+    /** Whether the deployment is reached over https, so the device cookies can assert `Secure`
+     * without becoming unusable on a plaintext development origin. */
+    readonly secureCookies: boolean;
+  };
   /** Surface-owned display host assets, read once by production startup. Optional only when the
    * eligible publication registry contains no display entrypoint; route composition rejects an
    * inconsistent display-bearing registry synchronously. */
@@ -369,6 +382,23 @@ export function createApiApp(options: CreateApiAppOptions): Hono {
     ...(options.displayHostAssets ? { assets: options.displayHostAssets } : {}),
   });
 
+  if (options.devices) {
+    // Host-owned device identity. Siblings of `/api/v1/modules/...`, reachable by no module, and
+    // mounted only when the deployment actually composed device support.
+    app.route(
+      "/",
+      createDeviceRoutes({
+        devices: options.devices.store,
+        evaluator: options.authorization.evaluator,
+        moduleUi: options.moduleUi,
+        registry: options.authorization.registry,
+        runtime,
+        secureCookies: options.devices.secureCookies,
+        trustedOrigins: allowedOrigins,
+      }),
+    );
+  }
+
   // Layered deliberately on top of the generic inventory above rather than merged into it: the
   // inventory stays the host-neutral "what is mountable" contract a standalone host could consume,
   // and this adds Ekklesia's own presentation of those same modules. See `./dashboard-routes.js`.