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/devices/schema.ts

@@ -0,0 +1,168 @@
+import { relations, sql } from "drizzle-orm";
+import { check, index, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { ekklesiaCoreUser } from "../identity/schema.js";
+
+/**
+ * Core-owned device identity: paired display devices, the permissions granted to them, and the
+ * short-lived pairing requests that create them (ADR 0036).
+ *
+ * **Devices are not users.** There is deliberately no foreign key from a device to
+ * `ekklesia_core_user`, and no device row ever appears in the identity tables: a device is its own
+ * principal class with its own credential and its own explicit permissions. The only reference to a
+ * user here is *who approved a pairing*, which is audit information about a person's action, not a
+ * device's identity.
+ *
+ * Device permissions live in their own table rather than in `ekklesia_core_grant`. That table's
+ * `user_id` is a non-null foreign key into the user table, and generalizing it to a polymorphic
+ * subject would rewrite the platform's central authorization record — and its relationship-derived
+ * grants, audit semantics, and indexes — to serve one narrow case. A separate table keeps the
+ * device story additive and auditable while the evaluator remains the single place any decision is
+ * made (`core/src/authorization/evaluator.ts`).
+ */
+
+export const ekklesiaCoreDevice = pgTable(
+  "ekklesia_core_device",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    /** Assigned by the approving administrator, never self-asserted by the unpaired device. */
+    name: text("name").notNull(),
+    /**
+     * SHA-256 of the device's credential, hex encoded. The raw credential exists only in the
+     * response that sets the cookie and in the device's own cookie jar; it is never stored, logged,
+     * or recoverable from this row. A fast hash is right here — unlike a password, the credential
+     * is 256 bits of CSPRNG output, so there is nothing to brute-force and a slow KDF would only
+     * add latency to every request a display makes.
+     */
+    credentialHash: text("credential_hash").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    createdByUserId: text("created_by_user_id").references(() => ekklesiaCoreUser.id, {
+      onDelete: "set null",
+    }),
+    /** Coarse operational signal, throttled by the resolver; never an identity input. */
+    lastSeenAt: timestamp("last_seen_at", { withTimezone: true }),
+    /** Server-side authority. Revocation is this column, never the deletion of a remote cookie. */
+    revokedAt: timestamp("revoked_at", { withTimezone: true }),
+    revokedByUserId: text("revoked_by_user_id").references(() => ekklesiaCoreUser.id, {
+      onDelete: "set null",
+    }),
+  },
+  (table) => [
+    // Every credential is distinct, and the resolver looks a presented credential up by this exact
+    // hash — an index probe rather than a scan-and-compare, so there is no comparison to time.
+    uniqueIndex("ekklesia_core_device_credential_hash_idx").on(table.credentialHash),
+    index("ekklesia_core_device_revoked_idx").on(table.revokedAt),
+    check("ekklesia_core_device_name_check", sql`length(${table.name}) between 1 and 128`),
+    check("ekklesia_core_device_credential_hash_check", sql`length(${table.credentialHash}) = 64`),
+  ],
+);
+
+export const ekklesiaCoreDevicePermission = pgTable(
+  "ekklesia_core_device_permission",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    deviceId: uuid("device_id")
+      .notNull()
+      .references(() => ekklesiaCoreDevice.id, { onDelete: "cascade" }),
+    permissionId: text("permission_id").notNull(),
+    grantedAt: timestamp("granted_at", { withTimezone: true }).defaultNow().notNull(),
+    grantedByUserId: text("granted_by_user_id").references(() => ekklesiaCoreUser.id, {
+      onDelete: "set null",
+    }),
+    revokedAt: timestamp("revoked_at", { withTimezone: true }),
+  },
+  (table) => [
+    index("ekklesia_core_device_permission_lookup_idx").on(table.deviceId, table.permissionId),
+    check(
+      "ekklesia_core_device_permission_id_check",
+      sql`length(${table.permissionId}) between 1 and 128`,
+    ),
+  ],
+);
+
+/**
+ * One in-flight pairing attempt.
+ *
+ * Three distinct secrets meet here and must not be confused:
+ *
+ * - `code` is the short digits shown on the screen. It is **public by design** — it is displayed on
+ *   a television in a hallway — and it identifies the request to an administrator. It is stored in
+ *   the clear because it is not a secret and because an administrator looks a request up by it.
+ * - `claimSecretHash` is SHA-256 of a 256-bit secret held only in the requesting browser's
+ *   HttpOnly cookie. It answers "are you the device that asked?", which the code cannot: anyone who
+ *   can *see* the screen knows the code, so a flow that issued a credential on the strength of the
+ *   code alone would hand the device's identity to whoever read it off the wall.
+ * - The device credential does not exist yet, and is created only when the approved request is
+ *   consumed by the browser holding the claim secret.
+ *
+ * `expiresAt` is the only expiry authority; there is no `expired` state to write and therefore no
+ * sweeper that must run for correctness. `state` records only what someone *did* — nothing here
+ * ages a row on its own.
+ */
+export const ekklesiaCoreDevicePairingRequest = pgTable(
+  "ekklesia_core_device_pairing_request",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    code: text("code").notNull(),
+    claimSecretHash: text("claim_secret_hash").notNull(),
+    /** The display the device actually navigated to, resolved server-side from the publication
+     * registry. Never a value the browser chose. */
+    moduleId: text("module_id").notNull(),
+    /** Derived from that module's validated display declaration, so a device cannot ask for a
+     * permission of its choosing. */
+    permissionId: text("permission_id").notNull(),
+    state: text("state").notNull().default("pending"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    /** Chosen by the approving administrator; carried here until the request is consumed and the
+     * device row is created. */
+    deviceName: text("device_name"),
+    approvedAt: timestamp("approved_at", { withTimezone: true }),
+    approvedByUserId: text("approved_by_user_id").references(() => ekklesiaCoreUser.id, {
+      onDelete: "set null",
+    }),
+    consumedAt: timestamp("consumed_at", { withTimezone: true }),
+    deviceId: uuid("device_id").references(() => ekklesiaCoreDevice.id, { onDelete: "set null" }),
+  },
+  (table) => [
+    // At most one live request may hold a given code, which is what makes a short code safe to
+    // generate: a collision is refused by PostgreSQL rather than resolved by whichever row a query
+    // happened to return first. Consumed rows keep their code without blocking reuse later.
+    uniqueIndex("ekklesia_core_device_pairing_code_idx")
+      .on(table.code)
+      .where(sql`${table.state} <> 'consumed'`),
+    index("ekklesia_core_device_pairing_claim_idx").on(table.claimSecretHash),
+    check("ekklesia_core_device_pairing_code_check", sql`${table.code} ~ '^[0-9]{6}$'`),
+    check(
+      "ekklesia_core_device_pairing_claim_hash_check",
+      sql`length(${table.claimSecretHash}) = 64`,
+    ),
+    check(
+      "ekklesia_core_device_pairing_state_check",
+      sql`${table.state} in ('pending', 'approved', 'consumed')`,
+    ),
+  ],
+);
+
+export const ekklesiaCoreDeviceRelations = relations(ekklesiaCoreDevice, ({ many }) => ({
+  permissions: many(ekklesiaCoreDevicePermission),
+}));
+
+export const ekklesiaCoreDevicePermissionRelations = relations(
+  ekklesiaCoreDevicePermission,
+  ({ one }) => ({
+    device: one(ekklesiaCoreDevice, {
+      fields: [ekklesiaCoreDevicePermission.deviceId],
+      references: [ekklesiaCoreDevice.id],
+    }),
+  }),
+);
+
+/** The device tables, bundled exactly like `authorizationSchema`, so a Drizzle view over the
+ * platform's shared pool is typed against them. */
+export const deviceSchema = {
+  ekklesiaCoreDevice,
+  ekklesiaCoreDevicePairingRequest,
+  ekklesiaCoreDevicePermission,
+  ekklesiaCoreDevicePermissionRelations,
+  ekklesiaCoreDeviceRelations,
+};