@simple-auth-kit/cli 1.0.0

package/registry/combos/nestjs-prisma/variants/base/src/audit-log.gateway.ts

@@ -0,0 +1,51 @@
+import { Inject } from "@nestjs/common";
+import { OnGatewayConnection, WebSocketGateway, WebSocketServer } from "@nestjs/websockets";
+import type { Server, Socket } from "socket.io";
+import { verifyAccessToken } from "@/lib/auth/core/token-service.js";
+import { AuditLogEntry, AuditLogRepository } from "./audit-log.repository.js";
+import { KeyProviderService } from "./key-provider.js";
+import { SessionRepository } from "./session.repository.js";
+
+// socket.io clients disagree on where a bearer token travels: `auth.token` (the socket.io-native
+// slot), an Authorization header, or a `token` query param. Accept all three, first present wins.
+function extractToken(client: Socket): string | undefined {
+  const raw = client.handshake.auth?.["token"] ?? client.handshake.headers.authorization ?? client.handshake.query?.["token"];
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  if (typeof value !== "string" || value.length === 0) return undefined;
+  return value.startsWith("Bearer ") ? value.slice("Bearer ".length) : value;
+}
+
+// Live feed of the audit log. This gateway only pushes, so the single decision is whether a
+// socket may attach at all — made with the same `verifyAccessToken` + session-denylist pair
+// AuthGuard uses on HTTP, not a parallel verification path.
+@WebSocketGateway({ namespace: "/audit-logs", cors: { origin: true } })
+export class AuditLogGateway implements OnGatewayConnection {
+  @WebSocketServer()
+  private server?: Server;
+
+  constructor(
+    @Inject(KeyProviderService) private readonly keys: KeyProviderService,
+    @Inject(SessionRepository) private readonly sessions: SessionRepository,
+    @Inject(AuditLogRepository) auditLog: AuditLogRepository,
+  ) {
+    auditLog.onAppend((entry) => this.broadcast(entry));
+  }
+
+  async handleConnection(client: Socket): Promise<void> {
+    const token = extractToken(client);
+    if (!token) {
+      client.disconnect(true);
+      return;
+    }
+    try {
+      await verifyAccessToken({ secret: this.keys.secret, isDenylisted: (jti) => this.sessions.isDenylisted(jti) }, token);
+    } catch {
+      client.disconnect(true);
+    }
+  }
+
+  private broadcast(entry: AuditLogEntry): void {
+    // Undefined only before gateway init — a write that early is simply not broadcast.
+    this.server?.emit("audit-log:created", entry);
+  }
+}

package/registry/combos/nestjs-prisma/variants/base/src/audit-log.repository.ts

@@ -0,0 +1,111 @@
+import { Inject, Injectable } from "@nestjs/common";
+import type { AuditEvent } from "@/lib/auth/core/types.js";
+import { Prisma, PrismaClient } from "../generated/prisma/client.js";
+import { toIdOrNull, toIdOrUndefined } from "./id.helper.js";
+import { buildPageMeta, normalizeLimit, normalizePage, type Paginated } from "./pagination.js";
+
+export interface AuditLogEntry {
+  id: string;
+  userId: string | null;
+  name: string;
+  action: string;
+  info: unknown;
+  remarks: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AuditLogListFilter {
+  userId?: string;
+  action?: string;
+  since?: string;
+  until?: string;
+  page?: number;
+  limit?: number;
+}
+
+// "role_assigned" -> "Role assigned". Derived rather than passed in, so core never carries display text.
+export function humanizeAction(action: string): string {
+  const words = action.split("_");
+  return [words[0].charAt(0).toUpperCase() + words[0].slice(1), ...words.slice(1)].join(" ");
+}
+
+/** An `AuditLog` row as `findMany` returns it. */
+export type AuditLogRow = Prisma.AuditLogGetPayload<object>;
+
+/** Shapes a raw row into the wire DTO — applied by the caller (`AuthService.listAuditLog`), not here. */
+export function toAuditLogEntry(row: AuditLogRow): AuditLogEntry {
+  return {
+    id: row.id.toString(),
+    userId: row.userId?.toString() ?? null,
+    name: row.name,
+    action: row.action,
+    info: row.info,
+    remarks: row.remarks,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+type AuditLogListener = (entry: AuditLogEntry) => void;
+
+@Injectable()
+export class AuditLogRepository {
+  // How the WS gateway hears about writes without this repository knowing sockets exist —
+  // the gateway depends on SessionRepository, which depends on this class, so injecting the
+  // gateway here would close a dependency cycle.
+  private readonly listeners = new Set<AuditLogListener>();
+
+  constructor(@Inject(PrismaClient) private readonly prisma: PrismaClient) {}
+
+  /** Fires after every successful write, with the same wire shape the REST list endpoint returns. */
+  onAppend(listener: AuditLogListener): void {
+    this.listeners.add(listener);
+  }
+
+  async append(event: AuditEvent, opts: { remarks?: string } = {}): Promise<void> {
+    const row = await this.prisma.auditLog.create({
+      data: {
+        action: event.type,
+        name: humanizeAction(event.type),
+        userId: "userId" in event ? toIdOrNull(event.userId) : null,
+        info: event as unknown as Prisma.InputJsonValue,
+        remarks: opts.remarks ?? null,
+      },
+    });
+    const entry = toAuditLogEntry(row);
+    for (const listener of this.listeners) {
+      try {
+        listener(entry);
+      } catch {
+        // A broken broadcast must never fail the operation being audited.
+      }
+    }
+  }
+
+  /** Newest-first, page-paginated. Returns raw rows — shaping is the caller's job, see `toAuditLogEntry`. */
+  async list(filter: AuditLogListFilter): Promise<Paginated<AuditLogRow>> {
+    const page = normalizePage(filter.page);
+    const limit = normalizeLimit(filter.limit);
+    const where = {
+      userId: toIdOrUndefined(filter.userId),
+      action: filter.action,
+      createdAt: {
+        gte: filter.since ? new Date(filter.since) : undefined,
+        lte: filter.until ? new Date(filter.until) : undefined,
+      },
+    };
+
+    const [rows, total] = await this.prisma.$transaction([
+      this.prisma.auditLog.findMany({
+        where,
+        orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+        take: limit,
+        skip: (page - 1) * limit,
+      }),
+      this.prisma.auditLog.count({ where }),
+    ]);
+
+    return { items: rows, meta: buildPageMeta(page, limit, total) };
+  }
+}

package/registry/combos/nestjs-prisma/variants/base/src/auth.module.ts

@@ -0,0 +1,87 @@
+import { PrismaPg } from "@prisma/adapter-pg";
+import { DynamicModule, Module } from "@nestjs/common";
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR } from "@nestjs/core";
+import { ThrottlerGuard, ThrottlerModule } from "@nestjs/throttler";
+import { AbilityGuard } from "./ability.guard.js";
+import { AdminController } from "./admin.controller.js";
+import { AuditLogGateway } from "./audit-log.gateway.js";
+import { AuditLogRepository } from "./audit-log.repository.js";
+import { AuthCoreErrorFilter } from "./auth-core-error.filter.js";
+import { AUTH_CONFIG, AuthConfig, defaultAuthConfig } from "./auth.config.js";
+import { AuthController } from "./auth.controller.js";
+import { AuthGuard } from "./auth.guard.js";
+import { AuthService } from "./auth.service.js";
+import { AuthzGuard } from "./authz.guard.js";
+import { PrismaClient } from "../generated/prisma/client.js";
+import { CountryRepository } from "./country.repository.js";
+import { CustomerRepository } from "./customer.repository.js";
+import { KeyProviderService } from "./key-provider.js";
+import { LanguageRepository } from "./language.repository.js";
+import { OAuthRepository } from "./oauth.repository.js";
+import { PasswordResetRepository } from "./password-reset.repository.js";
+import { InMemoryPermissionCacheStore, PERMISSION_CACHE_STORE, PermissionCache } from "./permission-cache.js";
+import { InMemoryRateLimitStore, RATE_LIMIT_STORE } from "./rate-limit.store.js";
+import { RbacRepository } from "./rbac.repository.js";
+import { ResponseInterceptor } from "./response.interceptor.js";
+import { assertEveryRouteDeclaresATier } from "./route-tiers.js";
+import { SessionRepository } from "./session.repository.js";
+import { TwoFactorRepository } from "./two-factor.repository.js";
+
+// Both what the module registers and what the startup tier check walks — one list, so a
+// controller can't be added and left out of the check.
+const AUTH_CONTROLLERS = [AuthController, AdminController];
+
+@Module({})
+export class AuthModule {
+  static forRoot(config: Partial<AuthConfig> = {}): DynamicModule {
+    // Fail-closed before anything else exists — nothing above this line allocates a database
+    // client or a port, so a failed boot leaves nothing behind.
+    assertEveryRouteDeclaresATier(AUTH_CONTROLLERS, { authentication: AuthGuard, ability: AbilityGuard });
+
+    const resolved: AuthConfig = { ...defaultAuthConfig, ...config };
+    const adapter = new PrismaPg({ connectionString: process.env["DATABASE_URL"] });
+
+    if (!config.permissionCacheStore || !config.rateLimitStore) {
+      console.warn(
+        "[simple-auth-kit] permissionCacheStore/rateLimitStore not overridden — using in-memory defaults. " +
+          "Fine for a single instance; silently inconsistent (stale grants, wrong rate-limit counts) " +
+          "across replicas once you run more than one. Override permissionCacheStore/rateLimitStore " +
+          "with a shared store (e.g. Redis) in AuthModule.forRoot() before scaling out.",
+      );
+    }
+    return {
+      module: AuthModule,
+      imports: resolved.throttle === false ? [] : [ThrottlerModule.forRoot(resolved.throttle)],
+      controllers: AUTH_CONTROLLERS,
+      providers: [
+        { provide: AUTH_CONFIG, useValue: resolved },
+        { provide: PrismaClient, useValue: new PrismaClient({ adapter }) },
+        // Swap for a Redis-backed store by passing `permissionCacheStore` to forRoot.
+        { provide: PERMISSION_CACHE_STORE, useValue: config.permissionCacheStore ?? new InMemoryPermissionCacheStore() },
+        PermissionCache,
+        { provide: APP_FILTER, useClass: AuthCoreErrorFilter },
+        { provide: APP_INTERCEPTOR, useClass: ResponseInterceptor },
+        // Registered from here rather than the consumer's root module so throttling ships with
+        // the combo. Runs before the route-level guards, exactly like every other APP_GUARD.
+        ...(resolved.throttle === false ? [] : [{ provide: APP_GUARD, useClass: ThrottlerGuard }]),
+        AuditLogRepository,
+        AuditLogGateway,
+        SessionRepository,
+        KeyProviderService,
+        { provide: RATE_LIMIT_STORE, useValue: config.rateLimitStore ?? new InMemoryRateLimitStore() },
+        RbacRepository,
+        TwoFactorRepository,
+        OAuthRepository,
+        PasswordResetRepository,
+        CountryRepository,
+        LanguageRepository,
+        CustomerRepository,
+        AuthService,
+        AuthGuard,
+        AuthzGuard,
+        AbilityGuard,
+      ],
+      exports: [AuthService, AuthGuard, AuthzGuard, AbilityGuard, PermissionCache, PrismaClient],
+    };
+  }
+}