@simple-auth-kit/cli 1.0.0

package/registry/combos/nestjs-drizzle/shared/drizzle.config.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { config as loadDotenv } from "dotenv";
+import { defineConfig } from "drizzle-kit";
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+
+// Plain `import "dotenv/config"` only loads `.env` relative to the process's cwd, which misses
+// the project's real `.env` at the root. Resolve from this file's own location instead and walk
+// up until a `.env` is found.
+function loadNearestEnv(startDir: string): void {
+  let dir = startDir;
+  for (let depth = 0; depth < 8; depth += 1) {
+    const candidate = join(dir, ".env");
+    if (existsSync(candidate)) {
+      loadDotenv({ path: candidate });
+      return;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+loadNearestEnv(thisDir);
+
+// The CLI installs this file at the project root (<targetRoot>/drizzle.config.ts, alongside
+// drizzle/) — Drizzle's own convention, so `npx drizzle-kit ...` need no `cd` and find it
+// automatically. schema.ts itself stays inside the merged auth-lib directory with the rest of
+// this combo's source, so its directory can't be a fixed relative string once this file moves.
+//
+// Two contexts share this file, and they disagree about where that directory is:
+//   - registry/combos/*/scripts/materialize.mjs (this combo's own dev/typecheck/prove-cycle
+//     loop) flatly composes shared/+variants/<v>/ into one directory, so schema.ts's directory
+//     is right next to this file — no .simple-auth-kit.json is ever written there.
+//   - a real consumer install: this file lives at the project root while schema.ts stays nested
+//     under the merged auth-lib directory, whose path is recorded in .simple-auth-kit.json
+//     (falling back to the CLI's own default when that file is absent).
+// Probing for the sibling first covers both without hardcoding either shape.
+function resolveSchemaDir(): string {
+  const sibling = join(thisDir, "src");
+  if (existsSync(join(sibling, "schema.ts"))) return sibling;
+
+  let authLibPath = "src/lib/auth";
+  try {
+    const parsed = JSON.parse(readFileSync(join(thisDir, ".simple-auth-kit.json"), "utf8")) as { path?: string };
+    if (parsed.path) authLibPath = parsed.path;
+  } catch {
+    // no .simple-auth-kit.json (defaults apply) — fall through with the CLI's own default path
+  }
+  return join(thisDir, authLibPath, "src");
+}
+
+const schemaDir = resolveSchemaDir();
+
+export default defineConfig({
+  // schema.ts is the CLI-managed file — never edit it directly, it's overwritten on every
+  // update. Add your own tables in a sibling file named *.schema.ts in this same directory
+  // (e.g. billing.schema.ts) instead: drizzle-kit merges every matched file's exports into one
+  // schema, and the CLI only ever tracks schema.ts by exact name, so your file is never touched.
+  schema: [join(schemaDir, "schema.ts"), join(schemaDir, "*.schema.ts")],
+  out: join(thisDir, "drizzle"),
+  dialect: "postgresql",
+  dbCredentials: {
+    url: process.env["DATABASE_URL"]!,
+  },
+});

package/registry/combos/nestjs-drizzle/shared/src/ability.guard.ts

@@ -0,0 +1,46 @@
+import { CanActivate, ExecutionContext, ForbiddenException, Inject, Injectable } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { ABILITY_SUBJECT } from "./ability.js";
+import { CHECK_ABILITY_KEY } from "./route-tiers.js";
+
+/**
+ * The authorization boundary for tier-3 routes. This is the *only* thing standing between a
+ * caller and an administrative route — there is deliberately no role-based bypass beside it, so a
+ * role that carries no permissions confers no authority no matter what it is called.
+ *
+ * It asks the caller's `Ability` the same question a client asks after `GET /auth/me`, built by
+ * the same function from the same slugs, which is what makes server enforcement and client UI
+ * incapable of disagreeing.
+ *
+ * Fail-closed in every direction:
+ *   • no `req.ability` (the authorization guard resolved nothing) → 403;
+ *   • any one of the declared slugs missing → 403, naming it;
+ *   • the guard applied to a route that declares no slugs → an error, not an open route.
+ *
+ * That last one is the deliberate divergence from the pattern this guard is modelled on, which
+ * returns `true` when a route names no permission. Treating "named nothing" as "authenticated is
+ * enough" means a new route ships open by omission; here "authenticated is enough" has its own
+ * marker (`@Authenticated()`), and a route that says neither does not survive startup — see
+ * `assertEveryRouteDeclaresATier`. This check stays as the runtime backstop.
+ */
+@Injectable()
+export class AbilityGuard implements CanActivate {
+  // @Inject(Reflector) explicitly, same rationale as key-provider.ts's PrismaClient injection —
+  // keeps DI working under esbuild-based toolchains that don't emit design:paramtypes metadata.
+  constructor(@Inject(Reflector) private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const required = this.reflector.getAllAndOverride<string[] | undefined>(CHECK_ABILITY_KEY, [context.getHandler(), context.getClass()]);
+    if (!required?.length) {
+      throw new Error(`${context.getClass().name}.${context.getHandler().name} is guarded by AbilityGuard but declares no @CheckAbility`);
+    }
+
+    const ability = context.switchToHttp().getRequest().ability;
+    if (!ability) throw new ForbiddenException("no authorization context for this request");
+
+    for (const permission of required) {
+      if (!ability.can(permission, ABILITY_SUBJECT)) throw new ForbiddenException(`missing permission: ${permission}`);
+    }
+    return true;
+  }
+}

package/registry/combos/nestjs-drizzle/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/nestjs-drizzle/shared/src/auth-core-error.filter.ts

@@ -0,0 +1,32 @@
+import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus } from "@nestjs/common";
+import { AuthCoreError } from "@/lib/auth/core/types.js";
+
+/**
+ * Every error response carries `success: false` alongside whatever produced it — `AuthCoreError`
+ * from registry/core, a NestJS `HttpException` (which already shapes `statusCode`/`message`, and
+ * for its built-ins, `error`), or anything unexpected. One filter handling all three, rather than
+ * `@Catch(AuthCoreError)` and a separate bare `@Catch()` filter, avoids depending on NestJS's
+ * filter-resolution order to pick the right one for an `AuthCoreError`.
+ */
+@Catch()
+export class AuthCoreErrorFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const res = host.switchToHttp().getResponse();
+
+    if (exception instanceof AuthCoreError) {
+      res.status(HttpStatus.UNAUTHORIZED).json({ success: false, statusCode: HttpStatus.UNAUTHORIZED, code: exception.code, message: exception.message });
+      return;
+    }
+
+    if (exception instanceof HttpException) {
+      const status = exception.getStatus();
+      const body = exception.getResponse();
+      const shaped = typeof body === "string" ? { message: body } : (body as Record<string, unknown>);
+      res.status(status).json({ success: false, statusCode: status, ...shaped });
+      return;
+    }
+
+    // Anything not thrown deliberately — don't leak internals in the response.
+    res.status(HttpStatus.INTERNAL_SERVER_ERROR).json({ success: false, statusCode: HttpStatus.INTERNAL_SERVER_ERROR, message: "internal server error" });
+  }
+}

package/registry/combos/nestjs-drizzle/shared/src/auth.config.ts

@@ -0,0 +1,65 @@
+import type { PermissionCacheStore } from "./permission-cache.js";
+import type { RateLimitDeps } from "@/lib/auth/core/rate-limit.js";
+
+export const AUTH_CONFIG = Symbol("AUTH_CONFIG");
+
+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;
+  };
+  /** Wire your own mailer here — if unset, requestPasswordReset() just returns the token without emailing it. */
+  sendPasswordResetEmail?: (email: string, token: string) => Promise<void>;
+  /**
+   * 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 windows are counted. Defaults to an in-process `Map`, which is correct for
+   * a single instance; pass a Redis-backed implementation of `RateLimitDeps` for several.
+   */
+  rateLimitStore?: RateLimitDeps;
+}
+
+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/nestjs-drizzle/shared/src/auth.controller.ts

@@ -0,0 +1,299 @@
+import { BadRequestException, Body, Controller, Get, Inject, Ip, Param, Patch, Post, Query, Req, UseGuards } from "@nestjs/common";
+import { ApiBearerAuth, ApiBody, ApiOperation, ApiParam, ApiQuery, ApiResponse, ApiTags } from "@nestjs/swagger";
+import type { Request } from "express";
+import { AUTH_CONFIG, AuthConfig } from "./auth.config.js";
+import { AuthGuard } from "./auth.guard.js";
+import { AuthService } from "./auth.service.js";
+import { AuthzGuard } from "./authz.guard.js";
+import { Authenticated, Public } from "./route-tiers.js";
+import {
+  AuthTokensDto,
+  ChangePasswordDto,
+  ConfirmTwoFactorResponseDto,
+  CurrentUserDto,
+  EnrollTwoFactorResponseDto,
+  ForgotPasswordDto,
+  LoginDto,
+  LoginTwoFactorDto,
+  OAuthStartResponseDto,
+  OkResponseDto,
+  RefreshDto,
+  RefreshResponseDto,
+  ResetPasswordDto,
+  SelfProfileDto,
+  SessionSummaryDto,
+  SignupDto,
+  TwoFactorChallengeDto,
+  TwoFactorCodeDto,
+  UpdateUserDto,
+} from "./dto/auth.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);
+
+/**
+ * Identity endpoints — everything that is about *a user*, never about a group of them.
+ * Administration lives in admin.controller.ts.
+ */
+@ApiTags("auth")
+@Controller("auth")
+export class AuthController {
+  constructor(
+    @Inject(AuthService) private readonly auth: AuthService,
+    @Inject(AUTH_CONFIG) private readonly config: AuthConfig,
+  ) {}
+
+  @Post("signup")
+  @Public()
+  @ApiOperation({ summary: "Create a user and issue a session" })
+  @ApiBody({ type: SignupDto })
+  @ApiResponse({ status: 201, type: AuthTokensDto })
+  async signup(@Body() body: Record<string, unknown>, @Req() req: Request, @Ip() ip: string) {
+    return this.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,
+    });
+  }
+
+  @Post("login")
+  @Public()
+  @ApiOperation({
+    summary: "Log in with email, username, or phone + password",
+    description: "identifier is matched against email, username, and phone, in that order. Returns tokens directly, or a 2FA challenge if the account has 2FA enabled.",
+  })
+  @ApiBody({ type: LoginDto })
+  @ApiResponse({ status: 201, schema: { oneOf: [{ $ref: "#/components/schemas/AuthTokensDto" }, { $ref: "#/components/schemas/TwoFactorChallengeDto" }] } })
+  async login(@Body() body: Record<string, unknown>, @Req() req: Request, @Ip() ip: string) {
+    return this.auth.login({
+      identifier: requireString(body.identifier, "identifier"),
+      password: requireString(body.password, "password"),
+      userAgent: req.headers["user-agent"],
+      ip,
+    });
+  }
+
+  @Post("login/2fa")
+  @Public()
+  @ApiOperation({ summary: "Complete the 2FA challenge from POST /auth/login" })
+  @ApiBody({ type: LoginTwoFactorDto })
+  @ApiResponse({ status: 201, type: AuthTokensDto })
+  async loginTwoFactor(@Body() body: Record<string, unknown>, @Req() req: Request, @Ip() ip: string) {
+    return this.auth.loginTwoFactor({
+      challengeToken: requireString(body.challengeToken, "challengeToken"),
+      code: requireString(body.code, "code"),
+      userAgent: req.headers["user-agent"],
+      ip,
+    });
+  }
+
+  @Post("refresh")
+  @Public()
+  @ApiOperation({ summary: "Rotate a refresh token for a new access+refresh pair" })
+  @ApiBody({ type: RefreshDto })
+  @ApiResponse({ status: 201, type: RefreshResponseDto })
+  async refresh(@Body() body: Record<string, unknown>) {
+    return this.auth.refresh(requireString(body.refreshToken, "refreshToken"));
+  }
+
+  @Get("me")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard, AuthzGuard)
+  @ApiOperation({
+    summary: "Current session's identity",
+    description:
+      "`roles` and `permissions` are whatever applies to this request — see AuthzGuard for how they are resolved. " +
+      "`permissions` is the caller's whole authorization: `defineAbilitiesFor(permissions)` from src/ability.ts rebuilds, " +
+      "in the client, the identical CASL ability the server's own guard just answered with, so the UI cannot disagree with " +
+      "what the API will allow.",
+  })
+  @ApiResponse({ status: 200, type: CurrentUserDto })
+  async me(@Req() req: Request) {
+    const { sub, sessionId } = req.auth!;
+    const [{ twoFactorEnabled }, profile] = await Promise.all([this.auth.getTwoFactorStatus(sub), this.auth.getProfile(sub)]);
+    // The same `req.authz` AbilityGuard's ability was built from — not re-resolved here.
+    return {
+      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,
+    };
+  }
+
+  @Get("sessions")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard)
+  @ApiOperation({ summary: "List the current user's active (non-revoked) sessions" })
+  @ApiResponse({ status: 200, type: [SessionSummaryDto] })
+  async sessions(@Req() req: Request) {
+    return this.auth.listActiveSessions(req.auth!.sub);
+  }
+
+  @Post("logout")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard)
+  @ApiOperation({ summary: "Revoke the current session" })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async logout(@Req() req: Request, @Ip() ip: string) {
+    const { sessionId, jti, sub } = req.auth!;
+    // The revoker is the caller themselves. Recorded so the row can later be told apart from a
+    // session an administrator ended — see `sessions.revoked_by`.
+    await this.auth.logout(sessionId, jti, this.config.accessTokenTtlSeconds, { userId: sub, ip });
+    return { ok: true };
+  }
+
+  @Post("logout-all")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard)
+  @ApiOperation({ summary: "Revoke every session for the current user" })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async logoutAll(@Req() req: Request, @Ip() ip: string) {
+    await this.auth.logoutAll(req.auth!.sub, { userId: req.auth!.sub, ip });
+    return { ok: true };
+  }
+
+  @Post("logout-others")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard)
+  @ApiOperation({ summary: "Revoke every session except the current one" })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async logoutOthers(@Req() req: Request, @Ip() ip: string) {
+    await this.auth.logoutOthers(req.auth!.sub, req.auth!.sessionId, { userId: req.auth!.sub, ip });
+    return { ok: true };
+  }
+
+  @Post("password/change")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard)
+  @ApiOperation({
+    summary: "Change the current password",
+    description: "Requires the current password. Every other session is revoked; the one making this call is left alone.",
+  })
+  @ApiBody({ type: ChangePasswordDto })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async changePassword(@Body() body: Record<string, unknown>, @Req() req: Request) {
+    await this.auth.changePassword(req.auth!.sub, req.auth!.sessionId, {
+      currentPassword: requireString(body.currentPassword, "currentPassword"),
+      newPassword: requireString(body.newPassword, "newPassword"),
+    });
+    return { ok: true };
+  }
+
+  @Patch("me")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard)
+  @ApiOperation({
+    summary: "Update the current user's own profile",
+    description: "Self-service — no admin permission required. Updates the caller's own row directly; unrelated to any workspace.",
+  })
+  @ApiBody({ type: UpdateUserDto })
+  @ApiResponse({ status: 200, type: SelfProfileDto })
+  async updateMe(@Body() body: Record<string, unknown>, @Req() req: Request) {
+    return this.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),
+    });
+  }
+
+  @Post("2fa/enroll")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard)
+  @ApiOperation({ summary: "Begin TOTP enrollment", description: "Not active until confirmed via POST /auth/2fa/confirm." })
+  @ApiResponse({ status: 201, type: EnrollTwoFactorResponseDto })
+  async enrollTwoFactor(@Req() req: Request) {
+    return this.auth.enrollTwoFactor(req.auth!.sub);
+  }
+
+  @Post("2fa/confirm")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard)
+  @ApiOperation({ summary: "Confirm TOTP enrollment with a code", description: "Enables 2FA and returns one-time backup codes, shown only here." })
+  @ApiBody({ type: TwoFactorCodeDto })
+  @ApiResponse({ status: 201, type: ConfirmTwoFactorResponseDto })
+  async confirmTwoFactor(@Body() body: Record<string, unknown>, @Req() req: Request) {
+    return this.auth.confirmTwoFactor(req.auth!.sub, requireString(body.code, "code"));
+  }
+
+  @Post("2fa/disable")
+  @Authenticated()
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard)
+  @ApiOperation({ summary: "Disable 2FA", description: "Requires a valid TOTP or backup code." })
+  @ApiBody({ type: TwoFactorCodeDto })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async disableTwoFactor(@Body() body: Record<string, unknown>, @Req() req: Request) {
+    await this.auth.disableTwoFactor(req.auth!.sub, requireString(body.code, "code"));
+    return { ok: true };
+  }
+
+  @Post("password/forgot")
+  @Public()
+  @ApiOperation({ summary: "Request a password reset", description: "Always reports success, whether or not the email exists — avoids account enumeration." })
+  @ApiBody({ type: ForgotPasswordDto })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async forgotPassword(@Body() body: Record<string, unknown>) {
+    await this.auth.requestPasswordReset(requireString(body.email, "email"));
+    return { ok: true }; // always 200 — never reveal whether the email exists
+  }
+
+  @Post("password/reset")
+  @Public()
+  @ApiOperation({ summary: "Complete a password reset", description: "Revokes every existing session for the user on success." })
+  @ApiBody({ type: ResetPasswordDto })
+  @ApiResponse({ status: 201, type: OkResponseDto })
+  async resetPassword(@Body() body: Record<string, unknown>) {
+    await this.auth.resetPassword(requireString(body.token, "token"), requireString(body.newPassword, "newPassword"));
+    return { ok: true };
+  }
+
+  @Get("oauth/:provider/start")
+  @Public()
+  @ApiOperation({ summary: "Get the redirect URL to start an OAuth login" })
+  @ApiParam({ name: "provider", enum: ["google", "apple"] })
+  @ApiResponse({ status: 200, type: OAuthStartResponseDto })
+  async oauthStart(@Param("provider") provider: string) {
+    return this.auth.startOAuth(provider);
+  }
+
+  @Get("oauth/:provider/callback")
+  @Public()
+  @ApiOperation({ summary: "OAuth provider callback — exchanges the code and completes login" })
+  @ApiParam({ name: "provider", enum: ["google", "apple"] })
+  @ApiQuery({ name: "code", required: true })
+  @ApiQuery({ name: "state", required: true })
+  @ApiResponse({ status: 200, type: AuthTokensDto })
+  async oauthCallback(@Param("provider") provider: string, @Query("code") code: string, @Query("state") state: string) {
+    return this.auth.completeOAuthCallback(provider, requireString(code, "code"), requireString(state, "state"));
+  }
+}

package/registry/combos/nestjs-drizzle/shared/src/auth.guard.ts

@@ -0,0 +1,34 @@
+import { CanActivate, ExecutionContext, Inject, Injectable, UnauthorizedException } from "@nestjs/common";
+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";
+
+/**
+ * Authentication only — proves who the caller is and populates `req.auth`. Authorization
+ * (`req.authz`) is a deliberately separate step: pair this with `AuthzGuard` on any route
+ * that checks roles or permissions.
+ */
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(
+    @Inject(KeyProviderService) private readonly keys: KeyProviderService,
+    @Inject(SessionRepository) private readonly sessions: SessionRepository,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const req = context.switchToHttp().getRequest();
+    const header: string | undefined = req.headers["authorization"];
+    if (!header?.startsWith("Bearer ")) throw new UnauthorizedException("missing bearer token");
+
+    try {
+      req.auth = await verifyAccessToken(
+        { secret: this.keys.secret, isDenylisted: (jti) => this.sessions.isDenylisted(jti) },
+        header.slice("Bearer ".length),
+      );
+    } catch (err) {
+      throw new UnauthorizedException(err instanceof Error ? err.message : "invalid access token");
+    }
+    return true;
+  }
+}

package/registry/combos/nestjs-drizzle/shared/src/db.ts

@@ -0,0 +1,12 @@
+// Drizzle has no client *class* the way Prisma has `PrismaClient`, so there's nothing to hand
+// NestJS's DI as an implicit constructor type the way the reference combo does. We mint an
+// explicit injection token instead (same idea as `AUTH_CONFIG` in auth.config.ts) and every
+// constructor in this combo uses `@Inject(DRIZZLE_DB)` — matching the reference's explicit-token
+// style, which is required (not just stylistic) for DI to keep working under esbuild-based
+// tooling like tsx that skips `emitDecoratorMetadata`'s runtime type reflection.
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type * as schema from "./schema.js";
+
+export const DRIZZLE_DB = Symbol("DRIZZLE_DB");
+
+export type Database = NodePgDatabase<typeof schema>;