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

packages/contracts/src/identity.ts

@@ -22,6 +22,34 @@ export function safeParseEkklesiaUserId(input: unknown): z.ZodSafeParseResult<Ek
   return ekklesiaUserIdSchema.safeParse(input);
 }
 
+/**
+ * A managed display device: a TV, signage player, or confidence monitor that the platform paired
+ * and can revoke.
+ *
+ * It is deliberately **not** a user. A device has no email, no password, no session that a person
+ * signs into, and no row in the user table — representing one as a fake user would make every
+ * "is this a person?" question in the platform unanswerable, and would quietly hand a screen in a
+ * hallway whatever a signed-in human is allowed to do.
+ *
+ * A device principal carries only the permissions explicitly granted to that device. It satisfies
+ * no `authenticated` baseline: "unattended screen in the foyer" is not "a person is signed in",
+ * and every route gated only by "someone is logged in" would otherwise open to it (ADR 0036).
+ */
+export const ekklesiaDeviceIdSchema = z
+  .string()
+  .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u)
+  .brand<"EkklesiaDeviceId">();
+
+export type EkklesiaDeviceId = z.infer<typeof ekklesiaDeviceIdSchema>;
+
+export function parseEkklesiaDeviceId(input: unknown): EkklesiaDeviceId {
+  return ekklesiaDeviceIdSchema.parse(input);
+}
+
+export function safeParseEkklesiaDeviceId(input: unknown): z.ZodSafeParseResult<EkklesiaDeviceId> {
+  return ekklesiaDeviceIdSchema.safeParse(input);
+}
+
 export interface EkklesiaAnonymousPrincipal {
   readonly kind: "anonymous";
 }
@@ -31,7 +59,20 @@ export interface EkklesiaAuthenticatedPrincipal {
   readonly userId: EkklesiaUserId;
 }
 
-export type EkklesiaPrincipal = EkklesiaAnonymousPrincipal | EkklesiaAuthenticatedPrincipal;
+export interface EkklesiaDevicePrincipal {
+  readonly kind: "device";
+  readonly deviceId: EkklesiaDeviceId;
+}
+
+/**
+ * The three principal classes Ekklesia recognizes. They are deliberately a closed union rather than
+ * "authenticated or not": code that means *a person* must be able to say so, and code that merely
+ * needs *some* caller must not accidentally accept a device.
+ */
+export type EkklesiaPrincipal =
+  | EkklesiaAnonymousPrincipal
+  | EkklesiaAuthenticatedPrincipal
+  | EkklesiaDevicePrincipal;
 
 export const ANONYMOUS_PRINCIPAL: EkklesiaAnonymousPrincipal = Object.freeze({
   kind: "anonymous",
@@ -44,14 +85,34 @@ export function createAuthenticatedPrincipal(userId: unknown): EkklesiaAuthentic
   });
 }
 
+export function createDevicePrincipal(deviceId: unknown): EkklesiaDevicePrincipal {
+  return Object.freeze({
+    deviceId: parseEkklesiaDeviceId(deviceId),
+    kind: "device",
+  });
+}
+
 export function isAnonymousPrincipal(
   principal: EkklesiaPrincipal,
 ): principal is EkklesiaAnonymousPrincipal {
   return principal.kind === "anonymous";
 }
 
+/**
+ * Whether this principal is a signed-in **person**.
+ *
+ * A device principal deliberately returns `false`. Every existing caller of this predicate means
+ * "a human is authenticated here" — the Dashboard shell, the `authenticated` permission baseline,
+ * the grants API — and each of them would be wrong about a screen on a wall.
+ */
 export function isAuthenticatedPrincipal(
   principal: EkklesiaPrincipal,
 ): principal is EkklesiaAuthenticatedPrincipal {
   return principal.kind === "authenticated";
 }
+
+export function isDevicePrincipal(
+  principal: EkklesiaPrincipal,
+): principal is EkklesiaDevicePrincipal {
+  return principal.kind === "device";
+}

packages/module-ui-sdk/src/host-context.ts

@@ -29,7 +29,26 @@ export interface ModuleUiAuthenticatedPrincipal {
   readonly userId: string;
 }
 
-export type ModuleUiPrincipal = ModuleUiAnonymousPrincipal | ModuleUiAuthenticatedPrincipal;
+/**
+ * A managed display device — a screen the platform paired, with no person behind it.
+ *
+ * Module UI is told this so it can render honestly: a signage view has nobody to greet, no personal
+ * data to show, and no interaction to invite. It is deliberately *not* an authenticated principal,
+ * because module code that asks "is someone signed in?" must not be told yes about a television.
+ *
+ * There is nothing here about pairing. How a device came to exist is the host's business; a module
+ * receives an identity and its permissions, exactly as it does for a person.
+ */
+export interface ModuleUiDevicePrincipal {
+  readonly kind: "device";
+  /** Opaque to module UI: an identifier to correlate with, never to parse or display verbatim. */
+  readonly deviceId: string;
+}
+
+export type ModuleUiPrincipal =
+  | ModuleUiAnonymousPrincipal
+  | ModuleUiAuthenticatedPrincipal
+  | ModuleUiDevicePrincipal;
 
 /**
  * Everything a host hands a module's UI, and the complete list of what module UI may assume exists.