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

core/src/authorization/evaluator.ts

@@ -5,11 +5,16 @@ import {
   type AuthorizationScope,
   type EkklesiaPrincipal,
   isAuthenticatedPrincipal,
+  isDevicePrincipal,
   permissionBaselineSchema,
   safeParseAuthorizationScope,
   safeParsePermissionId,
 } from "@ekklesia/contracts";
-import type { AuthorizationGrantPort, AuthorizationPlatformOwnerPort } from "./ports.js";
+import type {
+  AuthorizationDevicePort,
+  AuthorizationGrantPort,
+  AuthorizationPlatformOwnerPort,
+} from "./ports.js";
 
 export type AuthorizationEvaluationErrorCode = "AUTHORIZATION_EVALUATION_FAILED";
 
@@ -54,6 +59,10 @@ export interface AuthorizationEvaluator {
 export interface CreateAuthorizationEvaluatorOptions {
   readonly grants: AuthorizationGrantPort;
   readonly platformOwners: AuthorizationPlatformOwnerPort;
+  /** Device authority. Optional so every existing caller composes unchanged; when it is absent a
+   * device principal simply has no permissions and is denied, which is the correct answer for a
+   * deployment that has no device support wired at all. */
+  readonly devices?: AuthorizationDevicePort;
   /** Injectable clock so expiration evaluation is deterministic and testable. Defaults to the
    * real wall clock; production composition must leave this unset. */
   readonly now?: () => Date;
@@ -100,17 +109,14 @@ export function createAuthorizationEvaluator(
       }
 
       if (parsedBaseline.data === "authenticated") {
+        // A device deliberately does not satisfy this. The baseline means "a person is signed in",
+        // and every route that settles for it — the module UI inventory, anything a human is
+        // expected to be looking at — would otherwise open to an unattended screen (ADR 0036).
         return isAuthenticatedPrincipal(request.principal)
           ? AUTHORIZATION_ALLOWED
           : AUTHORIZATION_DENIED;
       }
 
-      // parsedBaseline.data === "restricted": requires an authenticated principal AND
-      // (an active matching grant OR platform-owner authority). Baseline alone never satisfies it.
-      if (!isAuthenticatedPrincipal(request.principal)) {
-        return AUTHORIZATION_DENIED;
-      }
-
       let scope: AuthorizationScope | undefined;
       if (request.scope !== undefined) {
         const parsedScope = safeParseAuthorizationScope(request.scope);
@@ -120,6 +126,34 @@ export function createAuthorizationEvaluator(
         scope = parsedScope.data;
       }
 
+      // A device satisfies `restricted` only by holding that exact permission, and by no other
+      // route: there is no owner check here, no baseline that stands in for a grant, and no branch
+      // that returns `allowed` before this lookup. "Paired" is not authority — a device that was
+      // paired for one display has nothing else.
+      if (isDevicePrincipal(request.principal)) {
+        if (!options.devices || scope !== undefined) {
+          // A scoped check has no device meaning yet; denying is the honest answer rather than
+          // silently treating it as unscoped.
+          return AUTHORIZATION_DENIED;
+        }
+        try {
+          return (await options.devices.hasActivePermission(
+            request.principal.deviceId,
+            parsedPermission.data,
+          ))
+            ? AUTHORIZATION_ALLOWED
+            : AUTHORIZATION_DENIED;
+        } catch {
+          throw new AuthorizationEvaluationError();
+        }
+      }
+
+      // parsedBaseline.data === "restricted": requires an authenticated principal AND
+      // (an active matching grant OR platform-owner authority). Baseline alone never satisfies it.
+      if (!isAuthenticatedPrincipal(request.principal)) {
+        return AUTHORIZATION_DENIED;
+      }
+
       const userId = request.principal.userId;
       let isOwner: boolean;
       let hasGrant: boolean;

core/src/authorization/permissions.ts

@@ -152,6 +152,23 @@ export const CORE_MODULES_CONFIGURATION_MANAGE: PermissionId = parsePermissionId
   "core.modules.configuration.manage",
 );
 
+/**
+ * Restricted, and deliberately a **platform** permission rather than a module's.
+ *
+ * A device is an identity the platform issues, so deciding that a screen in the foyer may exist —
+ * approving its pairing, seeing what has been paired, and taking it away again — is authority over
+ * Ekklesia itself, not over the module whose display happens to be shown. Letting a module declare
+ * or gate it would mean whoever administers a slideshow could mint credentials that outlive it.
+ *
+ * It gates approval, listing, and revocation together. Splitting "see the paired devices" from
+ * "revoke one" would be ceremony: the same person is trusted with both, and a reader who cannot act
+ * on what they see is not a role anyone has asked for (ADR 0027's reasoning, applied again).
+ *
+ * Holding it confers **no** authority inside any module and no ability to read a device credential
+ * — none is stored in a recoverable form, so there is no code path that could serve one (ADR 0036).
+ */
+export const CORE_DEVICES_MANAGE: PermissionId = parsePermissionId("core.devices.manage");
+
 /**
  * Core's own declarations, exported in deeply immutable form so a trusted composer (the module
  * integration layer, `core/src/modules/permissions.ts`) can build one combined registry from
@@ -185,6 +202,11 @@ export const CORE_PERMISSION_DECLARATIONS: readonly PermissionDeclaration[] = Ob
     description: "Read and change an installed module's own configuration values.",
     id: CORE_MODULES_CONFIGURATION_MANAGE,
   }),
+  Object.freeze({
+    baseline: "restricted" as const,
+    description: "Approve display device pairing, list paired devices, and revoke a device.",
+    id: CORE_DEVICES_MANAGE,
+  }),
 ]);
 
 /**

core/src/authorization/ports.ts

@@ -1,4 +1,9 @@
-import type { AuthorizationScope, EkklesiaUserId, PermissionId } from "@ekklesia/contracts";
+import type {
+  AuthorizationScope,
+  EkklesiaDeviceId,
+  EkklesiaUserId,
+  PermissionId,
+} from "@ekklesia/contracts";
 
 export interface ActiveGrantQuery {
   readonly userId: EkklesiaUserId;
@@ -26,3 +31,17 @@ export interface AuthorizationGrantPort {
 export interface AuthorizationPlatformOwnerPort {
   isPlatformOwner(userId: EkklesiaUserId): Promise<boolean>;
 }
+
+/**
+ * The evaluator's only read dependency for **device** authority.
+ *
+ * Separate from `AuthorizationGrantPort` because the two answer questions about different kinds of
+ * subject, not because devices are a special case in the decision: `authorize` consults exactly one
+ * of them per call, by principal kind, and neither can be reached without going through it.
+ *
+ * There is deliberately no device counterpart to `AuthorizationPlatformOwnerPort`. A device is
+ * never a platform owner, so there is no port that could accidentally say it was.
+ */
+export interface AuthorizationDevicePort {
+  hasActivePermission(deviceId: EkklesiaDeviceId, permission: PermissionId): Promise<boolean>;
+}