@simple-auth-kit/cli 1.0.0

package/registry/combos/nestjs-drizzle/variants/workspaces/drizzle/meta/_journal.json

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1786380173224,
+      "tag": "0000_init",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1786461179055,
+      "tag": "0001_add_is_active_field",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1786593633464,
+      "tag": "0002_calm_tyger_tiger",
+      "breakpoints": true
+    }
+  ]
+}

package/registry/combos/nestjs-drizzle/variants/workspaces/src/admin.controller.ts

@@ -0,0 +1,383 @@
+import { BadRequestException, Body, Controller, Delete, ForbiddenException, Get, Inject, Ip, Param, Patch, Post, Query, Req, UseGuards } from "@nestjs/common";
+import { ApiBearerAuth, ApiBody, ApiHeader, ApiOperation, ApiParam, ApiQuery, ApiResponse, ApiTags } from "@nestjs/swagger";
+import type { Request } from "express";
+import { AbilityGuard } from "./ability.guard.js";
+import { AuthGuard } from "./auth.guard.js";
+import { AuthService } from "./auth.service.js";
+import { WORKSPACE_HEADER, WorkspaceGuard } from "./authz.guard.js";
+import { CheckAbility } from "./route-tiers.js";
+import { WorkspaceRepository } from "./workspace.repository.js";
+import { hashPassword } from "@/lib/auth/core/crypto.js";
+import {
+  AssignRoleDto,
+  AttachPermissionDto,
+  CreateRoleDto,
+  CreateUserDto,
+  DefinePermissionDto,
+  DeleteReasonDto,
+  GrantPermissionDto,
+  OkResponseDto,
+  PermissionListResponseDto,
+  PermissionSummaryDto,
+  RoleListResponseDto,
+  RoleSummaryDto,
+  UpdateRoleDto,
+  UpdateUserDto,
+} from "./dto/auth.dto.js";
+import { AuditLogListResponseDto, UserListResponseDto, UserSummaryDto } from "./dto/admin.dto.js";
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.length === 0) throw new BadRequestException(`${field} is required`);
+  return value;
+}
+
+const optionalString = (value: unknown): string | undefined => (typeof value === "string" ? value : undefined);
+
+/**
+ * Administration *of one workspace*, and of nothing else. Authority is a permission, never a role
+ * name: `WorkspaceGuard` resolves the caller's membership of the workspace named by the
+ * `X-Workspace-Id` header into the roles and permissions that membership carries *there*, builds
+ * the CASL ability from them, and `AbilityGuard` checks each route's `@CheckAbility` against it —
+ * and every handler passes the same resolved context down, so the query itself is scoped too.
+ *
+ * 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 controller and takes
+ * effect on the next request. `GET /auth/me` returns the caller's slugs *for the workspace they
+ * named*, and a console rebuilds the same ability from them with the same function the guard used.
+ *
+ * Two consequences worth being explicit about. An admin of workspace A calling with workspace B's
+ * id is rejected by the guard, because the context it resolves is B's membership — the check is
+ * workspace-scoped by construction, not by a second check. And there is no role-based bypass:
+ * holding a role called "admin" that carries no permissions in this workspace gets exactly the
+ * same 403 as holding no role at all.
+ */
+@ApiTags("auth")
+@Controller("auth/admin")
+@ApiBearerAuth()
+@ApiHeader({ name: WORKSPACE_HEADER, required: true, description: "The workspace this request administers. The caller must be an admin member of it." })
+@UseGuards(AuthGuard, WorkspaceGuard, AbilityGuard)
+export class AdminController {
+  constructor(
+    @Inject(AuthService) private readonly auth: AuthService,
+    @Inject(WorkspaceRepository) private readonly workspaces: WorkspaceRepository,
+  ) {}
+
+  @Get("users")
+  @CheckAbility("users:read")
+  @ApiOperation({ summary: "[admin] List the members of this workspace" })
+  @ApiQuery({ name: "search", required: false, description: "Email substring match" })
+  @ApiQuery({ name: "page", required: false, description: "1-indexed. Defaults to 1." })
+  @ApiQuery({ name: "limit", required: false, description: "Defaults to 25, capped at 100." })
+  @ApiResponse({ status: 200, type: UserListResponseDto })
+  async listUsers(@Req() req: Request, @Query("search") search?: string, @Query("page") page?: string, @Query("limit") limit?: string) {
+    return this.auth.listUsers(req.authz!, { search, page: page ? Number(page) : undefined, limit: limit ? Number(limit) : undefined });
+  }
+
+  @Post("users")
+  @CheckAbility("users:manage")
+  @ApiOperation({
+    summary: "[admin] Create a user and add them to this workspace",
+    description: "No invitation email — the account is usable immediately with the password given here.",
+  })
+  @ApiBody({ type: CreateUserDto })
+  @ApiResponse({ status: 201, type: UserSummaryDto })
+  async createUser(@Body() body: Record<string, unknown>, @Req() req: Request) {
+    const passwordHash = await hashPassword(requireString(body.password, "password"));
+    const member = await this.workspaces.createMember(
+      req.authz!.workspaceId,
+      {
+        email: requireString(body.email, "email"),
+        passwordHash,
+        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,
+    );
+    return this.auth.getUser(req.authz!, member.userId);
+  }
+
+  @Get("users/:userId")
+  @CheckAbility("users:read")
+  @ApiOperation({ summary: "[admin] Fetch a single member's profile" })
+  @ApiParam({ name: "userId" })
+  @ApiResponse({ status: 200, type: UserSummaryDto })
+  async getUser(@Param("userId") userId: string, @Req() req: Request) {
+    return this.auth.getUser(req.authz!, userId);
+  }
+
+  @Patch("users/:userId")
+  @CheckAbility("users:manage")
+  @ApiOperation({ summary: "[admin] Edit a member's profile", description: "Profile fields only — email is the login identifier and is not editable here." })
+  @ApiParam({ name: "userId" })
+  @ApiBody({ type: UpdateUserDto })
+  @ApiResponse({ status: 200, type: UserSummaryDto })
+  async updateUser(@Param("userId") userId: string, @Body() body: Record<string, unknown>, @Req() req: Request) {
+    return this.auth.updateUser(
+      req.authz!,
+      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,
+    );
+  }
+
+  @Delete("users/:userId")
+  @CheckAbility("users:manage")
+  @ApiOperation({
+    summary: "[admin] Delete a member's account",
+    description:
+      "Soft-delete: the row survives for audit purposes, stops appearing in listings, and can no longer authenticate. " +
+      "This disables the account across every workspace it belongs to, not just this one — the same reach `block` already has.",
+  })
+  @ApiParam({ name: "userId" })
+  @ApiBody({ type: DeleteReasonDto, required: false })
+  @ApiResponse({ status: 200, type: OkResponseDto })
+  async deleteUser(@Param("userId") userId: string, @Body() body: Record<string, unknown>, @Req() req: Request) {
+    if (userId === req.auth!.sub) throw new ForbiddenException("cannot delete your own account");
+    await this.auth.deleteUser(req.authz!, userId, req.auth!.sub, optionalString(body?.reason));
+    return { ok: true };
+  }
+
+  @Get("audit-log")
+  @CheckAbility("audit-log:read")
+  @ApiOperation({ summary: "[admin] List this workspace's audit log entries, newest first" })
+  @ApiQuery({ name: "userId", required: false })
+  @ApiQuery({ name: "action", required: false, description: "AuditEvent discriminant, e.g. 'role_assigned'" })
+  @ApiQuery({ name: "since", required: false, description: "ISO 8601 timestamp" })
+  @ApiQuery({ name: "until", required: false, description: "ISO 8601 timestamp" })
+  @ApiQuery({ name: "page", required: false, description: "1-indexed. Defaults to 1." })
+  @ApiQuery({ name: "limit", required: false, description: "Defaults to 25, capped at 100." })
+  @ApiResponse({ status: 200, type: AuditLogListResponseDto })
+  async listAuditLog(
+    @Req() req: Request,
+    @Query("userId") userId?: string,
+    @Query("action") action?: string,
+    @Query("since") since?: string,
+    @Query("until") until?: string,
+    @Query("page") page?: string,
+    @Query("limit") limit?: string,
+  ) {
+    return this.auth.listAuditLog(req.authz!, {
+      userId,
+      action,
+      since,
+      until,
+      page: page ? Number(page) : undefined,
+      limit: limit ? Number(limit) : undefined,
+    });
+  }
+
+  @Get("permissions")
+  @CheckAbility("permissions:read")
+  @ApiOperation({
+    summary: "[admin] List the permission catalog",
+    description:
+      "Grouped and ordered for a permission matrix. The catalog is global, like the Permission table: what is scoped to this workspace is which of its roles and memberships point at each row.",
+  })
+  @ApiResponse({ status: 200, type: PermissionListResponseDto })
+  async listPermissions() {
+    return this.auth.listPermissions();
+  }
+
+  @Post("permissions")
+  @CheckAbility("permissions:define")
+  @ApiOperation({
+    summary: "[admin] Define or edit a permission",
+    description:
+      "Upserted on `slug`, which is the stable identifier grants and revocations use — renaming the display name never breaks a grant. " +
+      "`isActive: false` takes the permission out of every ability that carries it, in one write, effective on the next request — in every workspace.",
+  })
+  @ApiBody({ type: DefinePermissionDto })
+  @ApiResponse({ status: 201, type: PermissionSummaryDto })
+  async definePermission(@Body() body: Record<string, unknown>, @Req() req: Request) {
+    return this.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,
+    );
+  }
+
+  @Get("roles")
+  @CheckAbility("roles:manage")
+  @ApiOperation({ summary: "[admin] List the roles this workspace defines" })
+  @ApiResponse({ status: 200, type: RoleListResponseDto })
+  async listRoles(@Req() req: Request) {
+    return this.auth.listRoles(req.authz!);
+  }
+
+  @Post("roles")
+  @CheckAbility("roles:manage")
+  @ApiOperation({ summary: "[admin] Create a role in this workspace" })
+  @ApiBody({ type: CreateRoleDto })
+  @ApiResponse({ status: 201, type: RoleSummaryDto })
+  async createRole(@Body() body: Record<string, unknown>, @Req() req: Request) {
+    return this.auth.createRole(
+      req.authz!,
+      {
+        slug: requireString(body.slug, "slug"),
+        name: optionalString(body.name),
+        displayName: optionalString(body.displayName),
+        description: optionalString(body.description) ?? null,
+      },
+      req.auth!.sub,
+    );
+  }
+
+  @Patch("roles/:roleId")
+  @CheckAbility("roles:manage")
+  @ApiOperation({ summary: "[admin] Edit one of this workspace's roles" })
+  @ApiParam({ name: "roleId" })
+  @ApiBody({ type: UpdateRoleDto })
+  @ApiResponse({ status: 200, type: RoleSummaryDto })
+  async updateRole(@Param("roleId") roleId: string, @Body() body: Record<string, unknown>, @Req() req: Request) {
+    return this.auth.updateRole(
+      req.authz!,
+      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,
+    );
+  }
+
+  @Delete("roles/:roleId")
+  @CheckAbility("roles:manage")
+  @ApiOperation({
+    summary: "[admin] Delete one of this workspace's roles",
+    description: "Soft-delete: existing assignments are left in place rather than cascade-deleted, and the role simply stops being resolved.",
+  })
+  @ApiParam({ name: "roleId" })
+  @ApiBody({ type: DeleteReasonDto, required: false })
+  @ApiResponse({ status: 200, type: OkResponseDto })
+  async deleteRole(@Param("roleId") roleId: string, @Body() body: Record<string, unknown>, @Req() req: Request) {
+    await this.auth.deleteRole(req.authz!, roleId, req.auth!.sub, optionalString(body?.reason));
+    return { ok: true };
+  }
+
+  @Post("roles/:roleId/permissions")
+  @CheckAbility("roles:manage")
+  @ApiOperation({ summary: "[admin] Attach a permission to one of this workspace's roles" })
+  @ApiParam({ name: "roleId" })
+  @ApiBody({ type: AttachPermissionDto })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async attachPermissionToRole(@Param("roleId") roleId: string, @Body() body: Record<string, unknown>, @Req() req: Request) {
+    await this.auth.attachPermissionToRole(req.authz!, roleId, requireString(body.permission, "permission"), req.auth!.sub);
+    return { ok: true };
+  }
+
+  @Post("users/:userId/roles")
+  @CheckAbility("roles:assign")
+  @ApiOperation({ summary: "[admin] Assign a role to a member of this workspace" })
+  @ApiParam({ name: "userId" })
+  @ApiBody({ type: AssignRoleDto })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async assignRole(@Param("userId") userId: string, @Body() body: Record<string, unknown>, @Req() req: Request) {
+    await this.auth.assignRole(req.authz!, userId, requireString(body.role, "role"));
+    return { ok: true };
+  }
+
+  @Post("users/:userId/roles/:roleSlug/revoke")
+  @CheckAbility("roles:assign")
+  @ApiOperation({ summary: "[admin] Revoke a role from a member of this workspace" })
+  @ApiParam({ name: "userId" })
+  @ApiParam({ name: "roleSlug" })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async revokeRole(@Param("userId") userId: string, @Param("roleSlug") roleSlug: string, @Req() req: Request) {
+    // Revoking your own `admin` would strip the very permission that authorised the call. In a
+    // workspace there is no way back in afterwards, so the route refuses it the same way
+    // self-block does. Assigning to yourself is fine; it can't lock anyone out.
+    if (userId === req.auth!.sub) throw new ForbiddenException("cannot change your own roles");
+    await this.auth.revokeRole(req.authz!, userId, roleSlug);
+    return { ok: true };
+  }
+
+  @Post("users/:userId/permissions")
+  @CheckAbility("permissions:grant")
+  @ApiOperation({ summary: "[admin] Grant a permission directly to a member, bypassing roles", description: "The grant is scoped to this workspace." })
+  @ApiParam({ name: "userId" })
+  @ApiBody({ type: GrantPermissionDto })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async grantPermission(@Param("userId") userId: string, @Body() body: Record<string, unknown>, @Req() req: Request) {
+    await this.auth.grantPermission(req.authz!, userId, requireString(body.permission, "permission"), req.auth!.sub);
+    return { ok: true };
+  }
+
+  @Post("users/:userId/permissions/:permissionSlug/revoke")
+  @CheckAbility("permissions:grant")
+  @ApiOperation({ summary: "[admin] Revoke a direct permission grant from a member" })
+  @ApiParam({ name: "userId" })
+  @ApiParam({ name: "permissionSlug" })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async revokePermission(@Param("userId") userId: string, @Param("permissionSlug") permissionSlug: string, @Req() req: Request) {
+    await this.auth.revokePermission(req.authz!, userId, permissionSlug);
+    return { ok: true };
+  }
+
+  @Post("users/:userId/block")
+  @CheckAbility("users:block")
+  @ApiOperation({ summary: "[admin] Block a member, revoking all their sessions immediately",
+    description: "Blocking disables the whole account, so it is only allowed against a member of the workspace you administer." })
+  @ApiParam({ name: "userId" })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async block(@Param("userId") userId: string, @Req() req: Request, @Ip() ip: string) {
+    if (userId === req.auth!.sub) throw new ForbiddenException("cannot block your own account");
+    await this.auth.block(req.authz!, userId, { userId: req.auth!.sub, ip });
+    return { ok: true };
+  }
+
+  @Post("users/:userId/unblock")
+  @CheckAbility("users:block")
+  @ApiOperation({ summary: "[admin] Unblock a member" })
+  @ApiParam({ name: "userId" })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async unblock(@Param("userId") userId: string, @Req() req: Request) {
+    await this.auth.unblock(req.authz!, userId, { userId: req.auth!.sub, ip: req.ip });
+    return { ok: true };
+  }
+
+  @Post("users/:userId/deactivate")
+  @CheckAbility("users:block")
+  @ApiOperation({
+    summary: "[admin] Deactivate a member, revoking all their sessions immediately",
+    description: "Distinct from block/unblock — a routine administrative toggle, not a security action. Both independently deny login.",
+  })
+  @ApiParam({ name: "userId" })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async deactivate(@Param("userId") userId: string, @Req() req: Request, @Ip() ip: string) {
+    if (userId === req.auth!.sub) throw new ForbiddenException("cannot deactivate your own account");
+    await this.auth.deactivate(req.authz!, userId, { userId: req.auth!.sub, ip });
+    return { ok: true };
+  }
+
+  @Post("users/:userId/activate")
+  @CheckAbility("users:block")
+  @ApiOperation({ summary: "[admin] Reactivate a member" })
+  @ApiParam({ name: "userId" })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async activate(@Param("userId") userId: string, @Req() req: Request, @Ip() ip: string) {
+    await this.auth.activate(req.authz!, userId, { userId: req.auth!.sub, ip });
+    return { ok: true };
+  }
+}

package/registry/combos/nestjs-drizzle/variants/workspaces/src/audit-log.repository.ts

@@ -0,0 +1,102 @@
+import { Inject, Injectable } from "@nestjs/common";
+import { and, count, desc, eq, gte, lte, type SQL } from "drizzle-orm";
+import type { AuditEvent } from "@/lib/auth/core/types.js";
+import { DRIZZLE_DB, type Database } from "./db.js";
+import { buildPageMeta, normalizeLimit, normalizePage, type Paginated } from "./pagination.js";
+import { auditLogs } from "./schema.js";
+import { toIdOrNull, toIdOrUndefined } from "./id.helper.js";
+
+export interface AuditLogEntry {
+  id: string;
+  workspaceId: string | null;
+  userId: string | null;
+  name: string;
+  action: string;
+  info: unknown;
+  remarks: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AuditLogListFilter {
+  /** Set on every workspace-scoped read, so one workspace's admins never see another's entries. */
+  workspaceId?: string;
+  userId?: string;
+  action?: string;
+  since?: string;
+  until?: string;
+  page?: number;
+  limit?: number;
+}
+
+/** An `auditLogs` row as `.select().from(auditLogs)` returns it. */
+export type AuditLogRow = typeof auditLogs.$inferSelect;
+
+/** Shapes a raw row into the wire DTO. Applied by the caller (`AuthService.listAuditLog`), not here. */
+export function toAuditLogEntry(row: AuditLogRow): AuditLogEntry {
+  return {
+    id: row.id.toString(),
+    workspaceId: row.workspaceId?.toString() ?? null,
+    userId: row.userId?.toString() ?? null,
+    name: row.name,
+    action: row.action,
+    info: row.info,
+    remarks: row.remarks,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+/** "role_assigned" -> "Role assigned". Derived rather than passed in, so core never has to carry display text. */
+export function humanizeAction(action: string): string {
+  const words = action.split("_");
+  return [words[0].charAt(0).toUpperCase() + words[0].slice(1), ...words.slice(1)].join(" ");
+}
+
+@Injectable()
+export class AuditLogRepository {
+  constructor(@Inject(DRIZZLE_DB) private readonly db: Database) {}
+
+  /**
+   * `workspaceId` is left null for events core raises (login, logout, password reset, ...) —
+   * those happen to a user, not inside a workspace. Callers that *are* acting in a workspace
+   * pass it, which is what scopes the admin audit-log read below.
+   */
+  async append(event: AuditEvent, opts: { workspaceId?: string; remarks?: string } = {}): Promise<void> {
+    await this.db.insert(auditLogs).values({
+      action: event.type,
+      name: humanizeAction(event.type),
+      workspaceId: toIdOrNull(opts.workspaceId),
+      userId: "userId" in event ? toIdOrNull(event.userId) : null,
+      info: event as unknown as Record<string, unknown>,
+      remarks: opts.remarks ?? null,
+    });
+  }
+
+  /** Newest-first, page-paginated. Returns raw rows — shaping is the caller's job, see `toAuditLogEntry`. */
+  async list(filter: AuditLogListFilter): Promise<Paginated<AuditLogRow>> {
+    const page = normalizePage(filter.page);
+    const limit = normalizeLimit(filter.limit);
+
+    const conditions: SQL[] = [];
+    const workspaceIdBig = toIdOrUndefined(filter.workspaceId);
+    if (workspaceIdBig !== undefined) conditions.push(eq(auditLogs.workspaceId, workspaceIdBig));
+    const userIdBig = toIdOrUndefined(filter.userId);
+    if (userIdBig !== undefined) conditions.push(eq(auditLogs.userId, userIdBig));
+    if (filter.action) conditions.push(eq(auditLogs.action, filter.action));
+    if (filter.since) conditions.push(gte(auditLogs.createdAt, new Date(filter.since)));
+    if (filter.until) conditions.push(lte(auditLogs.createdAt, new Date(filter.until)));
+    const where = conditions.length ? and(...conditions) : undefined;
+
+    const rows = await this.db
+      .select()
+      .from(auditLogs)
+      .where(where)
+      .orderBy(desc(auditLogs.createdAt), desc(auditLogs.id))
+      .limit(limit)
+      .offset((page - 1) * limit);
+    const [{ value: total }] = await this.db.select({ value: count() }).from(auditLogs).where(where);
+
+    return { items: rows, meta: buildPageMeta(page, limit, total) };
+  }
+}

package/registry/combos/nestjs-drizzle/variants/workspaces/src/auth.module.ts

@@ -0,0 +1,87 @@
+import { Pool } from "pg";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { DynamicModule, Module } from "@nestjs/common";
+import { APP_FILTER, APP_INTERCEPTOR } from "@nestjs/core";
+import { AbilityGuard } from "./ability.guard.js";
+import { AdminController } from "./admin.controller.js";
+import { AuditLogRepository } from "./audit-log.repository.js";
+import { AuthCoreErrorFilter } from "./auth-core-error.filter.js";
+import { AUTH_CONFIG, AuthConfig, defaultAuthConfig } from "./auth.config.js";
+import { AuthController } from "./auth.controller.js";
+import { AuthGuard } from "./auth.guard.js";
+import { AuthService } from "./auth.service.js";
+import { AuthzGuard, WorkspaceGuard } from "./authz.guard.js";
+import { DRIZZLE_DB } from "./db.js";
+import { KeyProviderService } from "./key-provider.js";
+import { OAuthRepository } from "./oauth.repository.js";
+import { PasswordResetRepository } from "./password-reset.repository.js";
+import { InMemoryPermissionCacheStore, PERMISSION_CACHE_STORE, PermissionCache } from "./permission-cache.js";
+import { InMemoryRateLimitStore, RATE_LIMIT_STORE } from "./rate-limit.store.js";
+import { RbacRepository } from "./rbac.repository.js";
+import { ResponseInterceptor } from "./response.interceptor.js";
+import { assertEveryRouteDeclaresATier } from "./route-tiers.js";
+import * as schema from "./schema.js";
+import { SessionRepository } from "./session.repository.js";
+import { TwoFactorRepository } from "./two-factor.repository.js";
+import { WorkspaceController } from "./workspace.controller.js";
+import { WorkspaceRepository } from "./workspace.repository.js";
+
+/**
+ * Every controller this library ships, in one place. It is both what the module registers and
+ * what the startup tier check walks, so a controller cannot be added to the app and left out of
+ * the check — there is only one list.
+ */
+const AUTH_CONTROLLERS = [AuthController, AdminController, WorkspaceController];
+
+@Module({})
+export class AuthModule {
+  static forRoot(config: Partial<AuthConfig> = {}): DynamicModule {
+    // Fail-closed, before anything else exists. A route carrying none of @Public(),
+    // @Authenticated() or @CheckAbility(...) — or carrying one that its guards contradict —
+    // stops the process here, by name, rather than shipping as an open endpoint nobody noticed.
+    // Nothing above this line allocates a connection pool or a port, so a failed boot leaves
+    // nothing behind.
+    assertEveryRouteDeclaresATier(AUTH_CONTROLLERS, { authentication: AuthGuard, ability: AbilityGuard });
+
+    const pool = new Pool({ connectionString: process.env["DATABASE_URL"] });
+    const db = drizzle(pool, { schema });
+
+    if (!config.permissionCacheStore || !config.rateLimitStore) {
+      console.warn(
+        "[simple-auth-kit] permissionCacheStore/rateLimitStore not overridden — using in-memory defaults. " +
+          "Fine for a single instance; silently inconsistent (stale grants, wrong rate-limit counts) " +
+          "across replicas once you run more than one. Override permissionCacheStore/rateLimitStore " +
+          "with a shared store (e.g. Redis) in AuthModule.forRoot() before scaling out.",
+      );
+    }
+    return {
+      module: AuthModule,
+      controllers: AUTH_CONTROLLERS,
+      providers: [
+        { provide: AUTH_CONFIG, useValue: { ...defaultAuthConfig, ...config } },
+        { provide: DRIZZLE_DB, useValue: db },
+        // The cache seam. Swap the store for a Redis-backed one by passing `permissionCacheStore`
+        // to forRoot — nothing in this library's source changes. Keys are namespaced simpleauthkit:authz:*.
+        { provide: PERMISSION_CACHE_STORE, useValue: config.permissionCacheStore ?? new InMemoryPermissionCacheStore() },
+        PermissionCache,
+        { provide: APP_FILTER, useClass: AuthCoreErrorFilter },
+        { provide: APP_INTERCEPTOR, useClass: ResponseInterceptor },
+        AuditLogRepository,
+        SessionRepository,
+        KeyProviderService,
+        { provide: RATE_LIMIT_STORE, useValue: config.rateLimitStore ?? new InMemoryRateLimitStore() },
+        RbacRepository,
+        WorkspaceRepository,
+        TwoFactorRepository,
+        OAuthRepository,
+        PasswordResetRepository,
+        AuthService,
+        AuthGuard,
+        AuthzGuard,
+        WorkspaceGuard,
+        AbilityGuard,
+      ],
+      exports: [AuthService, AuthGuard, AuthzGuard, WorkspaceGuard, AbilityGuard, PermissionCache, WorkspaceRepository, DRIZZLE_DB],
+    };
+  }
+}