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/device-principal.ts

@@ -0,0 +1,94 @@
+import { createDevicePrincipal, type EkklesiaPrincipal } from "@ekklesia/contracts";
+import type { DeviceStore } from "@ekklesia/core/devices";
+import { DEVICE_LAST_SEEN_THROTTLE_MS } from "@ekklesia/core/devices";
+import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
+import { DEVICE_SESSION_COOKIE } from "./device-routes.js";
+
+/**
+ * Extends principal resolution with managed devices, without touching how a *person* is resolved
+ * (ADR 0036).
+ *
+ * Composition rather than modification is deliberate. Core's identity runtime is the Better Auth
+ * boundary and knows only about human sessions; teaching it about devices would put two unrelated
+ * credential systems behind one implementation and make "which one answered?" an internal detail.
+ * Wrapping keeps Better Auth's behaviour byte-for-byte unchanged — including that an infrastructure
+ * failure still throws rather than degrading to anonymous — and adds exactly one fallback.
+ *
+ * **A human session always wins.** If Better Auth resolves a person, that is the answer and the
+ * device cookie is never even read. This matters because a browser can hold both: an administrator
+ * who opens a display page on their own laptop after pairing it stays themself, and no device
+ * cookie can dilute or replace a human identity.
+ *
+ * Because every gate in the platform — the display page, the descriptor, module HTTP routes,
+ * realtime — resolves principals through this one function, a device becomes a principal in exactly
+ * one place, and every authorization decision about it is still made by the ordinary evaluator.
+ */
+export interface DevicePrincipalOptions {
+  readonly runtime: EkklesiaIdentityRuntime;
+  readonly devices: DeviceStore;
+  readonly now?: () => Date;
+}
+
+/** RFC 6265 `cookie-string` parsing, matching how Core's own session-cookie detection reads a
+ * header: split on `;`, take the text before the first `=` as the name, compare whole names
+ * exactly. Never a substring test, so `x_ekklesia_device_session` is correctly not a match. */
+function readCookie(headers: Headers, name: string): string | undefined {
+  const header = headers.get("cookie");
+  if (header === null) {
+    return undefined;
+  }
+  for (const pair of header.split(";")) {
+    const separator = pair.indexOf("=");
+    if (separator === -1) {
+      continue;
+    }
+    if (pair.slice(0, separator).trim() === name) {
+      const value = pair.slice(separator + 1).trim();
+      return value.length === 0 ? undefined : value;
+    }
+  }
+  return undefined;
+}
+
+export function withDevicePrincipals(options: DevicePrincipalOptions): EkklesiaIdentityRuntime {
+  const now = options.now ?? ((): Date => new Date());
+
+  return Object.freeze({
+    handleAuthRequest: (request: Request): Promise<Response> =>
+      options.runtime.handleAuthRequest(request),
+
+    async resolvePrincipal(headers: Headers): Promise<EkklesiaPrincipal> {
+      // Unchanged, including its failure behaviour: a genuine outage still throws rather than
+      // silently letting a device credential answer a question about a person.
+      const human = await options.runtime.resolvePrincipal(headers);
+      if (human.kind !== "anonymous") {
+        return human;
+      }
+
+      const credential = readCookie(headers, DEVICE_SESSION_COOKIE);
+      if (credential === undefined) {
+        return human;
+      }
+
+      const at = now();
+      const device = await options.devices.resolveCredential(credential, at);
+      if (!device) {
+        // A revoked, expired, or simply wrong credential is anonymous — never an error the caller
+        // could use to tell those three apart.
+        return human;
+      }
+
+      // Throttled here as well as in SQL: the common case must not even issue a statement, or a
+      // display polling realtime would turn an operational nicety into continuous write traffic.
+      const lastSeen = device.lastSeenAt;
+      if (
+        lastSeen === undefined ||
+        at.getTime() - lastSeen.getTime() >= DEVICE_LAST_SEEN_THROTTLE_MS
+      ) {
+        await options.devices.touchLastSeen(device.deviceId, at).catch(() => undefined);
+      }
+
+      return createDevicePrincipal(device.deviceId);
+    },
+  });
+}