@simple-auth-kit/cli 1.0.0

package/registry/combos/express-prisma/variants/base/prisma/schema/simple-auth-kit.prisma

@@ -0,0 +1,332 @@
+// 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 snake_case/plural at the database level and camelCase in TypeScript;
+// Prisma maps between them, so nothing in the application code spells a column name.
+// This is one file among possibly several under prisma/schema/ — Prisma's multi-file schema
+// support (stable since well before the version this repo pins) merges every .prisma file in
+// that folder into one logical schema automatically. Named simple-auth-kit.prisma specifically
+// so a consumer's own models, added as a sibling file in this same folder, are picked up by
+// `prisma generate`/`migrate` too, without the CLI ever touching that sibling file — it only
+// ever manages this one, by its exact name.
+//
+// `output` stays relative to *this file's own location*, which differs by context: the
+// registry's own dev/typecheck loop (scripts/materialize.mjs) keeps prisma/ as a sibling of
+// src/, so "../../generated/prisma" (two levels up from prisma/schema/) lands next to src/,
+// matching every "../generated/prisma/client.js" import there. A real CLI install moves
+// prisma.config.ts + prisma/ to the project root while src/ stays nested inside the merged
+// auth-lib directory — the CLI rewrites those same import strings in the copied files to match
+// (see installMerge's extraRewrites in cli/simple-auth-kit.ts), rather than this field trying to
+// be two things at once.
+generator client {
+  provider = "prisma-client"
+  output   = "../../generated/prisma"
+}
+
+datasource db {
+  provider = "postgresql"
+}
+
+model User {
+  id               BigInt    @id @default(autoincrement())
+  uuid             String    @unique @default(uuid())
+  email            String    @unique
+  firstName        String?   @unique @map("first_name")
+  lastName         String?   @unique @map("last_name")
+  displayName      String?   @map("display_name")
+  phone            String?   @unique
+  username         String?   @unique
+  photo            String?
+  lastLogin        DateTime? @map("last_login") @db.Timestamptz(6)
+  passwordHash     String?   @map("password_hash") // nullable: OAuth-only signup has 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   @default(false)
+  isActive         Boolean   @default(true) @map("is_active")
+  twoFactorEnabled Boolean   @default(false) @map("two_factor_enabled")
+  twoFactorSecret  String?   @map("two_factor_secret") // base32 TOTP secret; plaintext-at-rest
+  createdBy        BigInt?   @map("created_by")
+  updatedBy        BigInt?   @map("updated_by")
+  isDeleted        Boolean   @default(false) @map("is_deleted")
+  deletedAt        DateTime? @map("deleted_at") @db.Timestamptz(6)
+  deletedBy        BigInt?   @map("deleted_by")
+  deletedReason    String?   @map("deleted_reason") @db.VarChar(255)
+  createdAt        DateTime  @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt        DateTime  @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  roles                RoleUser[]
+  permissions          PermissionUser[]
+  sessions             Session[]             @relation("UserSessions")
+  oauthAccounts        OAuthAccount[]
+  passwordResetTokens  PasswordResetToken[]
+  twoFactorBackupCodes TwoFactorBackupCode[]
+
+  // Named relations: Session/Role/Permission each point at User multiple times, so Prisma needs
+  // an explicit name per back-reference.
+  revokedSessions Session[] @relation("UserRevokedSessions")
+  createdSessions Session[] @relation("SessionCreatedBy")
+  updatedSessions Session[] @relation("SessionUpdatedBy")
+  deletedSessions Session[] @relation("SessionDeletedBy")
+
+  createdByUser User?  @relation("UserCreatedBy", fields: [createdBy], references: [id], onDelete: SetNull)
+  usersCreated  User[] @relation("UserCreatedBy")
+  updatedByUser User?  @relation("UserUpdatedBy", fields: [updatedBy], references: [id], onDelete: SetNull)
+  usersUpdated  User[] @relation("UserUpdatedBy")
+  deletedByUser User?  @relation("UserDeletedBy", fields: [deletedBy], references: [id], onDelete: SetNull)
+  usersDeleted  User[] @relation("UserDeletedBy")
+
+  rolesCreated       Role[]       @relation("RoleCreatedBy")
+  rolesUpdated       Role[]       @relation("RoleUpdatedBy")
+  rolesDeleted       Role[]       @relation("RoleDeletedBy")
+  permissionsCreated Permission[] @relation("PermissionCreatedBy")
+  permissionsUpdated Permission[] @relation("PermissionUpdatedBy")
+  permissionsDeleted Permission[] @relation("PermissionDeletedBy")
+
+  @@index([isDeleted], map: "users_is_deleted_idx")
+  @@map("users")
+}
+
+/// `slug` is the identifier grants/revocations key off, so renaming `name`/`displayName` never
+/// breaks one. `isDefault` is what a newly signed-up user is given. `isActive: false` suspends a
+/// role without deleting it; `isDeleted` removes it from every listing outright.
+model Role {
+  id            BigInt    @id @default(autoincrement())
+  uuid          String    @unique @default(uuid())
+  slug          String    @unique @db.VarChar(255)
+  name          String    @db.VarChar(255)
+  displayName   String    @map("display_name") @db.VarChar(255)
+  description   String?
+  isDefault     Boolean   @default(false) @map("is_default")
+  order         Int       @default(0)
+  isActive      Boolean   @default(true) @map("is_active")
+  createdBy     BigInt?   @map("created_by")
+  updatedBy     BigInt?   @map("updated_by")
+  isDeleted     Boolean   @default(false) @map("is_deleted")
+  deletedAt     DateTime? @map("deleted_at") @db.Timestamptz(6)
+  deletedBy     BigInt?   @map("deleted_by")
+  deletedReason String?   @map("deleted_reason") @db.VarChar(255)
+  createdAt     DateTime  @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt     DateTime  @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  users       RoleUser[]
+  permissions PermissionRole[]
+
+  createdByUser User? @relation("RoleCreatedBy", fields: [createdBy], references: [id], onDelete: SetNull)
+  updatedByUser User? @relation("RoleUpdatedBy", fields: [updatedBy], references: [id], onDelete: SetNull)
+  deletedByUser User? @relation("RoleDeletedBy", fields: [deletedBy], references: [id], onDelete: SetNull)
+
+  @@index([isDefault], map: "roles_is_default_idx")
+  @@index([isActive, order], map: "roles_active_order_idx")
+  @@index([isDeleted], map: "roles_is_deleted_idx")
+  @@map("roles")
+}
+
+/// One capability, identified by its `slug` (`users:read`, `roles:assign`) — the same string
+/// used in `@CheckAbility` and `ability.can`. `group`/`groupOrder`/`order` back the admin
+/// console's permission matrix. `isActive: false` switches a capability off deployment-wide
+/// without unpicking every role that grants it; `isDeleted` removes it from every listing.
+model Permission {
+  id            BigInt    @id @default(autoincrement())
+  uuid          String    @unique @default(uuid())
+  slug          String    @unique @db.VarChar(255)
+  name          String    @db.VarChar(255)
+  displayName   String    @map("display_name") @db.VarChar(255)
+  description   String?
+  group         String    @default("General") @db.VarChar(255)
+  groupOrder    Int       @default(0) @map("group_order")
+  order         Int       @default(0)
+  isActive      Boolean   @default(true) @map("is_active")
+  createdBy     BigInt?   @map("created_by")
+  updatedBy     BigInt?   @map("updated_by")
+  isDeleted     Boolean   @default(false) @map("is_deleted")
+  deletedAt     DateTime? @map("deleted_at") @db.Timestamptz(6)
+  deletedBy     BigInt?   @map("deleted_by")
+  deletedReason String?   @map("deleted_reason") @db.VarChar(255)
+  createdAt     DateTime  @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt     DateTime  @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  roles PermissionRole[]
+  users PermissionUser[]
+
+  createdByUser User? @relation("PermissionCreatedBy", fields: [createdBy], references: [id], onDelete: SetNull)
+  updatedByUser User? @relation("PermissionUpdatedBy", fields: [updatedBy], references: [id], onDelete: SetNull)
+  deletedByUser User? @relation("PermissionDeletedBy", fields: [deletedBy], references: [id], onDelete: SetNull)
+
+  @@index([isActive], map: "permissions_is_active_idx")
+  @@index([group, groupOrder, order], map: "permissions_group_order_idx")
+  @@index([isDeleted], map: "permissions_is_deleted_idx")
+  @@map("permissions")
+}
+
+/// Which roles a user holds.
+model RoleUser {
+  userId    BigInt   @map("user_id")
+  roleId    BigInt   @map("role_id")
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+  role Role @relation(fields: [roleId], references: [id], onDelete: Cascade)
+
+  @@id([userId, roleId])
+  @@index([roleId], map: "role_user_role_id_idx")
+  @@map("role_user")
+}
+
+/// What each role carries.
+model PermissionRole {
+  permissionId BigInt   @map("permission_id")
+  roleId       BigInt   @map("role_id")
+  createdAt    DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt    DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  permission Permission @relation(fields: [permissionId], references: [id], onDelete: Cascade)
+  role       Role       @relation(fields: [roleId], references: [id], onDelete: Cascade)
+
+  @@id([permissionId, roleId])
+  @@index([roleId], map: "permission_role_role_id_idx")
+  @@map("permission_role")
+}
+
+/// Direct per-user permission grants, additive to whatever the user's roles already carry.
+model PermissionUser {
+  userId       BigInt   @map("user_id")
+  permissionId BigInt   @map("permission_id")
+  createdAt    DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt    DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  user       User       @relation(fields: [userId], references: [id], onDelete: Cascade)
+  permission Permission @relation(fields: [permissionId], references: [id], onDelete: Cascade)
+
+  @@id([userId, permissionId])
+  @@index([permissionId], map: "permission_user_permission_id_idx")
+  @@map("permission_user")
+}
+
+/// Links a social-login identity to a User. `[provider, providerAccountId]` is the OIDC `sub`
+/// claim; one User can have several, one per provider.
+model OAuthAccount {
+  id                BigInt   @id @default(autoincrement())
+  uuid              String   @unique @default(uuid())
+  userId            BigInt   @map("user_id")
+  provider          String   @db.VarChar(100)
+  providerAccountId String   @map("provider_account_id")
+  email             String?
+  createdAt         DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
+
+  user User @relation(fields: [userId], references: [id])
+
+  @@unique([provider, providerAccountId])
+  @@index([userId], map: "oauth_accounts_user_id_idx")
+  @@map("oauth_accounts")
+}
+
+/// Single-use forgot-password tokens. Only `tokenHash` is stored, never the raw token.
+model PasswordResetToken {
+  id         BigInt    @id @default(autoincrement())
+  uuid       String    @unique @default(uuid())
+  userId     BigInt    @map("user_id")
+  tokenHash  String    @unique @map("token_hash")
+  expiresAt  DateTime  @map("expires_at") @db.Timestamptz(6)
+  consumedAt DateTime? @map("consumed_at") @db.Timestamptz(6)
+  createdAt  DateTime  @default(now()) @map("created_at") @db.Timestamptz(6)
+
+  user User @relation(fields: [userId], references: [id])
+
+  @@map("password_reset_tokens")
+}
+
+/// One-time 2FA recovery codes, issued when the user confirms TOTP enrollment.
+model TwoFactorBackupCode {
+  id       BigInt    @id @default(autoincrement())
+  uuid     String    @unique @default(uuid())
+  userId   BigInt    @map("user_id")
+  codeHash String    @map("code_hash")
+  usedAt   DateTime? @map("used_at") @db.Timestamptz(6)
+
+  user User @relation(fields: [userId], references: [id])
+
+  @@index([userId], map: "two_factor_backup_codes_user_id_idx")
+  @@map("two_factor_backup_codes")
+}
+
+/// Append-only event 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 no schema change is needed when core adds event variants.
+/// The RBAC/User/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.
+model AuditLog {
+  id        BigInt   @id @default(autoincrement())
+  uuid      String   @unique @default(uuid())
+  userId    BigInt?  @map("user_id") // who the event is about; null if not attributable to one user
+  name      String // human-readable label for `action`, e.g. "Role assigned"
+  action    String // AuditEvent discriminant, e.g. "role_assigned"
+  info      Json // the rest of the AuditEvent's fields
+  remarks   String? // free-text note
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  @@index([userId, createdAt], map: "audit_logs_user_created_idx")
+  @@index([createdAt], map: "audit_logs_created_idx")
+  @@map("audit_logs")
+}
+
+/// One row per logged-in device. Stores no usable credential: `currentRefreshJti` is the id of
+/// the currently-valid refresh token, not the token itself. `expiresAt` is an absolute cap set
+/// once at creation, never extended — `rotateRefreshToken` in core enforces it. `isRevoked` is
+/// derived from `revokedAt` by the repository, never set independently.
+model Session {
+  id                BigInt    @id @default(autoincrement())
+  uuid              String    @unique @default(uuid())
+  userId            BigInt    @map("user_id")
+  sessionVersion    Int       @default(0) @map("session_version")
+  currentRefreshJti String    @map("current_refresh_jti")
+  provider          String?   @db.VarChar(100) // OAuth provider this login came through; null for a password login
+  userAgent         String?   @map("user_agent")
+  ip                String?   @db.VarChar(100)
+  expiresAt         DateTime  @map("expires_at") @db.Timestamptz(6)
+  isRevoked         Boolean   @default(false) @map("is_revoked")
+  revokedAt         DateTime? @map("revoked_at") @db.Timestamptz(6)
+  revokedBy         BigInt?   @map("revoked_by")
+  revokedByIp       String?   @map("revoked_ip") @db.VarChar(100)
+  isActive          Boolean   @default(true) @map("is_active")
+  createdBy         BigInt?   @map("created_by")
+  updatedBy         BigInt?   @map("updated_by")
+  isDeleted         Boolean   @default(false) @map("is_deleted")
+  deletedAt         DateTime? @map("deleted_at") @db.Timestamptz(6)
+  deletedBy         BigInt?   @map("deleted_by")
+  deletedReason     String?   @map("deleted_reason") @db.VarChar(255)
+  createdAt         DateTime  @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt         DateTime  @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  user          User  @relation("UserSessions", fields: [userId], references: [id], onDelete: Cascade)
+  revokedByUser User? @relation("UserRevokedSessions", fields: [revokedBy], references: [id], onDelete: SetNull)
+  createdByUser User? @relation("SessionCreatedBy", fields: [createdBy], references: [id], onDelete: SetNull)
+  updatedByUser User? @relation("SessionUpdatedBy", fields: [updatedBy], references: [id], onDelete: SetNull)
+  deletedByUser User? @relation("SessionDeletedBy", fields: [deletedBy], references: [id], onDelete: SetNull)
+
+  @@index([userId], map: "sessions_user_id_idx")
+  @@index([isRevoked], map: "sessions_is_revoked_idx")
+  @@index([expiresAt], map: "sessions_expires_at_idx")
+  @@index([userId, isRevoked, expiresAt], map: "sessions_user_active_idx")
+  @@index([revokedBy], map: "sessions_revoked_by_idx")
+  @@map("sessions")
+}
+
+/// 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.
+model DenylistedAccessToken {
+  jti       String   @id
+  expiresAt DateTime @map("expires_at") @db.Timestamptz(6)
+
+  @@map("denylisted_access_tokens")
+}

package/registry/combos/express-prisma/variants/base/src/admin.router.ts

@@ -0,0 +1,314 @@
+import type { NextFunction, Request, RequestHandler, Response } from "express";
+import { AuthService } from "./auth.service.js";
+import { HttpError } from "./http-error.js";
+import { ability, createTieredRouter, type TierMiddleware } from "./route-tiers.js";
+import "./request-context.js";
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.length === 0) throw new HttpError(400, `${field} is required`);
+  return value;
+}
+
+const optionalString = (value: unknown): string | undefined => (typeof value === "string" ? value : undefined);
+
+export interface AdminRouterDeps extends TierMiddleware {
+  auth: AuthService;
+}
+
+/**
+ * Administration of the whole deployment. Authority is a permission, never a role name: the authz
+ * middleware resolves the caller's roles and permissions from the database on this request, builds
+ * the CASL ability from them, and each route's `ability(...)` tier checks its slugs against it.
+ * There is no role-based bypass — holding a role called "admin" that carries no permissions gets
+ * exactly the same 403 as holding no role at all, which is why `npm run seed` (which provisions the
+ * catalog and the roles that carry it) is a prerequisite for this router doing anything.
+ *
+ * Each route says what it demands; the rows say who is granted it. The slugs below are checked at
+ * compile time against `PERMISSION_CATALOG` in `rbac.defaults.ts`, while who holds them — and
+ * whether the permission is active at all — is edited through this very router and takes effect on
+ * the next request. `GET /auth/me` returns the caller's slugs, and a console rebuilds the same
+ * ability from them with the same function the middleware used.
+ *
+ * Replaces the reference combo's `AdminController`. Mounted under `/auth/admin` by
+ * create-auth-app.ts; `createTieredRouter` stands in for its
+ * `@UseGuards(AuthGuard, AuthzGuard, AbilityGuard)` — see route-tiers.ts for why the tier is a
+ * required argument rather than a decorator.
+ */
+export function createAdminRouter(deps: AdminRouterDeps): RequestHandler {
+  const { auth, authentication, authorization } = deps;
+  const admin = createTieredRouter({ authentication, authorization });
+
+  admin.route("get", "/users", ability("users:read"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { search, page, limit } = req.query as Record<string, string | undefined>;
+      res.status(200).json(await auth.listUsers({ search, page: page ? Number(page) : undefined, limit: limit ? Number(limit) : undefined }));
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  // No invitation email — the account is usable immediately with the password given here.
+  admin.route("post", "/users", ability("users:manage"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      res.status(201).json(
+        await auth.createUser(
+          {
+            email: requireString(body.email, "email"),
+            password: requireString(body.password, "password"),
+            firstName: optionalString(body.firstName),
+            lastName: optionalString(body.lastName),
+            displayName: optionalString(body.displayName),
+            phone: optionalString(body.phone),
+            username: optionalString(body.username),
+            roles: Array.isArray(body.roles) ? body.roles.filter((role): role is string => typeof role === "string") : undefined,
+          },
+          req.auth!.sub,
+        ),
+      );
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("get", "/users/:userId", ability("users:read"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      res.status(200).json(await auth.getUser(requireString(req.params.userId, "userId")));
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  // Profile fields only — email is the login identifier and is not editable here.
+  admin.route("patch", "/users/:userId", ability("users:manage"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const userId = requireString(req.params.userId, "userId");
+      const body = req.body as Record<string, unknown>;
+      res.status(200).json(
+        await auth.updateUser(
+          userId,
+          {
+            firstName: body.firstName === null ? null : optionalString(body.firstName),
+            lastName: body.lastName === null ? null : optionalString(body.lastName),
+            displayName: body.displayName === null ? null : optionalString(body.displayName),
+            phone: body.phone === null ? null : optionalString(body.phone),
+            username: body.username === null ? null : optionalString(body.username),
+            photo: body.photo === null ? null : optionalString(body.photo),
+          },
+          req.auth!.sub,
+        ),
+      );
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  // Soft-delete: the row survives for audit purposes, stops appearing in listings, and can no
+  // longer authenticate.
+  admin.route("delete", "/users/:userId", ability("users:manage"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const userId = requireString(req.params.userId, "userId");
+      if (userId === req.auth!.sub) throw new HttpError(403, "cannot delete your own account");
+      await auth.deleteUser(userId, req.auth!.sub, optionalString((req.body as Record<string, unknown> | undefined)?.reason));
+      res.status(200).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("get", "/audit-log", ability("audit-log:read"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { userId, action, since, until, page, limit } = req.query as Record<string, string | undefined>;
+      res.status(200).json(
+        await auth.listAuditLog({ userId, action, since, until, page: page ? Number(page) : undefined, limit: limit ? Number(limit) : undefined }),
+      );
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("get", "/permissions", ability("permissions:read"), async (_req: Request, res: Response, next: NextFunction) => {
+    try {
+      res.status(200).json(await auth.listPermissions());
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/permissions", ability("permissions:define"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      res.status(201).json(
+        await auth.definePermission(
+          {
+            slug: requireString(body.slug, "slug"),
+            name: optionalString(body.name),
+            displayName: optionalString(body.displayName),
+            description: body.description === null ? null : optionalString(body.description),
+            group: optionalString(body.group),
+            groupOrder: typeof body.groupOrder === "number" ? body.groupOrder : undefined,
+            order: typeof body.order === "number" ? body.order : undefined,
+            isActive: typeof body.isActive === "boolean" ? body.isActive : undefined,
+          },
+          req.auth!.sub,
+        ),
+      );
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("get", "/roles", ability("roles:manage"), async (_req: Request, res: Response, next: NextFunction) => {
+    try {
+      res.status(200).json(await auth.listRoles());
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/roles", ability("roles:manage"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      res.status(201).json(
+        await auth.createRole(
+          {
+            slug: requireString(body.slug, "slug"),
+            name: optionalString(body.name),
+            displayName: optionalString(body.displayName),
+            description: optionalString(body.description) ?? null,
+          },
+          req.auth!.sub,
+        ),
+      );
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("patch", "/roles/:roleId", ability("roles:manage"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const roleId = requireString(req.params.roleId, "roleId");
+      const body = req.body as Record<string, unknown>;
+      res.status(200).json(
+        await auth.updateRole(
+          roleId,
+          {
+            name: optionalString(body.name),
+            displayName: optionalString(body.displayName),
+            description: body.description === null ? null : optionalString(body.description),
+            isActive: typeof body.isActive === "boolean" ? body.isActive : undefined,
+          },
+          req.auth!.sub,
+        ),
+      );
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  // Soft-delete: existing assignments are left in place rather than cascade-deleted, and the role
+  // simply stops being resolved.
+  admin.route("delete", "/roles/:roleId", ability("roles:manage"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const roleId = requireString(req.params.roleId, "roleId");
+      await auth.deleteRole(roleId, req.auth!.sub, optionalString((req.body as Record<string, unknown> | undefined)?.reason));
+      res.status(200).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/roles/:roleId/permissions", ability("roles:manage"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      await auth.attachPermissionToRole(requireString(req.params.roleId, "roleId"), requireString(body.permission, "permission"), req.auth!.sub);
+      res.status(201).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/users/:userId/roles", ability("roles:assign"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      await auth.assignRole(requireString(req.params.userId, "userId"), requireString(body.role, "role"));
+      res.status(201).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/users/:userId/roles/:roleSlug/revoke", ability("roles:assign"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const userId = requireString(req.params.userId, "userId");
+      // Revoking your own `admin` would strip the very permission that let you call this,
+      // with no route back in. Assigning to yourself is fine — it can't lock anyone out.
+      if (userId === req.auth!.sub) throw new HttpError(403, "cannot change your own roles");
+      await auth.revokeRole(userId, requireString(req.params.roleSlug, "roleSlug"));
+      res.status(201).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/users/:userId/permissions", ability("permissions:grant"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      await auth.grantPermission(requireString(req.params.userId, "userId"), requireString(body.permission, "permission"), req.auth!.sub);
+      res.status(201).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/users/:userId/permissions/:permissionSlug/revoke", ability("permissions:grant"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await auth.revokePermission(requireString(req.params.userId, "userId"), requireString(req.params.permissionSlug, "permissionSlug"));
+      res.status(201).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/users/:userId/block", ability("users:block"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const userId = requireString(req.params.userId, "userId");
+      if (userId === req.auth!.sub) throw new HttpError(403, "cannot block your own account");
+      await auth.block(userId, { userId: req.auth!.sub, ip: req.ip });
+      res.status(201).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/users/:userId/unblock", ability("users:block"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await auth.unblock(requireString(req.params.userId, "userId"), { userId: req.auth!.sub, ip: req.ip });
+      res.status(201).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/users/:userId/deactivate", ability("users:block"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const userId = requireString(req.params.userId, "userId");
+      if (userId === req.auth!.sub) throw new HttpError(403, "cannot deactivate your own account");
+      await auth.deactivate(userId, { userId: req.auth!.sub, ip: req.ip });
+      res.status(201).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  admin.route("post", "/users/:userId/activate", ability("users:block"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await auth.activate(requireString(req.params.userId, "userId"), { userId: req.auth!.sub, ip: req.ip });
+      res.status(201).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  return admin.handler;
+}