@simple-auth-kit/cli 1.0.0

package/registry/combos/nestjs-drizzle/variants/base/src/schema.ts

@@ -0,0 +1,427 @@
+// Roles and permissions are global to this deployment: a user has one set of roles, and it
+// applies everywhere.
+//
+// Authorization is resolved from the database on every request — user → roles → role permissions,
+// unioned with the user's direct grants — and the access token carries no authorization at all.
+// That is what makes a grant or a revocation take effect on the caller's *next request* rather
+// than their next token. The cost is bounded: three indexed reads on join tables, constant in the
+// number of users.
+//
+// Table and column names are the snake_case/plural ones the Prisma combos emit, so the two
+// reference combos produce interchangeable databases and the dev portal's schema-drift table has
+// nothing to flag. Ids are `bigint` (identity), which is what Prisma's `BigInt @id
+// @default(autoincrement())` does — every table also carries a separate `uuid` column for
+// external/URL use, since a sequential integer id should never appear in a URL.
+import { randomUUID } from "node:crypto";
+import { relations } from "drizzle-orm";
+import { type AnyPgColumn, bigint, bigserial, boolean, date, index, integer, jsonb, pgTable, primaryKey, text, timestamp, uniqueIndex, varchar } from "drizzle-orm/pg-core";
+
+/** Prisma's `@db.Timestamptz(6)`. Spelled once so no table can disagree with another about it. */
+const timestamptz = (name: string) => timestamp(name, { withTimezone: true, precision: 6 });
+
+/** Every table's primary key: bigint identity for join/index performance. */
+const id = () => bigserial("id", { mode: "bigint" }).primaryKey();
+
+/** Every table's external/URL-facing identifier — never the sequential `id`. */
+const uuid = () =>
+  text("uuid")
+    .notNull()
+    .$defaultFn(() => randomUUID());
+
+export const users = pgTable(
+  "users",
+  {
+    id: id(),
+    uuid: uuid(),
+    email: text("email").notNull(),
+    firstName: text("first_name"),
+    lastName: text("last_name"),
+    displayName: text("display_name"),
+    phone: text("phone"),
+    username: text("username"),
+    photo: text("photo"),
+    dob: date("dob"),
+    gender: varchar("gender", { length: 10 }),
+    joinedDate: date("joined_date").defaultNow().notNull(),
+    lastLogin: timestamptz("last_login"),
+    passwordHash: text("password_hash"), // nullable: users created via OAuth-only signup have no password
+    // Two independent reasons an account can't authenticate, tracked separately so an admin can see
+    // *why*: `blocked` is a security/moderation action (see `block()`/`unblock()`); `isActive` is a
+    // routine administrative on/off toggle (see `activate()`/`deactivate()`) — e.g. paused while an
+    // employee is on leave, with no implication of wrongdoing. Both deny login on their own; neither
+    // implies the other, and unblocking a blocked-but-inactive account still leaves it inactive.
+    blocked: boolean("blocked").notNull().default(false),
+    isActive: boolean("is_active").notNull().default(true),
+    twoFactorEnabled: boolean("two_factor_enabled").notNull().default(false),
+    twoFactorSecret: text("two_factor_secret"), // base32 TOTP secret; plaintext-at-rest, same accepted tradeoff already made for AUTH_JWT_SECRET (see key-provider.ts)
+    createdBy: bigint("created_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    updatedBy: bigint("updated_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    isDeleted: boolean("is_deleted").notNull().default(false),
+    deletedAt: timestamptz("deleted_at"),
+    deletedBy: bigint("deleted_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    deletedReason: varchar("deleted_reason", { length: 255 }),
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+    updatedAt: timestamptz("updated_at")
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [
+    uniqueIndex("users_uuid_key").on(table.uuid),
+    uniqueIndex("users_email_key").on(table.email),
+    uniqueIndex("users_first_name_key").on(table.firstName),
+    uniqueIndex("users_last_name_key").on(table.lastName),
+    uniqueIndex("users_phone_key").on(table.phone),
+    uniqueIndex("users_username_key").on(table.username),
+    index("users_is_deleted_idx").on(table.isDeleted),
+  ],
+);
+
+/**
+ * A named bundle of permissions. `slug` is the identifier everything else references, so renaming
+ * `name`/`displayName` never breaks a grant. `isDefault` is what a newly signed-up user is given,
+ * so the signup default is a row rather than a string literal in code. `isActive: false` suspends
+ * a role without deleting it; `isDeleted` removes it from every listing outright.
+ */
+export const roles = pgTable(
+  "roles",
+  {
+    id: id(),
+    uuid: uuid(),
+    slug: varchar("slug", { length: 255 }).notNull(),
+    name: varchar("name", { length: 255 }).notNull(),
+    displayName: varchar("display_name", { length: 255 }).notNull(),
+    description: text("description"),
+    isDefault: boolean("is_default").notNull().default(false),
+    order: integer("order").notNull().default(0),
+    isActive: boolean("is_active").notNull().default(true),
+    createdBy: bigint("created_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    updatedBy: bigint("updated_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    isDeleted: boolean("is_deleted").notNull().default(false),
+    deletedAt: timestamptz("deleted_at"),
+    deletedBy: bigint("deleted_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    deletedReason: varchar("deleted_reason", { length: 255 }),
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+    updatedAt: timestamptz("updated_at")
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [
+    uniqueIndex("roles_uuid_key").on(table.uuid),
+    uniqueIndex("roles_slug_key").on(table.slug),
+    index("roles_is_default_idx").on(table.isDefault),
+    index("roles_active_order_idx").on(table.isActive, table.order),
+    index("roles_is_deleted_idx").on(table.isDeleted),
+  ],
+);
+
+/**
+ * One capability, identified by its `slug` — `users:read`, `roles:assign`. The slug *is* the
+ * ability: `@CheckAbility("users:read")` on a route and `ability.can("users:read", "")` in a
+ * client are the same string, and the row is the only place it is defined.
+ *
+ * `group`/`groupOrder`/`order` exist for the admin console's permission matrix, which has to
+ * render a checkbox grid in a stable, human order; putting that order in the row keeps the console
+ * from hardcoding a second copy of the catalog. `isActive: false` is how a capability is switched
+ * off deployment-wide without unpicking every role that grants it.
+ */
+export const permissions = pgTable(
+  "permissions",
+  {
+    id: id(),
+    uuid: uuid(),
+    slug: varchar("slug", { length: 255 }).notNull(),
+    name: varchar("name", { length: 255 }).notNull(),
+    displayName: varchar("display_name", { length: 255 }).notNull(),
+    description: text("description"),
+    group: varchar("group", { length: 255 }).notNull().default("General"),
+    groupOrder: integer("group_order").notNull().default(0),
+    order: integer("order").notNull().default(0),
+    isActive: boolean("is_active").notNull().default(true),
+    createdBy: bigint("created_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    updatedBy: bigint("updated_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    isDeleted: boolean("is_deleted").notNull().default(false),
+    deletedAt: timestamptz("deleted_at"),
+    deletedBy: bigint("deleted_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    deletedReason: varchar("deleted_reason", { length: 255 }),
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+    updatedAt: timestamptz("updated_at")
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [
+    uniqueIndex("permissions_uuid_key").on(table.uuid),
+    uniqueIndex("permissions_slug_key").on(table.slug),
+    index("permissions_is_active_idx").on(table.isActive),
+    index("permissions_group_order_idx").on(table.group, table.groupOrder, table.order),
+    index("permissions_is_deleted_idx").on(table.isDeleted),
+  ],
+);
+
+/**
+ * Which roles a user holds. A real join table with real foreign keys, so a role cannot be assigned
+ * that does not exist and renaming a role cannot orphan an assignment.
+ */
+export const roleUser = pgTable(
+  "role_user",
+  {
+    userId: bigint("user_id", { mode: "bigint" })
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    roleId: bigint("role_id", { mode: "bigint" })
+      .notNull()
+      .references(() => roles.id, { onDelete: "cascade" }),
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+    updatedAt: timestamptz("updated_at")
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [primaryKey({ name: "role_user_pkey", columns: [table.userId, table.roleId] }), index("role_user_role_id_idx").on(table.roleId)],
+);
+
+/** What each role carries. */
+export const permissionRole = pgTable(
+  "permission_role",
+  {
+    permissionId: bigint("permission_id", { mode: "bigint" })
+      .notNull()
+      .references(() => permissions.id, { onDelete: "cascade" }),
+    roleId: bigint("role_id", { mode: "bigint" })
+      .notNull()
+      .references(() => roles.id, { onDelete: "cascade" }),
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+    updatedAt: timestamptz("updated_at")
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [
+    primaryKey({ name: "permission_role_pkey", columns: [table.permissionId, table.roleId] }),
+    index("permission_role_role_id_idx").on(table.roleId),
+  ],
+);
+
+/** Direct per-user permission grants, additive to whatever the user's roles already carry. */
+export const permissionUser = pgTable(
+  "permission_user",
+  {
+    userId: bigint("user_id", { mode: "bigint" })
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    permissionId: bigint("permission_id", { mode: "bigint" })
+      .notNull()
+      .references(() => permissions.id, { onDelete: "cascade" }),
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+    updatedAt: timestamptz("updated_at")
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [
+    primaryKey({ name: "permission_user_pkey", columns: [table.userId, table.permissionId] }),
+    index("permission_user_permission_id_idx").on(table.permissionId),
+  ],
+);
+
+/** Links a social-login identity to a user. `[provider, providerAccountId]` is the natural
+ * key an OIDC issuer gives you (its `sub` claim); one user can have several, one per provider. */
+export const oauthAccounts = pgTable(
+  "oauth_accounts",
+  {
+    id: id(),
+    uuid: uuid(),
+    userId: bigint("user_id", { mode: "bigint" })
+      .notNull()
+      .references(() => users.id),
+    provider: varchar("provider", { length: 100 }).notNull(),
+    providerAccountId: text("provider_account_id").notNull(),
+    email: text("email"),
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("oauth_accounts_uuid_key").on(table.uuid),
+    uniqueIndex("oauth_accounts_provider_provider_account_id_key").on(table.provider, table.providerAccountId),
+    index("oauth_accounts_user_id_idx").on(table.userId),
+  ],
+);
+
+/** Single-use forgot-password tokens. Only `tokenHash` is stored (sha256 of the raw token
+ * emailed to the user) — mirrors denylistedAccessTokens never holding a bearer secret in the clear. */
+export const passwordResetTokens = pgTable(
+  "password_reset_tokens",
+  {
+    id: id(),
+    uuid: uuid(),
+    userId: bigint("user_id", { mode: "bigint" })
+      .notNull()
+      .references(() => users.id),
+    tokenHash: text("token_hash").notNull(),
+    expiresAt: timestamptz("expires_at").notNull(),
+    consumedAt: timestamptz("consumed_at"),
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+  },
+  (table) => [uniqueIndex("password_reset_tokens_uuid_key").on(table.uuid), uniqueIndex("password_reset_tokens_token_hash_key").on(table.tokenHash)],
+);
+
+/** One-time 2FA recovery codes, issued when the user confirms TOTP enrollment. */
+export const twoFactorBackupCodes = pgTable(
+  "two_factor_backup_codes",
+  {
+    id: id(),
+    uuid: uuid(),
+    userId: bigint("user_id", { mode: "bigint" })
+      .notNull()
+      .references(() => users.id),
+    codeHash: text("code_hash").notNull(),
+    usedAt: timestamptz("used_at"),
+  },
+  (table) => [uniqueIndex("two_factor_backup_codes_uuid_key").on(table.uuid), index("two_factor_backup_codes_user_id_idx").on(table.userId)],
+);
+
+/** Persisted sink for `SessionStoreDeps.appendAuditEvent` (registry/core/session-policy.ts)
+ * plus the RBAC/2FA/OAuth/password-reset flows. `action` is the AuditEvent's discriminant and
+ * `info` the rest of its fields, so this table needs no schema change when new event variants
+ * are added in core.
+ *
+ * The User/Role/Permission/Session tables also carry their own `createdBy`/`updatedBy`/
+ * `deletedBy` — a denormalized copy of the same fact, kept so a row-level "who touched this" read
+ * needs no join. */
+export const auditLogs = pgTable(
+  "audit_logs",
+  {
+    id: id(),
+    uuid: uuid(),
+    userId: bigint("user_id", { mode: "bigint" }), // who the event is about; null for events not attributable to one user
+    name: text("name").notNull(), // human-readable label for `action`, e.g. "Role assigned"
+    action: text("action").notNull(), // AuditEvent discriminant, e.g. "role_assigned"
+    info: jsonb("info").notNull(), // the rest of the AuditEvent's fields
+    remarks: text("remarks"), // free-text note, for whoever is reading the log later
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+    updatedAt: timestamptz("updated_at")
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [
+    uniqueIndex("audit_logs_uuid_key").on(table.uuid),
+    index("audit_logs_user_created_idx").on(table.userId, table.createdAt),
+    index("audit_logs_created_idx").on(table.createdAt),
+  ],
+);
+
+/**
+ * Sessions are user-level: one row per logged-in device, independent of any grouping above it.
+ *
+ * Deliberately stores no usable credential: `currentRefreshJti` is the id of the refresh token
+ * that is currently valid, not the token, and access-token revocation is the denylist below. A
+ * read of this table hands an attacker nothing they can present. That is the one place this table
+ * diverges from the reference implementation it is otherwise column-for-column copied from, which
+ * keeps `token` and `refresh_token` columns holding the live tokens themselves.
+ *
+ * `expiresAt` is an absolute cap set once at creation and never extended, so a continuously
+ * refreshing client still has to log in again eventually; `rotateRefreshToken` in core enforces
+ * it. `isRevoked` is derived from `revokedAt` by the repository rather than set independently —
+ * two columns for one fact can only ever disagree — and `revokedBy`/`revokedByIp` are what let a
+ * row say *who* ended the session, which is how an administrator's block is told apart from the
+ * user's own logout afterwards.
+ */
+export const sessions = pgTable(
+  "sessions",
+  {
+    id: id(),
+    uuid: uuid(),
+    userId: bigint("user_id", { mode: "bigint" })
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    sessionVersion: integer("session_version").notNull().default(0),
+    currentRefreshJti: text("current_refresh_jti").notNull(),
+    provider: varchar("provider", { length: 100 }), // the OAuth provider this login came through; null for a password login
+    userAgent: text("user_agent"),
+    ip: varchar("ip", { length: 100 }),
+    expiresAt: timestamptz("expires_at").notNull(),
+    isRevoked: boolean("is_revoked").notNull().default(false),
+    revokedAt: timestamptz("revoked_at"),
+    revokedBy: bigint("revoked_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    revokedByIp: varchar("revoked_ip", { length: 100 }),
+    isActive: boolean("is_active").notNull().default(true),
+    createdBy: bigint("created_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    updatedBy: bigint("updated_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    isDeleted: boolean("is_deleted").notNull().default(false),
+    deletedAt: timestamptz("deleted_at"),
+    deletedBy: bigint("deleted_by", { mode: "bigint" }).references((): AnyPgColumn => users.id, { onDelete: "set null" }),
+    deletedReason: varchar("deleted_reason", { length: 255 }),
+    createdAt: timestamptz("created_at").notNull().defaultNow(),
+    updatedAt: timestamptz("updated_at")
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [
+    uniqueIndex("sessions_uuid_key").on(table.uuid),
+    index("sessions_user_id_idx").on(table.userId),
+    index("sessions_is_revoked_idx").on(table.isRevoked),
+    index("sessions_expires_at_idx").on(table.expiresAt),
+    index("sessions_user_active_idx").on(table.userId, table.isRevoked, table.expiresAt),
+    index("sessions_revoked_by_idx").on(table.revokedBy),
+  ],
+);
+
+/** Instant access-token revocation. Rows are only ever as old as the access-token
+ * TTL (~15 min) — safe to move to Redis with a matching TTL without changing callers. */
+export const denylistedAccessTokens = pgTable("denylisted_access_tokens", {
+  jti: text("jti").primaryKey(),
+  expiresAt: timestamptz("expires_at").notNull(),
+});
+
+export const usersRelations = relations(users, ({ many }) => ({
+  roles: many(roleUser),
+  permissions: many(permissionUser),
+  sessions: many(sessions),
+  oauthAccounts: many(oauthAccounts),
+  passwordResetTokens: many(passwordResetTokens),
+  twoFactorBackupCodes: many(twoFactorBackupCodes),
+}));
+
+export const rolesRelations = relations(roles, ({ many }) => ({
+  users: many(roleUser),
+  permissions: many(permissionRole),
+}));
+
+export const permissionsRelations = relations(permissions, ({ many }) => ({
+  roles: many(permissionRole),
+  users: many(permissionUser),
+}));
+
+export const roleUserRelations = relations(roleUser, ({ one }) => ({
+  user: one(users, { fields: [roleUser.userId], references: [users.id] }),
+  role: one(roles, { fields: [roleUser.roleId], references: [roles.id] }),
+}));
+
+export const permissionRoleRelations = relations(permissionRole, ({ one }) => ({
+  permission: one(permissions, { fields: [permissionRole.permissionId], references: [permissions.id] }),
+  role: one(roles, { fields: [permissionRole.roleId], references: [roles.id] }),
+}));
+
+export const permissionUserRelations = relations(permissionUser, ({ one }) => ({
+  user: one(users, { fields: [permissionUser.userId], references: [users.id] }),
+  permission: one(permissions, { fields: [permissionUser.permissionId], references: [permissions.id] }),
+}));
+
+export const oauthAccountsRelations = relations(oauthAccounts, ({ one }) => ({
+  user: one(users, { fields: [oauthAccounts.userId], references: [users.id] }),
+}));
+
+export const passwordResetTokensRelations = relations(passwordResetTokens, ({ one }) => ({
+  user: one(users, { fields: [passwordResetTokens.userId], references: [users.id] }),
+}));
+
+export const twoFactorBackupCodesRelations = relations(twoFactorBackupCodes, ({ one }) => ({
+  user: one(users, { fields: [twoFactorBackupCodes.userId], references: [users.id] }),
+}));
+
+export const sessionsRelations = relations(sessions, ({ one }) => ({
+  user: one(users, { fields: [sessions.userId], references: [users.id] }),
+}));

package/registry/combos/nestjs-drizzle/variants/base/src/seed.ts

@@ -0,0 +1,138 @@
+// Idempotent database seeder — everything RBAC needs before this deployment can authorize
+// anything. Roles are system-defined with fixed permission sets, so a fresh database has no
+// permission rows and no role rows, and every authorization check has nothing to check against.
+//
+//   npm run seed
+//
+// It seeds three things, in order:
+//
+//   1. the permission catalog — one slug per capability the admin API exposes;
+//   2. the default roles and their permission sets;
+//   3. an initial admin user, but only when SEED_ADMIN_EMAIL *and* SEED_ADMIN_PASSWORD are set.
+//      There is deliberately no fallback password: a seeder that invents one puts the same known
+//      credential on every fresh deployment. With the variables unset it says so and carries on.
+//
+// Re-running is safe: every write is an upsert and nothing is ever deleted. That also means it
+// is additive, on purpose — a permission you attached to a role by hand survives a re-run, and
+// an admin who already exists keeps the password they have now (the seeder never rewrites a
+// password it did not set).
+//
+// (1) and (2) are not defined here: they live in `rbac.defaults.ts`, which is also what types
+// `@CheckAbility` on the routes. The seeder is a caller of that definition, not its owner — so
+// what gets seeded and what the routes demand cannot drift apart.
+import { eq, inArray, notInArray } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { hashPassword } from "@/lib/auth/core/crypto.js";
+import type { Database } from "./db.js";
+import { DEFAULT_ROLES, PERMISSION_SLUGS, SEED_ADMIN_ROLES, SEED_SUPERADMIN_ROLES, provisionDefaultRoles } from "./rbac.defaults.js";
+import * as schema from "./schema.js";
+import { permissions, roleUser, roles, users } from "./schema.js";
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`${name} is not set — the seeder cannot reach the database without it`);
+  return value;
+}
+
+/** The catalog and the roles come from rbac.defaults.ts; this only reports what it wrote. */
+async function seedRbacDefaults(db: Database): Promise<void> {
+  await provisionDefaultRoles(db);
+  console.log(`permissions: ${PERMISSION_SLUGS.length} slug(s) in the catalog`);
+  for (const role of DEFAULT_ROLES) console.log(`role "${role.slug}": ${role.permissions.length} permission(s)${role.isDefault ? " (signup default)" : ""}`);
+
+  // Slugs that exist in the database but not in this build's catalog. They are not an error —
+  // `POST /auth/admin/permissions` exists so a deployment can define its own, and a grant can
+  // create one — but a slug no route names grants nothing, so a typo would otherwise be a
+  // permission that mysteriously never works. Printing them is what makes it visible.
+  const unknown = await db
+    .select({ slug: permissions.slug })
+    .from(permissions)
+    .where(notInArray(permissions.slug, PERMISSION_SLUGS));
+  if (unknown.length) console.log(`permissions: ${unknown.length} slug(s) outside this build's catalog (no route names them): ${unknown.map((r) => r.slug).join(", ")}`);
+  const inactive = await db.select({ slug: permissions.slug }).from(permissions).where(eq(permissions.isActive, false));
+  if (inactive.length) console.log(`permissions: ${inactive.length} deactivated, granting nothing: ${inactive.map((r) => r.slug).join(", ")}`);
+}
+
+/** Roles are global here, so administrative authority is a property of the user row itself. */
+async function seedAdminUser(db: Database): Promise<void> {
+  const email = process.env["SEED_ADMIN_EMAIL"];
+  const password = process.env["SEED_ADMIN_PASSWORD"];
+  if (!email || !password) {
+    console.log("admin: skipped — set SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD to create one (there is no default password)");
+    return;
+  }
+
+  // Their password may have been changed since; rewriting it here would silently reset it.
+  const [existing] = await db.select({ id: users.id }).from(users).where(eq(users.email, email)).limit(1);
+  // Hashed by the same function signup uses, so the seeded admin can actually log in.
+  const user = existing ?? (await db.insert(users).values({ email, passwordHash: await hashPassword(password) }).returning({ id: users.id }))[0];
+  console.log(existing ? `admin: ${email} already exists — password left unchanged` : `admin: created ${email}`);
+
+  const adminRoles = await db
+    .select({ id: roles.id, slug: roles.slug })
+    .from(roles)
+    .where(inArray(roles.slug, SEED_ADMIN_ROLES));
+  if (adminRoles.length) {
+    await db
+      .insert(roleUser)
+      .values(adminRoles.map((role) => ({ userId: user.id, roleId: role.id })))
+      .onConflictDoNothing({ target: [roleUser.userId, roleUser.roleId] });
+  }
+  console.log(`admin: holds roles ${adminRoles.map((r) => r.slug).join(", ")}`);
+}
+
+/** Roles are global here, so administrative authority is a property of the user row itself. */
+async function seedSuperAdminUser(db: Database): Promise<void> {
+  const email = process.env["SEED_SUPERADMIN_EMAIL"];
+  const password = process.env["SEED_SUPERADMIN_PASSWORD"];
+  if (!email || !password) {
+    console.log("super admin: skipped — set SEED_SUPERADMIN_EMAIL and SEED_SUPERADMIN_PASSWORD to create one (there is no default password)");
+    return;
+  }
+  const username = process.env["SEED_SUPERADMIN_USERNAME"] || undefined;
+
+  // Their password may have been changed since; rewriting it here would silently reset it.
+  const [existing] = await db.select({ id: users.id }).from(users).where(eq(users.email, email)).limit(1);
+  // Hashed by the same function signup uses, so the seeded super admin can actually log in.
+  const user = existing ?? (await db.insert(users).values({ email, username, passwordHash: await hashPassword(password) }).returning({ id: users.id }))[0];
+  console.log(existing ? `super admin: ${email} already exists — password left unchanged` : `super admin: created ${email}${username ? ` (username ${username})` : ""}`);
+
+  const superAdminRoles = await db
+    .select({ id: roles.id, slug: roles.slug })
+    .from(roles)
+    .where(inArray(roles.slug, SEED_SUPERADMIN_ROLES));
+  if (superAdminRoles.length) {
+    await db
+      .insert(roleUser)
+      .values(superAdminRoles.map((role) => ({ userId: user.id, roleId: role.id })))
+      .onConflictDoNothing({ target: [roleUser.userId, roleUser.roleId] });
+  }
+  console.log(`super admin: holds roles ${superAdminRoles.map((r) => r.slug).join(", ")}`);
+}
+
+async function main(): Promise<void> {
+  // Loads .env from the working directory if there is one. It never overrides a variable the
+  // process was already given, so an explicit `SEED_ADMIN_PASSWORD=... npm run seed` still wins.
+  try {
+    process.loadEnvFile();
+  } catch {
+    // No .env here — the environment is expected to carry the variables itself (docker, CI, ...).
+  }
+
+  const pool = new Pool({ connectionString: requireEnv("DATABASE_URL") });
+  try {
+    const db: Database = drizzle(pool, { schema });
+    await seedRbacDefaults(db);
+    await seedAdminUser(db);
+    await seedSuperAdminUser(db);
+    console.log("seed complete.");
+  } finally {
+    await pool.end();
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});