@simple-auth-kit/cli 1.0.0

package/registry/combos/express-prisma/shared/src/ability.ts

@@ -0,0 +1,44 @@
+// The whole ability model, in one function. Deliberately tiny, and deliberately not a Nest
+// provider: it has no dependencies, does no I/O, and is imported by the server *and* by whatever
+// renders the admin UI, so it must be usable outside a DI container and outside Node.
+//
+//   server:  const ability = defineAbilitiesFor(await permissions.forUser(userId))
+//            ability.can("users:read", ABILITY_SUBJECT)     ← AbilityGuard
+//   client:  const ability = defineAbilitiesFor(me.permissions)   ← from GET /auth/me
+//            ability.can("users:read", ABILITY_SUBJECT)     ← show/hide a button
+//
+// Both sides build the ability from the same input (a flat list of permission slugs) with the
+// same function, so the console cannot offer an action the API will refuse. `GET /auth/me` ships
+// the slugs, not a serialised ability: the wire format is the permission list a human can read in
+// a log, and the ability is a local derivation on either side.
+//
+// A permission slug is used as CASL's *action* and the subject is a constant empty string.
+// That is what makes the model flat: there is no subject taxonomy to keep in sync with the
+// database, no `(action, subject)` pairing to get wrong, and no conditions — which in turn means
+// there is no such thing as a rule the route guard can only *partially* evaluate. What a slug
+// means is decided entirely by which routes name it.
+import { AbilityBuilder, createMongoAbility, type MongoAbility } from "@casl/ability";
+
+/**
+ * The subject every rule is written against. CASL needs one; this model does not use subjects, so
+ * there is exactly one, and it is a constant rather than a string literal repeated at each call
+ * site — `can("users:read", "")` in one place and `can("users:read", "all")` in another would
+ * silently never match.
+ */
+export const ABILITY_SUBJECT = "";
+
+/** Actions are permission slugs; the subject is always `ABILITY_SUBJECT`. */
+export type AppAbility = MongoAbility<[string, typeof ABILITY_SUBJECT]>;
+
+/**
+ * Builds the ability for a set of permission slugs.
+ *
+ * An empty list builds an ability with no rules at all, which denies everything — the fail-closed
+ * answer for "we could not resolve any permissions", and the same answer as "this user genuinely
+ * has none". There is no default-allow branch anywhere in this file.
+ */
+export function defineAbilitiesFor(permissions: readonly string[] = []): AppAbility {
+  const { can, build } = new AbilityBuilder<AppAbility>(createMongoAbility);
+  for (const permission of permissions) can(permission, ABILITY_SUBJECT);
+  return build();
+}

package/registry/combos/express-prisma/shared/src/auth-core-error.middleware.ts

@@ -0,0 +1,31 @@
+import type { NextFunction, Request, Response } from "express";
+import { AuthCoreError } from "@/lib/auth/core/types.js";
+import { HttpError } from "./http-error.js";
+
+/**
+ * Replaces the reference combo's `AuthCoreErrorFilter` (a Nest global `@Catch` exception
+ * filter). Express has no filter system, so this is a standard 4-arg error-handling
+ * middleware — mount it last, after the routers. Maps `AuthCoreError` (thrown deep
+ * inside `registry/core/session-policy.ts`/`token-service.ts`, e.g. a stale/reused
+ * refresh token) to a 401 JSON response instead of falling through to a bare 500, and
+ * maps this combo's own `HttpError` to its intended status code — the plain-Express stand-in
+ * for the NestJS exception classes the reference throws.
+ */
+export function authCoreErrorMiddleware(err: unknown, _req: Request, res: Response, next: NextFunction): void {
+  if (res.headersSent) {
+    next(err);
+    return;
+  }
+
+  if (err instanceof AuthCoreError) {
+    res.status(401).json({ statusCode: 401, code: err.code, message: err.message });
+    return;
+  }
+
+  if (err instanceof HttpError) {
+    res.status(err.statusCode).json({ statusCode: err.statusCode, code: err.name, message: err.message });
+    return;
+  }
+
+  next(err);
+}

package/registry/combos/express-prisma/shared/src/auth.config.ts

@@ -0,0 +1,63 @@
+import type { RateLimitDeps } from "@/lib/auth/core/rate-limit.js";
+import type { PermissionCacheStore } from "./permission-cache.js";
+
+export interface GoogleOAuthCredentials {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+}
+
+export interface AppleOAuthCredentials {
+  clientId: string;
+  teamId: string;
+  keyId: string;
+  privateKey: string;
+  redirectUri: string;
+}
+
+export interface AuthConfig {
+  accessTokenTtlSeconds: number;
+  refreshTokenTtlSeconds: number;
+  /**
+   * A session's absolute lifetime, written to `sessions.expires_at` when it is created and
+   * **never extended**. Refresh rotation issues a new refresh token each time, so without this a
+   * continuously-active client could hold one session open forever; this is the cap that makes
+   * "log in again after N days" true regardless of activity. `rotateRefreshToken` enforces it.
+   */
+  sessionTtlSeconds: number;
+  /** App name shown inside authenticator apps next to the account (issuer part of the otpauth:// URI). */
+  twoFactorIssuer: string;
+  oauthProviders: {
+    google?: GoogleOAuthCredentials;
+    apple?: AppleOAuthCredentials;
+  };
+  /**
+   * How long a resolved permission set may sit in the cache. This is a safety net, not the
+   * invalidation mechanism: correctness comes from the version counters in permission-cache.ts,
+   * which make a stale entry unreachable the instant anything changes. Set to 0 to resolve from
+   * the database on every request — same answers, more queries.
+   */
+  permissionCacheTtlSeconds: number;
+  /**
+   * Where resolved permissions are cached. Defaults to an in-process `Map`, which is correct for
+   * a single instance; pass a Redis-backed implementation of `PermissionCacheStore` for several.
+   * Keys are namespaced `simpleauthkit:authz:*`.
+   */
+  permissionCacheStore?: PermissionCacheStore;
+  /**
+   * Where rate-limit counters live. Defaults to an in-process `Map`, which is correct for a
+   * single instance; pass a Redis-backed implementation of `RateLimitDeps` for several.
+   */
+  rateLimitStore?: RateLimitDeps;
+  /** Wire your own mailer here — if unset, requestPasswordReset() just returns the token without emailing it. */
+  sendPasswordResetEmail?: (email: string, token: string) => Promise<void>;
+}
+
+export const defaultAuthConfig: AuthConfig = {
+  accessTokenTtlSeconds: 900,
+  permissionCacheTtlSeconds: 300,
+  refreshTokenTtlSeconds: 60 * 60 * 24 * 30,
+  sessionTtlSeconds: 60 * 60 * 24 * 30,
+  twoFactorIssuer: "simple-auth-kit",
+  oauthProviders: {},
+};

package/registry/combos/express-prisma/shared/src/auth.middleware.ts

@@ -0,0 +1,44 @@
+import type { NextFunction, Request, Response } from "express";
+import { verifyAccessToken } from "@/lib/auth/core/token-service.js";
+import { KeyProviderService } from "./key-provider.js";
+import "./request-context.js";
+import { SessionRepository } from "./session.repository.js";
+
+export interface AuthMiddlewareDeps {
+  keys: KeyProviderService;
+  sessions: SessionRepository;
+}
+
+/**
+ * Authentication only — proves who the caller is and populates `req.auth`. Authorization
+ * (`req.authz`) is a deliberately separate step: pair this with the authz middleware on any
+ * route that checks roles or permissions.
+ *
+ * Replaces the reference combo's `AuthGuard` (a Nest `CanActivate`). There is no guard
+ * interface to implement in plain Express — a middleware factory closing over its dependencies
+ * is the idiomatic equivalent.
+ */
+export function createAuthMiddleware(deps: AuthMiddlewareDeps) {
+  return async function authMiddleware(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const header = req.headers["authorization"];
+    if (!header?.startsWith("Bearer ")) {
+      res.status(401).json({ statusCode: 401, code: "UNAUTHORIZED", message: "missing bearer token" });
+      return;
+    }
+
+    try {
+      req.auth = await verifyAccessToken(
+        { secret: deps.keys.secret, isDenylisted: (jti) => deps.sessions.isDenylisted(jti) },
+        header.slice("Bearer ".length),
+      );
+    } catch (err) {
+      res.status(401).json({
+        statusCode: 401,
+        code: "UNAUTHORIZED",
+        message: err instanceof Error ? err.message : "invalid access token",
+      });
+      return;
+    }
+    next();
+  };
+}

package/registry/combos/express-prisma/shared/src/auth.router.ts

@@ -0,0 +1,269 @@
+import type { NextFunction, Request, RequestHandler, Response } from "express";
+import type { AuthConfig } from "./auth.config.js";
+import { AuthService } from "./auth.service.js";
+import { HttpError } from "./http-error.js";
+import { authenticated, createTieredRouter, publicRoute, 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 AuthRouterDeps extends TierMiddleware {
+  auth: AuthService;
+  config: AuthConfig;
+}
+
+/**
+ * Identity endpoints — everything that is about *a user*, never about a group of them.
+ * Administration lives in admin.router.ts.
+ *
+ * Replaces the reference combo's `AuthController` (a Nest `@Controller`). Same endpoints, same
+ * validation, same status codes — just an Express `Router()` instead of a decorated class, and
+ * middleware passed in where the controller lists `@UseGuards(...)`. Every handler is wrapped in
+ * try/catch + `next(err)` so a thrown `HttpError`/`AuthCoreError` reaches the error-handling
+ * middleware mounted in create-auth-app.ts instead of leaking a bare 500.
+ */
+export function createAuthRouter(deps: AuthRouterDeps): RequestHandler {
+  const { auth, config, authentication, authorization } = deps;
+  const router = createTieredRouter({ authentication, authorization });
+
+  router.route("post", "/signup", publicRoute(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      const tokens = await auth.signup({
+        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),
+        userAgent: req.headers["user-agent"],
+        ip: req.ip,
+      });
+      res.status(201).json(tokens);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/login", publicRoute(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      const result = await auth.login({
+        identifier: requireString(body.identifier, "identifier"),
+        password: requireString(body.password, "password"),
+        userAgent: req.headers["user-agent"],
+        ip: req.ip,
+      });
+      res.status(200).json(result);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/login/2fa", publicRoute(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      const tokens = await auth.loginTwoFactor({
+        challengeToken: requireString(body.challengeToken, "challengeToken"),
+        code: requireString(body.code, "code"),
+        userAgent: req.headers["user-agent"],
+        ip: req.ip,
+      });
+      res.status(200).json(tokens);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/refresh", publicRoute(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      const tokens = await auth.refresh(requireString(body.refreshToken, "refreshToken"));
+      res.status(200).json(tokens);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  // `roles`/`permissions` are whatever applies to this request — see authz.middleware.ts for how
+  // they are resolved. A request that names no authorization scope gets empty arrays.
+  //
+  // `permissions` is the caller's whole authorization: `defineAbilitiesFor(permissions)` from
+  // ability.ts rebuilds, in the client, the identical CASL ability the server's own route check
+  // just answered with, so the UI cannot disagree with what the API will allow. The slugs go on
+  // the wire rather than a serialised ability, so the payload is something a human can read in a
+  // log — and it is the same `req.authz` the ability was built from, not a re-resolution.
+  router.route("get", "/me", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { sub, sessionId } = req.auth!;
+      const [{ twoFactorEnabled }, profile] = await Promise.all([auth.getTwoFactorStatus(sub), auth.getProfile(sub)]);
+      res.status(200).json({
+        sub,
+        sessionId,
+        roles: req.authz?.roles ?? [],
+        permissions: req.authz?.permissions ?? [],
+        twoFactorEnabled,
+        email: profile.email,
+        firstName: profile.firstName,
+        lastName: profile.lastName,
+        displayName: profile.displayName,
+        phone: profile.phone,
+        username: profile.username,
+        photo: profile.photo,
+      });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("get", "/sessions", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const sessions = await auth.listActiveSessions(req.auth!.sub);
+      res.status(200).json(sessions);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/logout", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { sessionId, jti, sub } = req.auth!;
+      // Recorded so the row can later be told apart from a session an administrator ended —
+      // see `sessions.revoked_by`.
+      await auth.logout(sessionId, jti, config.accessTokenTtlSeconds, { userId: sub, ip: req.ip });
+      res.status(200).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/logout-all", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await auth.logoutAll(req.auth!.sub, { userId: req.auth!.sub, ip: req.ip });
+      res.status(200).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/logout-others", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await auth.logoutOthers(req.auth!.sub, req.auth!.sessionId, { userId: req.auth!.sub, ip: req.ip });
+      res.status(200).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/password/change", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      await auth.changePassword(req.auth!.sub, req.auth!.sessionId, {
+        currentPassword: requireString(body.currentPassword, "currentPassword"),
+        newPassword: requireString(body.newPassword, "newPassword"),
+      });
+      res.status(200).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  // Self-service — no admin permission required. Updates the caller's own row directly; unrelated
+  // to any workspace. Same null-vs-undefined field parsing every PATCH handler in this codebase
+  // uses — see admin.router.ts's PATCH /users/:userId.
+  router.route("patch", "/me", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      const profile = await auth.updateProfile(req.auth!.sub, {
+        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),
+      });
+      res.status(200).json(profile);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/2fa/enroll", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const result = await auth.enrollTwoFactor(req.auth!.sub);
+      res.status(200).json(result);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/2fa/confirm", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      const result = await auth.confirmTwoFactor(req.auth!.sub, requireString(body.code, "code"));
+      res.status(200).json(result);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/2fa/disable", authenticated(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      await auth.disableTwoFactor(req.auth!.sub, requireString(body.code, "code"));
+      res.status(200).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/password/forgot", publicRoute(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      await auth.requestPasswordReset(requireString(body.email, "email"));
+      res.status(200).json({ ok: true }); // always 200 — never reveal whether the email exists
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("post", "/password/reset", publicRoute(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const body = req.body as Record<string, unknown>;
+      await auth.resetPassword(requireString(body.token, "token"), requireString(body.newPassword, "newPassword"));
+      res.status(200).json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("get", "/oauth/:provider/start", publicRoute(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const result = await auth.startOAuth(requireString(req.params.provider, "provider"));
+      res.status(200).json(result);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.route("get", "/oauth/:provider/callback", publicRoute(), async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const tokens = await auth.completeOAuthCallback(
+        requireString(req.params.provider, "provider"),
+        requireString(req.query.code, "code"),
+        requireString(req.query.state, "state"),
+      );
+      res.status(200).json(tokens);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  return router.handler;
+}

package/registry/combos/express-prisma/shared/src/http-error.ts

@@ -0,0 +1,18 @@
+/**
+ * HTTP-status-flavored errors, mapped to a response by auth-core-error.middleware.ts.
+ *
+ * The reference combo throws NestJS's exception classes (`ConflictException`,
+ * `NotFoundException`, ...) and lets the framework turn them into responses. Plain Express has
+ * no exception hierarchy at all, so this one small class stands in for the whole of it: the
+ * status code travels with the error from wherever it is thrown — service, repository, router —
+ * to the error-handling middleware mounted last in create-auth-app.ts.
+ */
+export class HttpError extends Error {
+  constructor(
+    public readonly statusCode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "HttpError";
+  }
+}

package/registry/combos/express-prisma/shared/src/id.helper.ts

@@ -0,0 +1,22 @@
+// Primary keys are BigInt for join/index performance; registry/core's types (SessionRecord,
+// Revoker, etc.) deliberately stay opaque `string` identifiers so core has zero DB awareness.
+// This is the one conversion point between the two, at each repository's Prisma boundary —
+// never call BigInt(...)/.toString() ad hoc, since a malformed value should 400, not throw an
+// uncaught SyntaxError.
+export function toId(value: string | number | bigint): bigint {
+  try {
+    return BigInt(value);
+  } catch {
+    throw new Error(`Invalid id: ${value}`);
+  }
+}
+
+export function toIdOrUndefined(value: string | number | bigint | null | undefined): bigint | undefined {
+  if (value === null || value === undefined || value === "") return undefined;
+  return toId(value);
+}
+
+export function toIdOrNull(value: string | number | bigint | null | undefined): bigint | null {
+  if (value === null || value === undefined || value === "") return null;
+  return toId(value);
+}

package/registry/combos/express-prisma/shared/src/key-provider.ts

@@ -0,0 +1,52 @@
+// NOTE: the `@/lib/auth/core/*` import path below is a placeholder the CLI rewrites
+// to your project's actual path alias at install time (see registry.json).
+import { createHash } from "node:crypto";
+import type { JwtSigningKey } from "@/lib/auth/core/types.js";
+
+const ENV_VAR = "AUTH_JWT_SECRET";
+const MIN_SECRET_BYTES = 32; // 256 bits, HS256's own minimum
+
+function loadSecret(): Uint8Array {
+  const raw = process.env[ENV_VAR];
+  if (!raw) {
+    throw new Error(`${ENV_VAR} is not set. Generate one and set it before starting the app — e.g.: openssl rand -base64 32`);
+  }
+  const secret = Buffer.from(raw, "base64");
+  if (secret.length < MIN_SECRET_BYTES) {
+    throw new Error(`${ENV_VAR} decodes to ${secret.length} bytes — needs at least ${MIN_SECRET_BYTES} (256 bits) for HS256.`);
+  }
+  return secret;
+}
+
+/**
+ * One static HS256 secret, read once from `AUTH_JWT_SECRET` at process start. No database, no
+ * generation, no rotation: the secret is deployment configuration, the same way `DATABASE_URL`
+ * is — losing it (or changing it) invalidates every outstanding token, which is the same
+ * failure mode an RSA keypair rotation has for its *retired* keys, just without the grace
+ * window this library previously bought by keeping old keys verifiable in the database.
+ *
+ * `kid` is derived from the secret (a hash prefix) rather than configured separately, so it
+ * changes automatically whenever the secret does, with nothing else to keep in sync. It is
+ * carried in the JWT header for tooling/debugging only — `token-service.ts`'s verify path does
+ * not consult it, because there is only ever one secret in play.
+ *
+ * Plain class, no DI container: Express has nothing like Nest's `@Injectable()`/`@Inject()`
+ * machinery — just construct one of these yourself (see create-auth-app.ts) and pass it around.
+ */
+export class KeyProviderService {
+  private readonly key: JwtSigningKey;
+
+  constructor() {
+    const secret = loadSecret();
+    const kid = createHash("sha256").update(secret).digest("hex").slice(0, 12);
+    this.key = { kid, secret };
+  }
+
+  async getActiveKey(): Promise<JwtSigningKey> {
+    return this.key;
+  }
+
+  get secret(): Uint8Array {
+    return this.key.secret;
+  }
+}

package/registry/combos/express-prisma/shared/src/oauth.repository.ts

@@ -0,0 +1,33 @@
+import type { OAuthStoreDeps } from "@/lib/auth/core/oauth.js";
+import { PrismaClient } from "../generated/prisma/client.js";
+import { HttpError } from "./http-error.js";
+import { toId } from "./id.helper.js";
+
+// Plain class, no DI container — constructed directly with a PrismaClient in
+// create-auth-app.ts. Identical Prisma queries to the reference combo.
+export class OAuthRepository implements OAuthStoreDeps {
+  constructor(private readonly prisma: PrismaClient) {}
+
+  async findAccountByProvider(provider: string, providerAccountId: string): Promise<{ userId: string } | null> {
+    const row = await this.prisma.oAuthAccount.findUnique({
+      where: { provider_providerAccountId: { provider, providerAccountId } },
+    });
+    return row ? { userId: row.userId.toString() } : null;
+  }
+
+  async linkAccount(input: { userId: string; provider: string; providerAccountId: string; email?: string }): Promise<void> {
+    await this.prisma.oAuthAccount.create({ data: { ...input, userId: toId(input.userId) } });
+  }
+
+  async findUserByVerifiedEmail(email: string): Promise<{ id: string } | null> {
+    const row = await this.prisma.user.findUnique({ where: { email } });
+    return row ? { id: row.id.toString() } : null;
+  }
+
+  /** OAuth-only signup: no password is ever set, which is why `User.passwordHash` is nullable. */
+  async createUserFromOAuth(input: { email?: string }): Promise<{ id: string }> {
+    if (!input.email) throw new HttpError(400, "OAuth provider did not return an email address");
+    const row = await this.prisma.user.create({ data: { email: input.email, passwordHash: null } });
+    return { id: row.id.toString() };
+  }
+}

package/registry/combos/express-prisma/shared/src/openapi-fragment.ts

@@ -0,0 +1,49 @@
+// Building blocks shared by the pieces of the hand-authored OpenAPI document.
+//
+// A leaf module on purpose: `openapi-spec.ts` assembles the document from its own identity
+// routes plus the fragment `openapi-admin.ts` contributes, and both of those import from here,
+// so nothing imports in a circle. (`rbac.defaults.ts` below is a leaf too — it imports only a
+// Prisma type — so naming the permission catalog here keeps that property.)
+import type { PermissionSlug } from "./rbac.defaults.js";
+
+/** One module's contribution to the assembled OpenAPI document — see openapi-spec.ts. */
+export interface OpenApiFragment {
+  tags: Array<Record<string, unknown>>;
+  schemas: Record<string, unknown>;
+  paths: Record<string, unknown>;
+  /**
+   * Parameters an identity route accepts for naming the scope it is acting in, if this
+   * deployment has one narrower than itself. `GET /auth/me` answers differently per scope,
+   * so it documents them; every other identity route is scope-free.
+   */
+  scopeParameters: Array<Record<string, unknown>>;
+}
+
+/** An error response body, as produced by auth-core-error.middleware.ts. */
+export function errorResponse(description: string): Record<string, unknown> {
+  return {
+    description,
+    content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } },
+  };
+}
+
+// The two helpers below are what keep this hand-authored document honest about authorization.
+// The nestjs-* combos derive their spec from the very decorators that enforce the check, so it
+// cannot disagree with the code; this one is written by hand and would happily go on describing
+// a rule that no longer exists. Typing both arguments as `PermissionSlug` recovers the half that
+// matters most: the document can only name permissions the catalog defines, so renaming a slug in
+// `rbac.defaults.ts` breaks the build here too rather than leaving the docs quietly wrong.
+
+/** The operation-level note naming the permission a route is gated on. See route-tiers.ts. */
+export function requiresPermission(permission: PermissionSlug): string {
+  return `Requires the \`${permission}\` permission.`;
+}
+
+/**
+ * The 403 an admin route answers with. `alsoWhen` lists the route's own extra refusals — its
+ * self-checks, and anything about the scope the request named, where this deployment has one
+ * narrower than itself.
+ */
+export function missingPermission(permission: PermissionSlug, ...alsoWhen: string[]): Record<string, unknown> {
+  return errorResponse([`Missing the \`${permission}\` permission`, ...alsoWhen].join(", or "));
+}