@simple-auth-kit/cli 1.0.0

package/registry/combos/express-drizzle/variants/base/drizzle/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1786381607914,
+      "tag": "0000_init",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1786461250121,
+      "tag": "0001_add_is_active_field",
+      "breakpoints": true
+    }
+  ]
+}

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

@@ -0,0 +1,307 @@
+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);
+    }
+  });
+
+  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);
+    }
+  });
+
+  admin.route("patch", "/users/:userId", ability("users:manage"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      res.status(200).json(
+        await auth.updateUser(
+          requireString(req.params.userId, "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);
+    }
+  });
+
+  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");
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      await auth.deleteUser(userId, req.auth!.sub, optionalString(body.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 body = req.body as Record<string, unknown>;
+      res.status(200).json(
+        await auth.updateRole(
+          requireString(req.params.roleId, "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);
+    }
+  });
+
+  admin.route("delete", "/roles/:roleId", ability("roles:manage"), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      await auth.deleteRole(requireString(req.params.roleId, "roleId"), req.auth!.sub, optionalString(body.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;
+}

package/registry/combos/express-drizzle/variants/base/src/audit-log.repository.ts

@@ -0,0 +1,93 @@
+import { and, count, desc, eq, gte, lte, type SQL } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { AuditEvent } from "@/lib/auth/core/types.js";
+import { buildPageMeta, normalizeLimit, normalizePage, type Paginated } from "./pagination.js";
+import * as schema from "./schema.js";
+import { toIdOrNull, toIdOrUndefined } from "./id.helper.js";
+
+export interface AuditLogEntry {
+  id: string;
+  userId: string | null;
+  name: string;
+  action: string;
+  info: unknown;
+  remarks: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AuditLogListFilter {
+  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 schema.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(),
+    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(" ");
+}
+
+/**
+ * Plain class, no decorators — Drizzle-specific sink for `SessionStoreDeps.appendAuditEvent`
+ * (registry/core/session-policy.ts) plus the RBAC/2FA/OAuth/password-reset flows, mirroring
+ * the reference combo's AuditLogRepository.
+ */
+export class AuditLogRepository {
+  constructor(private readonly db: NodePgDatabase<typeof schema>) {}
+
+  async append(event: AuditEvent, opts: { remarks?: string } = {}): Promise<void> {
+    await this.db.insert(schema.auditLogs).values({
+      action: event.type,
+      name: humanizeAction(event.type),
+      userId: "userId" in event ? toIdOrNull(event.userId) : null,
+      info: event,
+      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 userIdBig = toIdOrUndefined(filter.userId);
+    if (userIdBig !== undefined) conditions.push(eq(schema.auditLogs.userId, userIdBig));
+    if (filter.action) conditions.push(eq(schema.auditLogs.action, filter.action));
+    if (filter.since) conditions.push(gte(schema.auditLogs.createdAt, new Date(filter.since)));
+    if (filter.until) conditions.push(lte(schema.auditLogs.createdAt, new Date(filter.until)));
+    const where = conditions.length ? and(...conditions) : undefined;
+
+    const rows = await this.db
+      .select()
+      .from(schema.auditLogs)
+      .where(where)
+      .orderBy(desc(schema.auditLogs.createdAt), desc(schema.auditLogs.id))
+      .limit(limit)
+      .offset((page - 1) * limit);
+    const [{ value: total }] = await this.db.select({ value: count() }).from(schema.auditLogs).where(where);
+
+    return { items: rows, meta: buildPageMeta(page, limit, total) };
+  }
+}