@facilis.dev/auth 0.0.0-stage → 0.1.1

package/src/tables.ts

@@ -0,0 +1,214 @@
+import { sql } from "drizzle-orm";
+import {
+  boolean,
+  index,
+  pgPolicy,
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+  type PgColumn,
+  type PgPolicy,
+} from "drizzle-orm/pg-core";
+
+import { rlsForTable, tenantColumn } from "@facilis.dev/db";
+
+const usersRls = rlsForTable({ tenantColumn: "tenant_id" });
+
+/**
+ * Auth tables (SPEC §5.3). Access is two-class (D-136): a table with RLS is reachable by the
+ * app role under its policies; a table without RLS is system-only (`facilis_app` has no
+ * privilege on it, only the audited system identity can read or write it).
+ *
+ * `role_permissions` and `roles` are the system-only pair: `role_permissions` is a
+ * projection of facilis.config.ts, written only by migrations/seed and never read at runtime
+ * (permissions come from the config through `expandRoles`). `sessions` and `user_roles` are
+ * app-reachable, so they carry an RLS policy that inherits the parent `users` row's
+ * visibility instead of restating tenant isolation.
+ *
+ * Users carry both policies: restrictive tenant isolation (D-008) AND-ed with a permissive
+ * "tenant scope present" policy, since Postgres denies by default when no permissive policy
+ * applies. Net effect: non-superusers only reach users of the tenant in `app.tenant_id`.
+ */
+export const users = pgTable(
+  "users",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    email: text("email").notNull().unique(),
+    // The registration insert has no session yet; the column takes the deployment tenant
+    // from the policy-scope GUC (D-040). Postgres fills it before the RLS check runs.
+    tenantId: tenantColumn(),
+    passwordHash: text("password_hash"),
+    // Service accounts exist only to back an API client. They have no password and every
+    // login path rejects them, so the flag is a stored fact the session/SSO code can check.
+    isService: boolean("is_service").notNull().default(false),
+    // null means "never verified" (D-156): a password account starts here and only the
+    // single-use link consumed by the verification route sets the timestamp.
+    emailVerifiedAt: timestamp("email_verified_at"),
+    createdAt: timestamp("created_at").defaultNow(),
+  },
+  (table) => [
+    // Canonical identity: emails are stored normalized, and the unique lower(email) index makes
+    // a case variant rejected by the database too, not only by the app (D-150).
+    uniqueIndex("users_email_lower_idx").on(sql`lower(${table.email})`),
+    ...usersRls.policies,
+    pgPolicy("users_tenant_access", {
+      for: "all",
+      using: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+      withCheck: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+  ],
+).enableRLS();
+
+/**
+ * Inherits the parent `users` row's visibility instead of restating it (the D-053 pattern):
+ * a session or role assignment is reachable exactly when the user it points at is visible in
+ * the current tenant scope. This is what keeps the two tables app-reachable — their rows have
+ * no tenant column of their own (D-136).
+ */
+function parentUserAccessPolicy(name: string, column: PgColumn): PgPolicy {
+  const predicate = sql`exists (select 1 from ${users} u where u.id = ${column})`;
+  return pgPolicy(name, { for: "all", using: predicate, withCheck: predicate });
+}
+
+/**
+ * Email verification links (D-156): one active token per user, stored as `sha256(token)`; the raw
+ * link exists only in the delivered email. App-scoped like the other auth tables (D-136), and
+ * reached through the audited system elevation by the verification route, which has no session.
+ */
+const emailVerificationsRls = rlsForTable({ tenantColumn: "tenant_id" });
+
+export const authEmailVerifications = pgTable(
+  "auth_email_verifications",
+  {
+    // sha256(token): a tenant-scoped read of the table cannot be replayed as a verification link.
+    id: text("id").primaryKey(),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    expiresAt: timestamp("expires_at").notNull(),
+    tenantId: tenantColumn(),
+  },
+  (table) => [
+    // One lookup per user for "rotate the outstanding link"; the primary key covers the token.
+    index("auth_email_verifications_user_idx").on(table.userId),
+    ...emailVerificationsRls.policies,
+    pgPolicy("auth_email_verifications_tenant_access", {
+      for: "all",
+      using: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+      withCheck: sql`nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+  ],
+).enableRLS();
+
+export const sessions = pgTable(
+  "sessions",
+  {
+    // sha256(cookie id): the raw credential never reaches the table (D-144).
+    id: text("id").primaryKey(),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id),
+    expiresAt: timestamp("expires_at").notNull(),
+  },
+  (table) => [parentUserAccessPolicy("sessions_user_access", table.userId)],
+).enableRLS();
+
+// System-only (no RLS): seeded by the migration, never read by a route (D-136).
+export const roles = pgTable("roles", {
+  name: text("name").primaryKey(),
+});
+
+export const rolePermissions = pgTable(
+  "role_permissions",
+  {
+    role: text("role")
+      .notNull()
+      .references(() => roles.name),
+    permission: text("permission").notNull(),
+  },
+  (table) => [primaryKey({ columns: [table.role, table.permission] })],
+);
+
+export const userRoles = pgTable(
+  "user_roles",
+  {
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id),
+    role: text("role")
+      .notNull()
+      .references(() => roles.name),
+    assignedBy: uuid("assigned_by"),
+    assignedAt: timestamp("assigned_at").defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.userId, table.role] }),
+    parentUserAccessPolicy("user_roles_user_access", table.userId),
+  ],
+).enableRLS();
+
+/**
+ * Programmatic API clients (V3a). A client is a service user plus a hashed secret and a fixed
+ * role; both new tables are app-scoped through the parent user (D-136), so the RLS boundary
+ * stays the `users` table and a client row is reachable exactly when its service user is.
+ */
+export const apiClients = pgTable(
+  "api_clients",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    clientId: text("client_id").notNull().unique(),
+    // Only the SHA-256 of the secret is stored; the plaintext leaves the process once, in
+    // the createApiClient result, and can never be recovered from the database.
+    secretHash: text("secret_hash").notNull(),
+    name: text("name").notNull(),
+    // The client's fixed role: an issued token carries exactly this role, never the user's
+    // interactive roles (a service account has none worth expanding).
+    role: text("role").notNull(),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id),
+    createdBy: uuid("created_by"),
+    createdAt: timestamp("created_at").defaultNow(),
+    revokedAt: timestamp("revoked_at"),
+    lastUsedAt: timestamp("last_used_at"),
+  },
+  (table) => [parentUserAccessPolicy("api_clients_user_access", table.userId)],
+).enableRLS();
+
+export const apiTokens = pgTable(
+  "api_tokens",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    // Lookup key for a presented bearer token: SHA-256 of the raw value, never the value.
+    tokenHash: text("token_hash").notNull().unique(),
+    clientId: uuid("client_id")
+      .notNull()
+      .references(() => apiClients.id),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id),
+    expiresAt: timestamp("expires_at").notNull(),
+    createdAt: timestamp("created_at").defaultNow(),
+    revokedAt: timestamp("revoked_at"),
+    lastUsedAt: timestamp("last_used_at"),
+  },
+  (table) => [parentUserAccessPolicy("api_tokens_user_access", table.userId)],
+).enableRLS();
+
+export type UserRow = typeof users.$inferSelect;
+export type NewUserRow = typeof users.$inferInsert;
+export type SessionRow = typeof sessions.$inferSelect;
+export type RoleRow = typeof roles.$inferSelect;
+export type RolePermissionRow = typeof rolePermissions.$inferSelect;
+export type UserRoleRow = typeof userRoles.$inferSelect;
+export type ApiClientRow = typeof apiClients.$inferSelect;
+export type ApiTokenRow = typeof apiTokens.$inferSelect;
+export type EmailVerificationRow = typeof authEmailVerifications.$inferSelect;
+export type NewEmailVerificationRow = typeof authEmailVerifications.$inferInsert;
+
+/** Public projection of a user row: the password hash never leaves @facilis.dev/auth. */
+export type AuthUser = Pick<UserRow, "id" | "email" | "tenantId" | "createdAt">;

package/src/test-support.ts

@@ -0,0 +1,149 @@
+import { getTableConfig, type PgTable } from "drizzle-orm/pg-core";
+
+import {
+  applyStatements,
+  createDb,
+  ensureAppRole,
+  policyCreateSql,
+  type FacilisDb,
+} from "@facilis.dev/db";
+
+import { authIdentities, authSsoStates } from "./sso/tables.ts";
+import {
+  apiClients,
+  apiTokens,
+  authEmailVerifications,
+  rolePermissions,
+  roles,
+  sessions,
+  userRoles,
+  users,
+} from "./tables.ts";
+
+/**
+ * Hand-written DDL matching the drizzle tables exactly (no drizzle-kit in CI). Column
+ * names, nullability, defaults, keys and references mirror ./tables.ts.
+ */
+export const AUTH_TABLE_STATEMENTS: readonly string[] = [
+  `CREATE TABLE IF NOT EXISTS users (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    email text NOT NULL UNIQUE,
+    tenant_id uuid NOT NULL DEFAULT nullif(current_setting('app.tenant_id', true), '')::uuid,
+    password_hash text,
+    is_service boolean NOT NULL DEFAULT false,
+    email_verified_at timestamp,
+    created_at timestamp DEFAULT now()
+  )`,
+  `CREATE TABLE IF NOT EXISTS sessions (
+    id text PRIMARY KEY,
+    user_id uuid NOT NULL REFERENCES users(id),
+    expires_at timestamp NOT NULL
+  )`,
+  "CREATE TABLE IF NOT EXISTS roles (name text PRIMARY KEY)",
+  `CREATE TABLE IF NOT EXISTS role_permissions (
+    role text NOT NULL REFERENCES roles(name),
+    permission text NOT NULL,
+    PRIMARY KEY (role, permission)
+  )`,
+  `CREATE TABLE IF NOT EXISTS user_roles (
+    user_id uuid NOT NULL REFERENCES users(id),
+    role text NOT NULL REFERENCES roles(name),
+    assigned_by uuid,
+    assigned_at timestamp DEFAULT now(),
+    PRIMARY KEY (user_id, role)
+  )`,
+  `CREATE TABLE IF NOT EXISTS api_clients (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    client_id text NOT NULL UNIQUE,
+    secret_hash text NOT NULL,
+    name text NOT NULL,
+    role text NOT NULL,
+    user_id uuid NOT NULL REFERENCES users(id),
+    created_by uuid,
+    created_at timestamp DEFAULT now(),
+    revoked_at timestamp,
+    last_used_at timestamp
+  )`,
+  `CREATE TABLE IF NOT EXISTS api_tokens (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    token_hash text NOT NULL UNIQUE,
+    client_id uuid NOT NULL REFERENCES api_clients(id),
+    user_id uuid NOT NULL REFERENCES users(id),
+    expires_at timestamp NOT NULL,
+    created_at timestamp DEFAULT now(),
+    revoked_at timestamp,
+    last_used_at timestamp
+  )`,
+  `CREATE TABLE IF NOT EXISTS auth_identities (
+    provider text NOT NULL,
+    subject text NOT NULL,
+    user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    email text NOT NULL,
+    tenant_id uuid NOT NULL DEFAULT nullif(current_setting('app.tenant_id', true), '')::uuid,
+    created_at timestamp DEFAULT now() NOT NULL,
+    last_login_at timestamp DEFAULT now() NOT NULL,
+    PRIMARY KEY (provider, subject)
+  )`,
+  `CREATE TABLE IF NOT EXISTS auth_sso_states (
+    state text PRIMARY KEY,
+    provider text NOT NULL,
+    nonce text,
+    code_verifier text,
+    request_id text,
+    redirect_to text,
+    created_at timestamp DEFAULT now() NOT NULL,
+    expires_at timestamp NOT NULL,
+    tenant_id uuid NOT NULL DEFAULT nullif(current_setting('app.tenant_id', true), '')::uuid
+  )`,
+  `CREATE TABLE IF NOT EXISTS auth_email_verifications (
+    id text PRIMARY KEY,
+    user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    created_at timestamp DEFAULT now() NOT NULL,
+    expires_at timestamp NOT NULL,
+    tenant_id uuid NOT NULL DEFAULT nullif(current_setting('app.tenant_id', true), '')::uuid
+  )`,
+];
+
+const RLS_TABLES: readonly (readonly [string, PgTable])[] = [
+  ["users", users],
+  ["sessions", sessions],
+  ["roles", roles],
+  ["role_permissions", rolePermissions],
+  ["user_roles", userRoles],
+  ["api_clients", apiClients],
+  ["api_tokens", apiTokens],
+  ["auth_identities", authIdentities],
+  ["auth_sso_states", authSsoStates],
+  ["auth_email_verifications", authEmailVerifications],
+];
+
+/**
+ * RLS wiring derived from the same drizzle tables the DDL mirrors, so a new policy (D-136)
+ * cannot land in the schema and stay out of the test database. Tables without `enableRLS`
+ * (`roles`, `role_permissions`) are system-only and contribute no statement.
+ */
+const AUTH_RLS_STATEMENTS: readonly string[] = RLS_TABLES.flatMap(([name, table]) => {
+  const config = getTableConfig(table);
+  if (!config.enableRLS) return [];
+  const statements = [`ALTER TABLE "${name}" ENABLE ROW LEVEL SECURITY`];
+  for (const policy of config.policies) statements.push(policyCreateSql(name, policy));
+  return statements;
+});
+
+let cachedStatements: readonly string[] | undefined;
+
+function authSchemaStatements(): readonly string[] {
+  cachedStatements ??= [...AUTH_TABLE_STATEMENTS, ...AUTH_RLS_STATEMENTS];
+  return cachedStatements;
+}
+
+/**
+ * Boots an in-memory PGlite db with the auth schema, its RLS policies and the app role:
+ * `ensureAppRole` then grants only the RLS-enabled tables and revokes the system-only pair.
+ */
+export async function createAuthTestDb(): Promise<FacilisDb> {
+  const db = await createDb();
+  await applyStatements(db, authSchemaStatements());
+  await ensureAppRole(db);
+  return db;
+}