@simple-auth-kit/cli 1.0.0

package/registry/combos/express-prisma/variants/base/src/rbac.defaults.ts

@@ -0,0 +1,195 @@
+// The permission catalog and the system roles — what a fresh database is *seeded* with, and the
+// type that keeps routes honest.
+//
+// Two different things live here, and keeping them apart is the whole point of the design:
+//
+//   1. **The catalog as a type.** `PermissionSlug` is `keyof typeof PERMISSION_CATALOG`, and
+//      `@CheckAbility(...)` takes that type rather than `string`. A route cannot demand a
+//      permission this build never defined, so "this route requires something nothing can ever
+//      grant" is a compile error rather than a 403 nobody can explain. Adding an admin route
+//      means adding its slug here first.
+//
+//   2. **The catalog as seed data.** `provisionDefaultRoles` writes these rows once and never
+//      rewrites them. From then on the database is authoritative: which role carries which
+//      permission, who holds which role, and whether a permission is active at all are rows an
+//      administrator edits, and nothing in the request path reads this file. Editing a row
+//      changes enforcement on the very next request, with no code change and no redeploy;
+//      editing this file changes only what a *new* deployment starts with.
+//
+// That is what "code declares what a route demands; the database decides who is granted it" means
+// concretely.
+//
+// Callers: `src/seed.ts` (`npm run seed`, the only bootstrap in this variant) and
+// `variants/base/test/variant-hooks.ts`.
+import type { PrismaClient } from "../generated/prisma/client.js";
+
+/** The display metadata a seeded permission carries. `group`/`order` exist so an admin console can render a stable matrix. */
+export interface PermissionSeed {
+  displayName: string;
+  description: string;
+  group: string;
+  order: number;
+}
+
+/**
+ * One slug per capability the admin API actually exposes, named `noun:verb`. Reading and writing
+ * the same noun are separate slugs; block and unblock share one, because they are a single
+ * capability used in two directions.
+ *
+ * The slug is the whole ability. `@CheckAbility("users:read")` on a route and
+ * `ability.can("users:read", ABILITY_SUBJECT)` in a client are the same string — there is no
+ * action/subject pairing to keep in sync, and no rule shape a route guard could only partially
+ * evaluate.
+ */
+export const PERMISSION_CATALOG = {
+  "users:read": { displayName: "List users", description: "GET /auth/admin/users, GET /auth/admin/users/:userId", group: "Users", order: 1 },
+  "users:block": { displayName: "Block and unblock users", description: "POST /auth/admin/users/:userId/block, .../unblock", group: "Users", order: 2 },
+  "users:manage": {
+    displayName: "Edit and delete users",
+    description: "Edit a user's profile or delete their account — PATCH /auth/admin/users/:userId, DELETE /auth/admin/users/:userId",
+    group: "Users",
+    order: 3,
+  },
+  "roles:manage": {
+    displayName: "Define roles",
+    description: "Create, edit, or delete roles and say what they carry — POST/PATCH/DELETE /auth/admin/roles(/:roleId), POST /auth/admin/roles/:roleId/permissions",
+    group: "Roles",
+    order: 1,
+  },
+  "roles:assign": {
+    displayName: "Assign roles",
+    description: "Assign and revoke a user's roles — POST /auth/admin/users/:userId/roles, .../roles/:roleSlug/revoke",
+    group: "Roles",
+    order: 2,
+  },
+  "permissions:read": { displayName: "Read the permission catalog", description: "GET /auth/admin/permissions", group: "Permissions", order: 1 },
+  "permissions:define": {
+    displayName: "Define permissions",
+    description: "Create a permission, rename it, or deactivate it — POST /auth/admin/permissions. The authority that defines all the others.",
+    group: "Permissions",
+    order: 2,
+  },
+  "permissions:grant": {
+    displayName: "Grant permissions directly",
+    description: "Grant and revoke a permission straight to a user, bypassing roles — POST /auth/admin/users/:userId/permissions, .../permissions/:slug/revoke",
+    group: "Permissions",
+    order: 3,
+  },
+  "audit-log:read": { displayName: "Read the audit log", description: "GET /auth/admin/audit-log", group: "Audit", order: 1 },
+} as const satisfies Record<string, PermissionSeed>;
+
+/**
+ * Every slug the catalog defines, as a type. This is what `@CheckAbility` takes.
+ *
+ * Deployments may invent slugs at runtime — `POST /auth/admin/permissions` accepts any string —
+ * and those work exactly like these do at the database level. What they cannot do is gate a route
+ * shipped by this library, because a route's slug is checked against this type at compile time.
+ */
+export type PermissionSlug = keyof typeof PERMISSION_CATALOG;
+
+export const PERMISSION_SLUGS = Object.keys(PERMISSION_CATALOG) as PermissionSlug[];
+
+/** Groups, in the order an admin console should render them. Derived from the catalog so it cannot drift from it. */
+export const PERMISSION_GROUP_ORDER: string[] = [...new Set(PERMISSION_SLUGS.map((slug) => PERMISSION_CATALOG[slug].group))];
+
+/** The display metadata a seeded role carries, plus what it starts out granting. */
+export interface RoleSeed {
+  slug: string;
+  displayName: string;
+  description: string;
+  /** Given to every newly signed-up user. Exactly one role should carry it. */
+  isDefault: boolean;
+  order: number;
+  permissions: readonly PermissionSlug[];
+}
+
+/**
+ * The system-defined roles. `admin` carries the whole catalog; `member` is the signup default and
+ * carries nothing, because every slug above is an administrative capability and the safe default
+ * is the empty set.
+ *
+ * Note what the names are and are not: no guard checks for the literal string "admin" — authority
+ * comes only from the permissions a role carries. Renaming `admin` here does not open a hole, it
+ * just leaves the deployment with no role that carries the catalog. And `member` is the signup
+ * default because `isDefault` says so on the row, not because any code spells "member".
+ */
+export const DEFAULT_ROLES: readonly RoleSeed[] = [
+  {
+    slug: "admin",
+    displayName: "Administrator",
+    description: "Carries every permission in the catalog.",
+    isDefault: false,
+    order: 0,
+    permissions: PERMISSION_SLUGS,
+  },
+  {
+    slug: "superadmin",
+    displayName: "Super Admin",
+    description: "Carries every permission in the catalog — same authority as admin, held by the seeded super_admin account (see SEED_SUPERADMIN_* in seed.ts).",
+    isDefault: false,
+    order: 1,
+    permissions: PERMISSION_SLUGS,
+  },
+  {
+    slug: "member",
+    displayName: "Member",
+    description: "The signup default. Carries no administrative permission.",
+    isDefault: true,
+    order: 2,
+    permissions: [],
+  },
+];
+
+/** Role slugs given to the seeded admin. `member` is included so the admin is also an ordinary user. */
+export const SEED_ADMIN_ROLES: string[] = ["admin", "member"];
+
+/** Role slugs given to the seeded super_admin. `member` is included so they're also an ordinary user. */
+export const SEED_SUPERADMIN_ROLES: string[] = ["superadmin", "member"];
+
+/** Anything that can write the catalog tables: the PrismaClient, or a `$transaction` client. */
+export type RbacWriter = Pick<PrismaClient, "permission" | "role" | "permissionRole">;
+
+/**
+ * Writes the starting catalog and roles above into `db`, which may be a transaction client — so a
+ * caller that has to provision roles atomically alongside other rows can.
+ *
+ * Idempotent and safe to run concurrently: every insert is `skipDuplicates` (`ON CONFLICT DO
+ * NOTHING`) on the natural unique key, and nothing is ever deleted or updated. Re-running is
+ * additive on purpose — a permission attached to a seeded role by hand survives it, and so does a
+ * permission an administrator deactivated or renamed.
+ */
+export async function provisionDefaultRoles(db: RbacWriter): Promise<void> {
+  await db.permission.createMany({
+    data: PERMISSION_SLUGS.map((slug) => ({
+      slug,
+      name: PERMISSION_CATALOG[slug].displayName,
+      displayName: PERMISSION_CATALOG[slug].displayName,
+      description: PERMISSION_CATALOG[slug].description,
+      group: PERMISSION_CATALOG[slug].group,
+      groupOrder: PERMISSION_GROUP_ORDER.indexOf(PERMISSION_CATALOG[slug].group),
+      order: PERMISSION_CATALOG[slug].order,
+    })),
+    skipDuplicates: true,
+  });
+  const permissions = await db.permission.findMany({ where: { slug: { in: PERMISSION_SLUGS } }, select: { id: true, slug: true } });
+  const permissionId = new Map(permissions.map((p) => [p.slug, p.id]));
+
+  await db.role.createMany({
+    data: DEFAULT_ROLES.map((role) => ({
+      slug: role.slug,
+      name: role.displayName,
+      displayName: role.displayName,
+      description: role.description,
+      isDefault: role.isDefault,
+      order: role.order,
+    })),
+    skipDuplicates: true,
+  });
+  const roles = await db.role.findMany({ where: { slug: { in: DEFAULT_ROLES.map((r) => r.slug) } }, select: { id: true, slug: true } });
+  const seedBySlug = new Map(DEFAULT_ROLES.map((role) => [role.slug, role]));
+
+  const rolePermissions = roles.flatMap((role) =>
+    (seedBySlug.get(role.slug)?.permissions ?? []).map((slug) => ({ roleId: role.id, permissionId: permissionId.get(slug)! })),
+  );
+  if (rolePermissions.length) await db.permissionRole.createMany({ data: rolePermissions, skipDuplicates: true });
+}

package/registry/combos/express-prisma/variants/base/src/rbac.repository.ts

@@ -0,0 +1,484 @@
+import { resolvePermissions } from "@/lib/auth/core/rbac.js";
+import { Prisma, PrismaClient } from "../generated/prisma/client.js";
+import { HttpError } from "./http-error.js";
+import { buildPageMeta, normalizeLimit, normalizePage, type Paginated } from "./pagination.js";
+import { PermissionCache } from "./permission-cache.js";
+import { toId, toIdOrNull } from "./id.helper.js";
+
+export interface UserSummary {
+  id: string;
+  uuid: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+  displayName: string | null;
+  phone: string | null;
+  username: string | null;
+  photo: string | null;
+  lastLogin: string | null;
+  blocked: boolean;
+  isActive: boolean;
+  twoFactorEnabled: boolean;
+  roles: string[];
+  createdBy: string | null;
+  updatedBy: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface UserListFilter {
+  search?: string;
+  page?: number;
+  limit?: number;
+}
+
+export type UserListResult = Paginated<UserSummary>;
+
+const USER_ROLES_INCLUDE = { roles: { select: { role: { select: { slug: true } } } } } as const;
+
+/** A `User` row as `findUnique`/`findMany` return it with its roles joined in. */
+export type UserRow = Prisma.UserGetPayload<{ include: typeof USER_ROLES_INCLUDE }>;
+
+/**
+ * Shapes a raw row into the wire DTO — bigint id to string, `Date` to ISO, the roles relation
+ * to a flat slug list. Exported so callers that need the collection (paginated `listUsers`) can
+ * apply it themselves at the service layer instead of the repository doing it on their behalf.
+ */
+export function toUserSummary(row: UserRow): UserSummary {
+  return {
+    id: row.id.toString(),
+    uuid: row.uuid,
+    email: row.email,
+    firstName: row.firstName,
+    lastName: row.lastName,
+    displayName: row.displayName,
+    phone: row.phone,
+    username: row.username,
+    photo: row.photo,
+    lastLogin: row.lastLogin?.toISOString() ?? null,
+    blocked: row.blocked,
+    isActive: row.isActive,
+    twoFactorEnabled: row.twoFactorEnabled,
+    roles: row.roles.map((r) => r.role.slug).sort(),
+    createdBy: row.createdBy?.toString() ?? null,
+    updatedBy: row.updatedBy?.toString() ?? null,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+/** A `Permission` row as the catalog endpoints return it. */
+export interface PermissionSummary {
+  id: string;
+  slug: string;
+  name: string;
+  displayName: string;
+  description: string | null;
+  group: string;
+  groupOrder: number;
+  order: number;
+  isActive: boolean;
+}
+
+export interface PermissionInput {
+  slug: string;
+  name?: string;
+  displayName?: string;
+  description?: string | null;
+  group?: string;
+  groupOrder?: number;
+  order?: number;
+  isActive?: boolean;
+}
+
+export interface RoleSummary {
+  id: string;
+  slug: string;
+  name: string;
+  displayName: string;
+  isDefault: boolean;
+  isActive: boolean;
+}
+
+const PERMISSION_SELECT = {
+  id: true,
+  slug: true,
+  name: true,
+  displayName: true,
+  description: true,
+  group: true,
+  groupOrder: true,
+  order: true,
+  isActive: true,
+} as const;
+
+const ROLE_SELECT = { id: true, slug: true, name: true, displayName: true, isDefault: true, isActive: true } as const;
+
+export class RbacRepository {
+  constructor(
+    private readonly prisma: PrismaClient,
+    private readonly cache: PermissionCache,
+  ) {}
+
+  // Every write below ends by bumping a version counter, and which counter is the whole design:
+  // a change to one user's roles or grants bumps only that user (`invalidateSubject`), while a
+  // change to what a role carries, or to whether a permission is active, bumps everyone
+  // (`invalidatePolicy`) — because those genuinely do affect everyone who holds the role, and
+  // enumerating them is the fan-out this scheme exists to avoid.
+
+  /**
+   * The hot path: every authenticated request runs this once.
+   *
+   * One call, walking `user → role_user → roles → permission_role → permissions` and
+   * `user → permission_user → permissions`. The access token carries no authorization at all, so
+   * this is the only place a caller's authority is decided, and a grant or a revocation therefore
+   * takes effect on their **next request** rather than their next token.
+   *
+   * Cost is constant in the number of users: every hop is an indexed read on a primary key or a
+   * composite join-table key, and the row counts involved are "roles this user holds" and
+   * "permissions those roles carry" — a handful, whatever the size of the deployment.
+   *
+   * `isActive: false` on a role or a permission takes it out of the answer here, which is what
+   * makes deactivating either one enforcement-changing without unpicking any grant.
+   */
+  async resolveAuthzContext(userId: string): Promise<{ roles: string[]; permissions: string[] }> {
+    const user = await this.prisma.user.findUnique({
+      where: { id: toId(userId), isDeleted: false },
+      select: {
+        roles: {
+          where: { role: { isActive: true, isDeleted: false } },
+          select: {
+            role: {
+              select: {
+                slug: true,
+                permissions: { where: { permission: { isActive: true, isDeleted: false } }, select: { permission: { select: { slug: true } } } },
+              },
+            },
+          },
+        },
+        permissions: { where: { permission: { isActive: true, isDeleted: false } }, select: { permission: { select: { slug: true } } } },
+      },
+    });
+    if (!user) return { roles: [], permissions: [] };
+
+    const rolePermissions = user.roles.flatMap((roleUser) => roleUser.role.permissions.map((pr) => pr.permission.slug));
+    const directPermissions = user.permissions.map((pu) => pu.permission.slug);
+
+    return {
+      roles: user.roles.map((roleUser) => roleUser.role.slug).sort(),
+      permissions: resolvePermissions(rolePermissions, directPermissions),
+    };
+  }
+
+  /**
+   * Newest-first, page-paginated; `search` matches an email substring. Returns raw rows, not
+   * `UserSummary` — shaping each row is the caller's job (`AuthService.listUsers` does it via
+   * `toUserSummary`), so this method's only responsibility is the query and the page envelope.
+   */
+  async listUsers(filter: UserListFilter = {}): Promise<Paginated<UserRow>> {
+    const page = normalizePage(filter.page);
+    const limit = normalizeLimit(filter.limit);
+    const where = {
+      isDeleted: false,
+      email: filter.search ? { contains: filter.search, mode: "insensitive" as const } : undefined,
+    };
+
+    const [rows, total] = await this.prisma.$transaction([
+      this.prisma.user.findMany({
+        where,
+        include: USER_ROLES_INCLUDE,
+        orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+        take: limit,
+        skip: (page - 1) * limit,
+      }),
+      this.prisma.user.count({ where }),
+    ]);
+
+    return { items: rows, meta: buildPageMeta(page, limit, total) };
+  }
+
+  async getUser(userId: string): Promise<UserSummary> {
+    const row = await this.prisma.user.findUnique({
+      where: { id: toId(userId), isDeleted: false },
+      include: USER_ROLES_INCLUDE,
+    });
+    if (!row) throw new HttpError(404, `user "${userId}" not found`);
+    return toUserSummary(row);
+  }
+
+  /**
+   * An administrator provisioning an account directly, as distinct from `/auth/signup` — the row
+   * is otherwise identical, right down to which roles a bare account gets by default.
+   */
+  async createUser(
+    input: {
+      email: string;
+      passwordHash: string;
+      firstName?: string;
+      lastName?: string;
+      displayName?: string;
+      phone?: string;
+      username?: string;
+      roles?: string[];
+    },
+    actorUserId: string | null,
+  ): Promise<UserSummary> {
+    const existing = await this.prisma.user.findUnique({ where: { email: input.email } });
+    if (existing) throw new HttpError(409, "email already registered");
+
+    const user = await this.prisma.user.create({
+      data: {
+        email: input.email,
+        passwordHash: input.passwordHash,
+        firstName: input.firstName,
+        lastName: input.lastName,
+        displayName: input.displayName,
+        phone: input.phone,
+        username: input.username,
+        createdBy: toIdOrNull(actorUserId),
+      },
+    });
+
+    if (input.roles && input.roles.length > 0) {
+      const roles = await this.prisma.role.findMany({ where: { slug: { in: input.roles }, isActive: true, isDeleted: false }, select: { id: true } });
+      if (roles.length > 0) {
+        await this.prisma.roleUser.createMany({ data: roles.map((role) => ({ userId: user.id, roleId: role.id })), skipDuplicates: true });
+        await this.cache.invalidateSubject(user.id.toString());
+      }
+    } else {
+      await this.assignDefaultRoles(user.id);
+    }
+
+    return this.getUser(user.id.toString());
+  }
+
+  // Profile fields only — email is the login identifier and stays out of this endpoint to avoid
+  // uniqueness/re-verification concerns a general "edit profile" screen shouldn't have to handle.
+  async updateUser(
+    userId: string,
+    input: { firstName?: string | null; lastName?: string | null; displayName?: string | null; phone?: string | null; username?: string | null; photo?: string | null },
+    actorUserId: string | null,
+  ): Promise<UserSummary> {
+    const userIdBig = toId(userId);
+    const existing = await this.prisma.user.findUnique({ where: { id: userIdBig, isDeleted: false }, select: { id: true } });
+    if (!existing) throw new HttpError(404, `user "${userId}" not found`);
+    await this.prisma.user.update({ where: { id: userIdBig }, data: { ...input, updatedBy: toIdOrNull(actorUserId) } });
+    return this.getUser(userId);
+  }
+
+  // Soft-delete, matching every other table's `isDeleted`/`deletedAt`/`deletedBy`/`deletedReason`
+  // pattern — the row survives for audit purposes, it just stops appearing in listings and can
+  // no longer authenticate (mirrors how `block` already disables login without removing the row).
+  async deleteUser(userId: string, actorUserId: string | null, reason?: string): Promise<void> {
+    const userIdBig = toId(userId);
+    const existing = await this.prisma.user.findUnique({ where: { id: userIdBig, isDeleted: false }, select: { id: true } });
+    if (!existing) throw new HttpError(404, `user "${userId}" not found`);
+    await this.prisma.user.update({
+      where: { id: userIdBig },
+      data: { isDeleted: true, deletedAt: new Date(), deletedBy: toIdOrNull(actorUserId), deletedReason: reason ?? null },
+    });
+    await this.cache.invalidateSubject(userId);
+  }
+
+  async updateRole(
+    roleId: string,
+    input: { name?: string; displayName?: string; description?: string | null; isActive?: boolean },
+    actorUserId: string | null,
+  ): Promise<RoleSummary> {
+    const roleIdBig = toId(roleId);
+    const existing = await this.prisma.role.findUnique({ where: { id: roleIdBig, isDeleted: false }, select: { id: true } });
+    if (!existing) throw new HttpError(404, "role not found");
+    const role = await this.prisma.role.update({
+      where: { id: roleIdBig },
+      data: { ...input, updatedBy: toIdOrNull(actorUserId) },
+      select: ROLE_SELECT,
+    });
+    // Renaming/deactivating changes what every holder resolves to.
+    await this.cache.invalidatePolicy();
+    return { ...role, id: role.id.toString() };
+  }
+
+  // Soft-delete. The `role_user`/`permission_role` rows pointing at it are left in place — a
+  // deleted role simply stops being returned by `listRoles`/`resolveAuthzContext`, rather than
+  // cascading a delete that would silently strip a user's other roles' foreign keys.
+  async deleteRole(roleId: string, actorUserId: string | null, reason?: string): Promise<void> {
+    const roleIdBig = toId(roleId);
+    const existing = await this.prisma.role.findUnique({ where: { id: roleIdBig, isDeleted: false }, select: { id: true } });
+    if (!existing) throw new HttpError(404, "role not found");
+    await this.prisma.role.update({
+      where: { id: roleIdBig },
+      data: { isDeleted: true, deletedAt: new Date(), deletedBy: toIdOrNull(actorUserId), deletedReason: reason ?? null },
+    });
+    await this.cache.invalidatePolicy();
+  }
+
+  // ---- the catalog itself ----
+
+  /** Every permission this deployment defines, in the order an admin console should render them. */
+  async listPermissions(): Promise<PermissionSummary[]> {
+    const rows = await this.prisma.permission.findMany({
+      where: { isDeleted: false },
+      select: PERMISSION_SELECT,
+      orderBy: [{ groupOrder: "asc" }, { group: "asc" }, { order: "asc" }, { slug: "asc" }],
+    });
+    return rows.map((row) => ({ ...row, id: row.id.toString() }));
+  }
+
+  /**
+   * Defines a permission, or edits one. The write path for "the catalog is editable in the
+   * database": a deployment can add a capability of its own, rename one for the console, or set
+   * `isActive: false` to take an existing one out of every ability it appears in — all without a
+   * deploy, and all visible on the very next request.
+   *
+   * Upserted on `slug`, which stays the stable identifier grants and revocations use, so renaming
+   * `name`/`displayName` never breaks a grant.
+   */
+  async upsertPermission(input: PermissionInput, actorUserId: string | null): Promise<PermissionSummary> {
+    const shared = {
+      name: input.name,
+      displayName: input.displayName,
+      description: input.description,
+      group: input.group,
+      groupOrder: input.groupOrder,
+      order: input.order,
+      isActive: input.isActive,
+      updatedBy: toIdOrNull(actorUserId),
+    };
+    const permission = await this.prisma.permission.upsert({
+      where: { slug: input.slug },
+      create: {
+        slug: input.slug,
+        ...shared,
+        name: input.name ?? input.displayName ?? input.slug,
+        displayName: input.displayName ?? input.slug,
+        group: input.group ?? "Custom",
+        createdBy: toIdOrNull(actorUserId),
+      },
+      // Only the fields the caller sent are written; `undefined` leaves a column alone, so a
+      // partial edit cannot blank out metadata it did not mention.
+      update: shared,
+      select: PERMISSION_SELECT,
+    });
+    // `isActive` can change here, and it changes what every holder resolves to.
+    await this.cache.invalidatePolicy();
+    return { ...permission, id: permission.id.toString() };
+  }
+
+  async listRoles(): Promise<RoleSummary[]> {
+    const rows = await this.prisma.role.findMany({ where: { isDeleted: false }, select: ROLE_SELECT, orderBy: [{ order: "asc" }, { slug: "asc" }] });
+    return rows.map((row) => ({ ...row, id: row.id.toString() }));
+  }
+
+  async createRole(
+    input: { slug: string; name?: string; displayName?: string; description?: string | null },
+    actorUserId: string | null,
+  ): Promise<RoleSummary> {
+    const role = await this.prisma.role.create({
+      data: {
+        slug: input.slug,
+        name: input.name ?? input.displayName ?? input.slug,
+        displayName: input.displayName ?? input.slug,
+        description: input.description ?? null,
+        createdBy: toIdOrNull(actorUserId),
+        updatedBy: toIdOrNull(actorUserId),
+      },
+      select: ROLE_SELECT,
+    });
+    return { ...role, id: role.id.toString() };
+  }
+
+  /**
+   * A permission slug this deployment never defined is created on the spot, inactive-safe: it
+   * exists, it can be granted, and it opens nothing until a route names it. That is the same
+   * closed-catalog property the routes always had — `@CheckAbility` only accepts slugs from
+   * `rbac.defaults.ts`, so an invented slug cannot gate anything shipped by this library.
+   */
+  async attachPermissionToRole(roleId: string, permissionSlug: string, actorUserId: string | null): Promise<void> {
+    const roleIdBig = toId(roleId);
+    const role = await this.prisma.role.findUnique({ where: { id: roleIdBig, isDeleted: false }, select: { id: true } });
+    if (!role) throw new HttpError(404, "role not found");
+
+    const permission = await this.ensurePermission(permissionSlug, actorUserId);
+    await this.prisma.permissionRole.upsert({
+      where: { permissionId_roleId: { permissionId: permission.id, roleId: roleIdBig } },
+      create: { permissionId: permission.id, roleId: roleIdBig },
+      update: {},
+    });
+    await this.cache.invalidatePolicy(); // everyone holding this role is affected
+  }
+
+  async assignRoleToUser(userId: string, roleSlug: string): Promise<void> {
+    const userIdBig = toId(userId);
+    const role = await this.prisma.role.findUnique({ where: { slug: roleSlug }, select: { id: true } });
+    if (!role) throw new HttpError(404, `role "${roleSlug}" not found`);
+
+    await this.prisma.user.findUniqueOrThrow({ where: { id: userIdBig }, select: { id: true } });
+    await this.prisma.roleUser.upsert({
+      where: { userId_roleId: { userId: userIdBig, roleId: role.id } },
+      create: { userId: userIdBig, roleId: role.id },
+      update: {},
+    });
+    await this.cache.invalidateSubject(userId);
+  }
+
+  async revokeRoleFromUser(userId: string, roleSlug: string): Promise<void> {
+    const role = await this.prisma.role.findUnique({ where: { slug: roleSlug }, select: { id: true } });
+    if (!role) return;
+    await this.prisma.roleUser.deleteMany({ where: { userId: toId(userId), roleId: role.id } });
+    await this.cache.invalidateSubject(userId);
+  }
+
+  /**
+   * The roles a brand-new user starts with — the rows flagged `isDefault`, not a string literal.
+   * Called at signup and for a user created by an OAuth login who holds no roles at all, so it
+   * can never re-add a role an administrator has revoked from an existing user.
+   *
+   * Takes bigint directly: every caller already has the user row's id in hand from its own
+   * Prisma lookup, so there's no string to convert from.
+   */
+  async assignDefaultRoles(userId: bigint): Promise<void> {
+    const defaults = await this.prisma.role.findMany({ where: { isDefault: true, isActive: true, isDeleted: false }, select: { id: true } });
+    if (!defaults.length) return;
+    await this.prisma.roleUser.createMany({ data: defaults.map((role) => ({ userId, roleId: role.id })), skipDuplicates: true });
+    await this.cache.invalidateSubject(userId.toString());
+  }
+
+  async hasAnyRole(userId: bigint): Promise<boolean> {
+    return (await this.prisma.roleUser.count({ where: { userId } })) > 0;
+  }
+
+  async grantPermissionToUser(userId: string, permissionSlug: string, actorUserId: string | null): Promise<void> {
+    const userIdBig = toId(userId);
+    const permission = await this.ensurePermission(permissionSlug, actorUserId);
+    await this.prisma.permissionUser.upsert({
+      where: { userId_permissionId: { userId: userIdBig, permissionId: permission.id } },
+      create: { userId: userIdBig, permissionId: permission.id },
+      update: {},
+    });
+    await this.cache.invalidateSubject(userId);
+  }
+
+  async revokePermissionFromUser(userId: string, permissionSlug: string): Promise<void> {
+    const permission = await this.prisma.permission.findUnique({ where: { slug: permissionSlug }, select: { id: true } });
+    if (!permission) return;
+    await this.prisma.permissionUser.deleteMany({ where: { userId: toId(userId), permissionId: permission.id } });
+    await this.cache.invalidateSubject(userId);
+  }
+
+  /** Bumped by `AuthService.block`: a blocked account should not keep serving a warm entry either, even though the block itself is enforced on the authentication path. */
+  async invalidateUser(userId: string): Promise<void> {
+    await this.cache.invalidateSubject(userId);
+  }
+
+  /** Creates the row for a slug granted before anyone defined it; leaves an existing definition alone. */
+  private async ensurePermission(slug: string, actorUserId: string | null): Promise<{ id: bigint }> {
+    const existing = await this.prisma.permission.findUnique({ where: { slug }, select: { id: true } });
+    return (
+      existing ??
+      (await this.prisma.permission.create({
+        data: { slug, name: slug, displayName: slug, group: "Custom", createdBy: toIdOrNull(actorUserId), updatedBy: toIdOrNull(actorUserId) },
+        select: { id: true },
+      }))
+    );
+  }
+}