@simple-auth-kit/cli 1.4.3 → 1.5.0

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

@@ -0,0 +1,508 @@
+import type { NextFunction, Request, RequestHandler, Response } from "express";
+import { AuthService } from "../services/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;
+}

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

@@ -22,12 +22,21 @@
 // what gets seeded and what the routes demand cannot drift apart.
 import { PrismaPg } from "@prisma/adapter-pg";
 import { hashPassword } from "@/lib/auth/core/crypto.js";
-import { PrismaClient } from "../generated/prisma/client.js";
-import { DEFAULT_ROLES, PERMISSION_SLUGS, provisionDefaultRoles, SEED_ADMIN_ROLES, SEED_SUPERADMIN_ROLES } from "./rbac.defaults.js";
+import { PrismaClient } from "./../generated/prisma/client.js";
+import {
+  DEFAULT_ROLES,
+  PERMISSION_SLUGS,
+  provisionDefaultRoles,
+  SEED_ADMIN_ROLES,
+  SEED_SUPERADMIN_ROLES,
+} from "./rbac.defaults.js";
 
 function requireEnv(name: string): string {
   const value = process.env[name];
-  if (!value) throw new Error(`${name} is not set — the seeder cannot reach the database without it`);
+  if (!value)
+    throw new Error(
+      `${name} is not set — the seeder cannot reach the database without it`,
+    );
   return value;
 }
 
@@ -35,17 +44,30 @@ function requireEnv(name: string): string {
 async function seedRbacDefaults(prisma: PrismaClient): Promise<void> {
   await provisionDefaultRoles(prisma);
   console.log(`permissions: ${PERMISSION_SLUGS.length} slug(s) in the catalog`);
-  for (const role of DEFAULT_ROLES) console.log(`role "${role.slug}": ${role.permissions.length} permission(s)${role.isDefault ? " (signup default)" : ""}`);
+  for (const role of DEFAULT_ROLES)
+    console.log(
+      `role "${role.slug}": ${role.permissions.length} permission(s)${role.isDefault ? " (signup default)" : ""}`,
+    );
 
   // Slugs that exist in the database but not in this build's catalog. They are not an error —
   // `POST /auth/admin/permissions` exists so a deployment can define its own, and a grant can
   // create one — but a slug no route names grants nothing, so a typo would otherwise be a
   // permission that mysteriously never works. Printing them is what makes it visible.
-  const rows = await prisma.permission.findMany({ select: { slug: true, isActive: true } });
-  const unknown = rows.filter((row) => !(PERMISSION_SLUGS as string[]).includes(row.slug));
-  if (unknown.length) console.log(`permissions: ${unknown.length} slug(s) outside this build's catalog (no route names them): ${unknown.map((r) => r.slug).join(", ")}`);
+  const rows = await prisma.permission.findMany({
+    select: { slug: true, isActive: true },
+  });
+  const unknown = rows.filter(
+    (row) => !(PERMISSION_SLUGS as string[]).includes(row.slug),
+  );
+  if (unknown.length)
+    console.log(
+      `permissions: ${unknown.length} slug(s) outside this build's catalog (no route names them): ${unknown.map((r) => r.slug).join(", ")}`,
+    );
   const inactive = rows.filter((row) => !row.isActive);
-  if (inactive.length) console.log(`permissions: ${inactive.length} deactivated, granting nothing: ${inactive.map((r) => r.slug).join(", ")}`);
+  if (inactive.length)
+    console.log(
+      `permissions: ${inactive.length} deactivated, granting nothing: ${inactive.map((r) => r.slug).join(", ")}`,
+    );
 }
 
 /** Roles are global here, so administrative authority is a property of the user row itself. */
@@ -53,18 +75,34 @@ async function seedAdminUser(prisma: PrismaClient): Promise<void> {
   const email = process.env["SEED_ADMIN_EMAIL"];
   const password = process.env["SEED_ADMIN_PASSWORD"];
   if (!email || !password) {
-    console.log("admin: skipped — set SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD to create one (there is no default password)");
+    console.log(
+      "admin: skipped — set SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD to create one (there is no default password)",
+    );
     return;
   }
 
   // Their password may have been changed since; rewriting it here would silently reset it.
   const existing = await prisma.user.findUnique({ where: { email } });
   // Hashed by the same function signup uses, so the seeded admin can actually log in.
-  const user = existing ?? (await prisma.user.create({ data: { email, passwordHash: await hashPassword(password) } }));
-  console.log(existing ? `admin: ${email} already exists — password left unchanged` : `admin: created ${email}`);
+  const user =
+    existing ??
+    (await prisma.user.create({
+      data: { email, passwordHash: await hashPassword(password) },
+    }));
+  console.log(
+    existing
+      ? `admin: ${email} already exists — password left unchanged`
+      : `admin: created ${email}`,
+  );
 
-  const roles = await prisma.role.findMany({ where: { slug: { in: SEED_ADMIN_ROLES } }, select: { id: true, slug: true } });
-  await prisma.roleUser.createMany({ data: roles.map((role) => ({ userId: user.id, roleId: role.id })), skipDuplicates: true });
+  const roles = await prisma.role.findMany({
+    where: { slug: { in: SEED_ADMIN_ROLES } },
+    select: { id: true, slug: true },
+  });
+  await prisma.roleUser.createMany({
+    data: roles.map((role) => ({ userId: user.id, roleId: role.id })),
+    skipDuplicates: true,
+  });
   console.log(`admin: holds roles ${roles.map((r) => r.slug).join(", ")}`);
 }
 
@@ -73,7 +111,9 @@ async function seedSuperAdminUser(prisma: PrismaClient): Promise<void> {
   const email = process.env["SEED_SUPERADMIN_EMAIL"];
   const password = process.env["SEED_SUPERADMIN_PASSWORD"];
   if (!email || !password) {
-    console.log("super admin: skipped — set SEED_SUPERADMIN_EMAIL and SEED_SUPERADMIN_PASSWORD to create one (there is no default password)");
+    console.log(
+      "super admin: skipped — set SEED_SUPERADMIN_EMAIL and SEED_SUPERADMIN_PASSWORD to create one (there is no default password)",
+    );
     return;
   }
   const username = process.env["SEED_SUPERADMIN_USERNAME"] || undefined;
@@ -81,12 +121,28 @@ async function seedSuperAdminUser(prisma: PrismaClient): Promise<void> {
   // Their password may have been changed since; rewriting it here would silently reset it.
   const existing = await prisma.user.findUnique({ where: { email } });
   // Hashed by the same function signup uses, so the seeded super admin can actually log in.
-  const user = existing ?? (await prisma.user.create({ data: { email, username, passwordHash: await hashPassword(password) } }));
-  console.log(existing ? `super admin: ${email} already exists — password left unchanged` : `super admin: created ${email}${username ? ` (username ${username})` : ""}`);
+  const user =
+    existing ??
+    (await prisma.user.create({
+      data: { email, username, passwordHash: await hashPassword(password) },
+    }));
+  console.log(
+    existing
+      ? `super admin: ${email} already exists — password left unchanged`
+      : `super admin: created ${email}${username ? ` (username ${username})` : ""}`,
+  );
 
-  const roles = await prisma.role.findMany({ where: { slug: { in: SEED_SUPERADMIN_ROLES } }, select: { id: true, slug: true } });
-  await prisma.roleUser.createMany({ data: roles.map((role) => ({ userId: user.id, roleId: role.id })), skipDuplicates: true });
-  console.log(`super admin: holds roles ${roles.map((r) => r.slug).join(", ")}`);
+  const roles = await prisma.role.findMany({
+    where: { slug: { in: SEED_SUPERADMIN_ROLES } },
+    select: { id: true, slug: true },
+  });
+  await prisma.roleUser.createMany({
+    data: roles.map((role) => ({ userId: user.id, roleId: role.id })),
+    skipDuplicates: true,
+  });
+  console.log(
+    `super admin: holds roles ${roles.map((r) => r.slug).join(", ")}`,
+  );
 }
 
 async function main(): Promise<void> {
@@ -98,7 +154,9 @@ async function main(): Promise<void> {
     // No .env here — the environment is expected to carry the variables itself (docker, CI, ...).
   }
 
-  const prisma = new PrismaClient({ adapter: new PrismaPg({ connectionString: requireEnv("DATABASE_URL") }) });
+  const prisma = new PrismaClient({
+    adapter: new PrismaPg({ connectionString: requireEnv("DATABASE_URL") }),
+  });
   try {
     await seedRbacDefaults(prisma);
     await seedAdminUser(prisma);