Ekklesia/core/src/devices/schema.ts

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,
};