@simple-auth-kit/cli 1.0.0

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

@@ -0,0 +1,29 @@
+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 — no role-based bypass beside it, so a role
+// carrying no permissions confers no authority. Fail-closed: no ability, a missing slug, or a
+// route that declares none of them all reject rather than pass.
+@Injectable()
+export class AbilityGuard implements CanActivate {
+  // Explicit @Inject: 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-prisma/shared/src/ability.ts

@@ -0,0 +1,23 @@
+// Deliberately not a Nest provider: no dependencies, no I/O, imported by both the server and
+// whatever renders the admin UI, so it must work outside a DI container and outside Node. Both
+// sides build the ability from the same flat permission-slug list with this same function, so
+// the console can never offer an action the API would refuse.
+//
+// A permission slug is CASL's *action*; the subject is always a constant empty string. That
+// keeps the model flat — no subject taxonomy, no (action, subject) pairing to get wrong, no
+// conditions.
+import { AbilityBuilder, createMongoAbility, type MongoAbility } from "@casl/ability";
+
+// Constant rather than a repeated string literal — `can("users:read", "")` in one place and
+// `can("users:read", "all")` in another would silently never match.
+export const ABILITY_SUBJECT = "";
+
+export type AppAbility = MongoAbility<[string, typeof ABILITY_SUBJECT]>;
+
+// An empty list builds an ability with no rules, which denies everything — the fail-closed
+// answer whether permissions failed to resolve or the user genuinely has none.
+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-prisma/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-prisma/shared/src/auth.config.ts

@@ -0,0 +1,71 @@
+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;
+}
+
+/** One global rate-limit bucket, shaped exactly like a @nestjs/throttler entry. `ttl` is milliseconds. */
+export interface ThrottleBucket {
+  name: string;
+  ttl: number;
+  limit: number;
+}
+
+export interface AuthConfig {
+  accessTokenTtlSeconds: number;
+  refreshTokenTtlSeconds: number;
+  // A session's absolute lifetime, never extended by refresh rotation — the cap that makes
+  // "log in again after N days" true regardless of activity. Enforced by `rotateRefreshToken`.
+  sessionTtlSeconds: number;
+  /** App name shown inside authenticator apps (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>;
+  // Safety net, not the invalidation mechanism — correctness comes from the version counters in
+  // permission-cache.ts. Set to 0 to resolve from the database on every request.
+  permissionCacheTtlSeconds: number;
+  // Defaults to an in-process Map; pass a Redis-backed PermissionCacheStore for multiple
+  // instances. Keys are namespaced `simpleauthkit:authz:*`.
+  permissionCacheStore?: PermissionCacheStore;
+  // Defaults to an in-process Map; pass a Redis-backed RateLimitDeps for multiple instances.
+  rateLimitStore?: RateLimitDeps;
+  // Enforced by a globally registered ThrottlerGuard, per client IP, all buckets at once.
+  // `false` removes the guard entirely — the escape hatch for load tests and proofs whose
+  // request rate is the point, not an abuse signal.
+  throttle: ThrottleBucket[] | false;
+}
+
+// Exported by name so `@SkipThrottle` call sites can name every default bucket —
+// `@SkipThrottle()` bare only skips a throttler literally named "default", which none of these is.
+export const defaultThrottleBuckets: ThrottleBucket[] = [
+  { name: "short", ttl: 1_000, limit: 100 },
+  { name: "medium", ttl: 10_000, limit: 200 },
+  { name: "long", ttl: 60_000, limit: 400 },
+];
+
+export const defaultAuthConfig: AuthConfig = {
+  accessTokenTtlSeconds: 900,
+  permissionCacheTtlSeconds: 300,
+  throttle: defaultThrottleBuckets,
+  refreshTokenTtlSeconds: 60 * 60 * 24 * 30,
+  sessionTtlSeconds: 60 * 60 * 24 * 30,
+  twoFactorIssuer: "simple-auth-kit",
+  oauthProviders: {},
+};

package/registry/combos/nestjs-prisma/shared/src/auth.controller.ts

@@ -0,0 +1,303 @@
+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 { SkipThrottle } from "@nestjs/throttler";
+import type { Request } from "express";
+import { AUTH_CONFIG, AuthConfig, defaultThrottleBuckets } 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()
+  // Clients hit this on every navigation to verify the token is still live — identity checks
+  // must not consume the abuse budget. Metadata only in variants that don't register the guard.
+  @SkipThrottle(Object.fromEntries(defaultThrottleBuckets.map((bucket) => [bucket.name, true])))
+  @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-prisma/shared/src/auth.guard.ts

@@ -0,0 +1,31 @@
+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`. Pair 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;
+  }
+}