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/tests/authorization-device.test.ts

@@ -0,0 +1,189 @@
+import {
+  ANONYMOUS_PRINCIPAL,
+  createAuthenticatedPrincipal,
+  createDevicePrincipal,
+  parsePermissionId,
+} from "@ekklesia/contracts";
+import { describe, expect, it, vi } from "vitest";
+import { createAuthorizationEvaluator } from "../src/authorization/evaluator.js";
+
+/**
+ * Device authority, decided by the **same** evaluator that decides everything else.
+ *
+ * The point of these tests is mostly negative: a device must not acquire authority from being a
+ * principal, from being paired, from an `authenticated` baseline, or from platform ownership. The
+ * only thing that ever makes a device allowed is an explicit permission granted to that exact
+ * device (ADR 0036).
+ */
+const displayPermission = parsePermissionId("announcements.slideshow.view");
+const otherPermission = parsePermissionId("calendar.display.view");
+const deviceId = "3f1c8a4e-1d2b-4c3a-9e5f-6a7b8c9d0e1f";
+
+function evaluator(options: { readonly devicePermissions?: readonly string[] } = {}) {
+  const granted = new Set(options.devicePermissions ?? []);
+  const hasActivePermission = vi.fn(async (_deviceId: string, permission: string) =>
+    granted.has(permission),
+  );
+  // Deliberately always true: if the evaluator ever consulted these for a device, every assertion
+  // below would flip, which is exactly what must not happen.
+  const isPlatformOwner = vi.fn(async () => true);
+  const hasActiveGrant = vi.fn(async () => true);
+  return {
+    evaluator: createAuthorizationEvaluator({
+      devices: { hasActivePermission } as never,
+      grants: { hasActiveGrant } as never,
+      platformOwners: { isPlatformOwner } as never,
+    }),
+    hasActiveGrant,
+    hasActivePermission,
+    isPlatformOwner,
+  };
+}
+
+describe("device principals go through the ordinary evaluator", () => {
+  it("allows a device holding the exact restricted permission", async () => {
+    const harness = evaluator({ devicePermissions: [displayPermission] });
+
+    await expect(
+      harness.evaluator.authorize({
+        baseline: "restricted",
+        permission: displayPermission,
+        principal: createDevicePrincipal(deviceId),
+      }),
+    ).resolves.toEqual({ allowed: true });
+    expect(harness.hasActivePermission).toHaveBeenCalledWith(deviceId, displayPermission);
+  });
+
+  it("denies a device any permission it was not granted", async () => {
+    const harness = evaluator({ devicePermissions: [displayPermission] });
+
+    // Pairing a screen for one display is not authority over another module's.
+    await expect(
+      harness.evaluator.authorize({
+        baseline: "restricted",
+        permission: otherPermission,
+        principal: createDevicePrincipal(deviceId),
+      }),
+    ).resolves.toEqual({ allowed: false });
+  });
+
+  it("never satisfies an authenticated baseline, however many permissions it holds", async () => {
+    const harness = evaluator({ devicePermissions: [displayPermission] });
+
+    // "A person is signed in" is not true of a television. Every route that settles for the
+    // `authenticated` baseline — the module UI inventory among them — stays closed.
+    await expect(
+      harness.evaluator.authorize({
+        baseline: "authenticated",
+        permission: displayPermission,
+        principal: createDevicePrincipal(deviceId),
+      }),
+    ).resolves.toEqual({ allowed: false });
+    expect(harness.hasActivePermission).not.toHaveBeenCalled();
+  });
+
+  it("never consults platform ownership or user grants for a device", async () => {
+    const harness = evaluator();
+
+    await expect(
+      harness.evaluator.authorize({
+        baseline: "restricted",
+        permission: displayPermission,
+        principal: createDevicePrincipal(deviceId),
+      }),
+    ).resolves.toEqual({ allowed: false });
+
+    // Both ports would have answered "yes". A device is denied anyway, because neither is a path a
+    // device can reach — there is no device that is a platform owner.
+    expect(harness.isPlatformOwner).not.toHaveBeenCalled();
+    expect(harness.hasActiveGrant).not.toHaveBeenCalled();
+  });
+
+  it("denies every device when the deployment composed no device support at all", async () => {
+    const withoutDevices = createAuthorizationEvaluator({
+      grants: { hasActiveGrant: async () => true } as never,
+      platformOwners: { isPlatformOwner: async () => true } as never,
+    });
+
+    await expect(
+      withoutDevices.authorize({
+        baseline: "restricted",
+        permission: displayPermission,
+        principal: createDevicePrincipal(deviceId),
+      }),
+    ).resolves.toEqual({ allowed: false });
+  });
+
+  it("denies a scoped check for a device rather than treating it as unscoped", async () => {
+    const harness = evaluator({ devicePermissions: [displayPermission] });
+
+    await expect(
+      harness.evaluator.authorize({
+        baseline: "restricted",
+        permission: displayPermission,
+        principal: createDevicePrincipal(deviceId),
+        scope: "event-1",
+      }),
+    ).resolves.toEqual({ allowed: false });
+  });
+
+  it("still allows a device through a public baseline, like any other principal", async () => {
+    const harness = evaluator();
+
+    await expect(
+      harness.evaluator.authorize({
+        baseline: "public",
+        permission: displayPermission,
+        principal: createDevicePrincipal(deviceId),
+      }),
+    ).resolves.toEqual({ allowed: true });
+  });
+
+  it("leaves human and anonymous decisions exactly as they were", async () => {
+    const harness = evaluator();
+
+    await expect(
+      harness.evaluator.authorize({
+        baseline: "restricted",
+        permission: displayPermission,
+        principal: createAuthenticatedPrincipal("user-1"),
+      }),
+    ).resolves.toEqual({ allowed: true });
+    await expect(
+      harness.evaluator.authorize({
+        baseline: "restricted",
+        permission: displayPermission,
+        principal: ANONYMOUS_PRINCIPAL,
+      }),
+    ).resolves.toEqual({ allowed: false });
+    await expect(
+      harness.evaluator.authorize({
+        baseline: "authenticated",
+        permission: displayPermission,
+        principal: createAuthenticatedPrincipal("user-1"),
+      }),
+    ).resolves.toEqual({ allowed: true });
+  });
+
+  it("propagates a device lookup failure rather than reporting it as denied", async () => {
+    const failing = createAuthorizationEvaluator({
+      devices: {
+        hasActivePermission: async () => {
+          throw new Error("database unavailable");
+        },
+      } as never,
+      grants: { hasActiveGrant: async () => false } as never,
+      platformOwners: { isPlatformOwner: async () => false } as never,
+    });
+
+    // A caller must never be told "no permission" when the true answer is "could not be
+    // determined", exactly as for a human.
+    await expect(
+      failing.authorize({
+        baseline: "restricted",
+        permission: displayPermission,
+        principal: createDevicePrincipal(deviceId),
+      }),
+    ).rejects.toMatchObject({ code: "AUTHORIZATION_EVALUATION_FAILED" });
+  });
+});

core/tests/authorization-permissions.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import {
   CORE_AUTHORIZATION_GRANTS_MANAGE,
   CORE_DASHBOARD_NAVIGATION_MANAGE,
+  CORE_DEVICES_MANAGE,
   CORE_MODULES_CONFIGURATION_MANAGE,
   CORE_MODULES_LIFECYCLE_MANAGE,
   CORE_MODULES_UI_READ,
@@ -132,13 +133,14 @@ describe("CORE_PERMISSION_REGISTRY", () => {
     expect(CORE_MODULES_CONFIGURATION_MANAGE).not.toBe(CORE_MODULES_LIFECYCLE_MANAGE);
   });
 
-  it("contains exactly these five permissions and no others", () => {
+  it("contains exactly these six permissions and no others", () => {
     expect(CORE_PERMISSION_REGISTRY.declarations.map((declaration) => declaration.id)).toEqual([
       CORE_AUTHORIZATION_GRANTS_MANAGE,
       CORE_MODULES_UI_READ,
       CORE_DASHBOARD_NAVIGATION_MANAGE,
       CORE_MODULES_LIFECYCLE_MANAGE,
       CORE_MODULES_CONFIGURATION_MANAGE,
+      CORE_DEVICES_MANAGE,
     ]);
   });
 });
@@ -171,6 +173,11 @@ describe("CORE_PERMISSION_DECLARATIONS", () => {
         description: "Read and change an installed module's own configuration values.",
         id: CORE_MODULES_CONFIGURATION_MANAGE,
       },
+      {
+        baseline: "restricted",
+        description: "Approve display device pairing, list paired devices, and revoke a device.",
+        id: CORE_DEVICES_MANAGE,
+      },
     ]);
     expect(Object.isFrozen(CORE_PERMISSION_DECLARATIONS)).toBe(true);
     for (const declaration of CORE_PERMISSION_DECLARATIONS) {

core/tests/authorization-store.integration.ts

@@ -176,6 +176,7 @@ async function applyCoreMigrations(url: string): Promise<void> {
       "core:0003_dashboard_navigation_tables",
       "core:0004_module_lifecycle_state",
       "core:0005_module_configuration",
+      "core:0006_device_identity",
     ]);
     await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
   } finally {
@@ -228,6 +229,11 @@ describe.sequential("live Core authorization store", () => {
       "ekklesia_core_authorization_audit",
       "ekklesia_core_dashboard_group",
       "ekklesia_core_dashboard_placement",
+      // Device identity is Core's, and deliberately its own tables rather than rows smuggled into
+      // the user or grant tables (ADR 0036).
+      "ekklesia_core_device",
+      "ekklesia_core_device_pairing_request",
+      "ekklesia_core_device_permission",
       "ekklesia_core_grant",
       "ekklesia_core_migrations",
       "ekklesia_core_module_configuration",

core/tests/dashboard-store.integration.ts

@@ -175,6 +175,7 @@ async function applyCoreMigrations(url: string): Promise<void> {
       "core:0003_dashboard_navigation_tables",
       "core:0004_module_lifecycle_state",
       "core:0005_module_configuration",
+      "core:0006_device_identity",
     ]);
     await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
   } finally {

core/tests/doctor-report.test.ts

@@ -87,7 +87,7 @@ Modules
   ✓ Dependency graph valid
     Dependency order is empty.
   ✓ Permission registry composed
-    5 permissions registered
+    6 permissions registered
   ○ Module lifecycle skipped
     DATABASE_URL is not configured.
   ○ Module configuration skipped

core/tests/module-configuration-store.integration.ts

@@ -3,8 +3,15 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseModuleManifest } from "@ekklesia/contracts";
 import { Client, type QueryResultRow } from "pg";
 import { afterAll, describe, expect, it } from "vitest";
+import { createValidatedPostgresPool } from "../src/database/index.js";
+import {
+  applyModuleMigrations,
+  createPostgresMigrationDatabase,
+  discoverAllMigrations,
+} from "../src/migrations/index.js";
 import {
   createModuleConfigurationStore,
   createModuleConfigurationView,
@@ -12,13 +19,6 @@ import {
   ModuleConfigurationStoreError,
   resolveModuleConfigurationFor,
 } from "../src/modules/index.js";
-import { parseModuleManifest } from "@ekklesia/contracts";
-import { createValidatedPostgresPool } from "../src/database/index.js";
-import {
-  applyModuleMigrations,
-  createPostgresMigrationDatabase,
-  discoverAllMigrations,
-} from "../src/migrations/index.js";
 
 /**
  * The module configuration store against real PostgreSQL.
@@ -177,6 +177,7 @@ async function applyCoreMigrations(url: string): Promise<void> {
       "core:0003_dashboard_navigation_tables",
       "core:0004_module_lifecycle_state",
       "core:0005_module_configuration",
+      "core:0006_device_identity",
     ]);
     await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
   } finally {

core/tests/module-lifecycle-store.integration.ts

@@ -3,8 +3,16 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseModuleManifest } from "@ekklesia/contracts";
 import { Client, type QueryResultRow } from "pg";
 import { afterAll, describe, expect, it } from "vitest";
+import { createValidatedPostgresPool } from "../src/database/index.js";
+import {
+  applyModuleMigrations,
+  createPostgresMigrationDatabase,
+  discoverAllMigrations,
+} from "../src/migrations/index.js";
+import type { DiscoveredModule } from "../src/modules/discovery.js";
 import {
   createModuleLifecycleStore,
   createModuleLifecycleView,
@@ -12,14 +20,6 @@ import {
   ModuleLifecycleStoreError,
   resolveModuleEligibility,
 } from "../src/modules/index.js";
-import { parseModuleManifest } from "@ekklesia/contracts";
-import type { DiscoveredModule } from "../src/modules/discovery.js";
-import { createValidatedPostgresPool } from "../src/database/index.js";
-import {
-  applyModuleMigrations,
-  createPostgresMigrationDatabase,
-  discoverAllMigrations,
-} from "../src/migrations/index.js";
 
 /**
  * The module lifecycle configuration store against real PostgreSQL.
@@ -180,6 +180,7 @@ async function applyCoreMigrations(url: string): Promise<void> {
       "core:0003_dashboard_navigation_tables",
       "core:0004_module_lifecycle_state",
       "core:0005_module_configuration",
+      "core:0006_device_identity",
     ]);
     await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
   } finally {

core/tests/module-permissions.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import {
   CORE_AUTHORIZATION_GRANTS_MANAGE,
   CORE_DASHBOARD_NAVIGATION_MANAGE,
+  CORE_DEVICES_MANAGE,
   CORE_MODULES_CONFIGURATION_MANAGE,
   CORE_MODULES_LIFECYCLE_MANAGE,
   CORE_MODULES_UI_READ,
@@ -74,7 +75,7 @@ describe("composePlatformPermissionRegistry", () => {
     expect(registry.has(CORE_MODULES_LIFECYCLE_MANAGE)).toBe(true);
     expect(registry.has(CORE_MODULES_CONFIGURATION_MANAGE)).toBe(true);
     // Core's own five declarations plus one from each module.
-    expect(registry.declarations).toHaveLength(7);
+    expect(registry.declarations).toHaveLength(8);
   });
 
   it("preserves deterministic order: Core first, then modules in the supplied order, then declarations in manifest order", () => {
@@ -94,6 +95,7 @@ describe("composePlatformPermissionRegistry", () => {
       CORE_DASHBOARD_NAVIGATION_MANAGE,
       CORE_MODULES_LIFECYCLE_MANAGE,
       CORE_MODULES_CONFIGURATION_MANAGE,
+      CORE_DEVICES_MANAGE,
       "calendar.events.read",
       "calendar.events.write",
       "people.directory.read",