@simple-auth-kit/cli 1.0.0

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

@@ -0,0 +1,266 @@
+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);
+    }
+  });
+
+  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-drizzle/shared/src/db.ts

@@ -0,0 +1,12 @@
+// Drizzle has no client *class* the way Prisma has `PrismaClient` — a `NodePgDatabase` is just a
+// value returned by `drizzle(pool, { schema })`. This file exists only to give every repository a
+// single place to import the resulting type from, rather than each one re-deriving
+// `NodePgDatabase<typeof schema>` and risking two slightly different shapes.
+//
+// Unlike the nestjs-drizzle combo's equivalent file, there is no injection token here: plain
+// Express has no DI container, so `createAuthApp` (see create-auth-app.ts) just builds the
+// database and passes it to each class's constructor directly.
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type * as schema from "./schema.js";
+
+export type Database = NodePgDatabase<typeof schema>;

package/registry/combos/express-drizzle/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-drizzle/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 Drizzle 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-drizzle/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 decorators — Express has no DI container to register with. Construct
+ * it directly in create-auth-app.ts and pass it into whatever else needs it.
+ */
+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-drizzle/shared/src/oauth.repository.ts

@@ -0,0 +1,47 @@
+import { and, eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { OAuthStoreDeps } from "@/lib/auth/core/oauth.js";
+import { HttpError } from "./http-error.js";
+import * as schema from "./schema.js";
+import { toId } from "./id.helper.js";
+
+/**
+ * Plain class, no decorators — Drizzle-specific implementation of `OAuthStoreDeps`
+ * (registry/core/oauth.js), mirroring the reference combo's OAuthRepository.
+ */
+export class OAuthRepository implements OAuthStoreDeps {
+  constructor(private readonly db: NodePgDatabase<typeof schema>) {}
+
+  async findAccountByProvider(provider: string, providerAccountId: string): Promise<{ userId: string } | null> {
+    const [row] = await this.db
+      .select()
+      .from(schema.oauthAccounts)
+      .where(and(eq(schema.oauthAccounts.provider, provider), eq(schema.oauthAccounts.providerAccountId, providerAccountId)))
+      .limit(1);
+    return row ? { userId: row.userId.toString() } : null;
+  }
+
+  async linkAccount(input: { userId: string; provider: string; providerAccountId: string; email?: string }): Promise<void> {
+    await this.db.insert(schema.oauthAccounts).values({
+      userId: toId(input.userId),
+      provider: input.provider,
+      providerAccountId: input.providerAccountId,
+      email: input.email,
+    });
+  }
+
+  async findUserByVerifiedEmail(email: string): Promise<{ id: string } | null> {
+    const [row] = await this.db.select().from(schema.users).where(eq(schema.users.email, email)).limit(1);
+    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.db
+      .insert(schema.users)
+      .values({ email: input.email, passwordHash: null })
+      .returning();
+    return { id: row.id.toString() };
+  }
+}

package/registry/combos/express-drizzle/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 "));
+}