@podosoft/podokit 0.2.0 → 0.4.0

package/dist/templates/modules/admin-dashboard/files/tests/ui/users-crud.ui.spec.ts

@@ -0,0 +1,129 @@
+import { expect, test, type Page } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5173";
+
+// Seed a throwaway user via the API (admin cookies come from storageState) so
+// the mutating UI tests don't touch the shared admin/user seed accounts.
+async function seedUser(page: Page, email: string): Promise<void> {
+  const res = await page.request.post("/api/auth/admin/create-user", {
+    headers: { origin: base },
+    data: { email, password: "password123", name: "Throwaway", role: "user" },
+  });
+  expect(res.ok()).toBeTruthy();
+}
+
+// Open the Manage two-pane modal for a seeded user.
+async function openManage(page: Page, email: string): Promise<void> {
+  await page.getByPlaceholder("Search by email…").fill(email);
+  await page.getByRole("row", { name: new RegExp(email) }).getByRole("button").click();
+  await page.getByRole("menuitem", { name: "Manage" }).click();
+}
+
+test("admin can create a user via the dialog @smoke", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const email = `ui-create-${Date.now()}@example.com`;
+  await page.getByRole("button", { name: "Add user" }).click();
+  const dialog = page.getByRole("dialog");
+  await dialog.getByLabel("Name").fill("Created");
+  await dialog.getByLabel("Email").fill(email);
+  await dialog.getByLabel("Password", { exact: true }).fill("password123");
+  await dialog.getByLabel("Confirm password").fill("password123");
+  await dialog.getByRole("button", { name: "Create" }).click();
+  await page.getByPlaceholder("Search by email…").fill(email);
+  await expect(page.getByRole("cell", { name: email })).toBeVisible();
+});
+
+test("create rejects mismatched passwords", async ({ page }) => {
+  await ready(page, "/admin/users");
+  await page.getByRole("button", { name: "Add user" }).click();
+  const dialog = page.getByRole("dialog");
+  await dialog.getByLabel("Name").fill("Mismatch");
+  await dialog.getByLabel("Email").fill(`ui-mismatch-${Date.now()}@example.com`);
+  await dialog.getByLabel("Password", { exact: true }).fill("password123");
+  await dialog.getByLabel("Confirm password").fill("different999");
+  await dialog.getByRole("button", { name: "Create" }).click();
+  await expect(dialog.getByText("Passwords do not match")).toBeVisible();
+});
+
+test("manage: edit profile name @smoke", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const email = `ui-edit-${Date.now()}@example.com`;
+  await seedUser(page, email);
+  await openManage(page, email);
+  const dialog = page.getByRole("dialog");
+  await dialog.getByLabel("Name").fill("Edited Name");
+  await dialog.getByRole("button", { name: "Save" }).click();
+  await expect(page.getByText("User updated")).toBeVisible();
+});
+
+test("manage: set a password (and reject mismatch)", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const email = `ui-setpw-${Date.now()}@example.com`;
+  await seedUser(page, email);
+  await openManage(page, email);
+  const dialog = page.getByRole("dialog");
+  await dialog.getByRole("button", { name: "Security" }).click();
+  await dialog.getByLabel("New password", { exact: true }).fill("newpass1234");
+  await dialog.getByLabel("Confirm new password").fill("different999");
+  await dialog.getByRole("button", { name: "Set password" }).click();
+  await expect(dialog.getByText("Passwords do not match")).toBeVisible();
+  await dialog.getByLabel("Confirm new password").fill("newpass1234");
+  await dialog.getByRole("button", { name: "Set password" }).click();
+  await expect(page.getByText("Password updated")).toBeVisible();
+});
+
+test("manage: ban a user with a reason", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const email = `ui-ban-${Date.now()}@example.com`;
+  await seedUser(page, email);
+  await openManage(page, email);
+  const dialog = page.getByRole("dialog");
+  await dialog.getByRole("button", { name: "Security" }).click();
+  await dialog.getByLabel("Reason (optional)").fill("policy violation");
+  await dialog.getByRole("button", { name: "Ban", exact: true }).click();
+  await expect(page.getByText("User banned", { exact: true })).toBeVisible();
+});
+
+test("manage: revoke a user's session", async ({ page, playwright }) => {
+  await ready(page, "/admin/users");
+  const email = `ui-sess-${Date.now()}@example.com`;
+  await seedUser(page, email);
+  // create a session for the user in an isolated context (don't touch the admin cookie)
+  const uctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: { origin: base } });
+  expect((await uctx.post("/api/auth/sign-in/email", { data: { email, password: "password123" } })).ok()).toBeTruthy();
+  await uctx.dispose();
+  await openManage(page, email);
+  const dialog = page.getByRole("dialog");
+  await dialog.getByRole("button", { name: "Sessions" }).click();
+  await dialog.getByRole("button", { name: "Revoke", exact: true }).first().click();
+  await expect(page.getByText("Session revoked")).toBeVisible();
+});
+
+test("manage: delete a user from the danger zone", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const email = `ui-delete-${Date.now()}@example.com`;
+  await seedUser(page, email);
+  await openManage(page, email);
+  const dialog = page.getByRole("dialog");
+  await dialog.getByRole("button", { name: "Danger zone" }).click();
+  await dialog.getByRole("button", { name: "Delete" }).click(); // arm
+  await dialog.getByRole("button", { name: "Delete" }).click(); // confirm
+  await expect(page.getByText("User deleted")).toBeVisible();
+  await page.getByPlaceholder("Search by email…").fill(email);
+  await expect(page.getByRole("cell", { name: email })).toHaveCount(0);
+});
+
+test("users list shows pagination beyond one page", async ({ page }) => {
+  await ready(page, "/admin/users");
+  for (let i = 0; i < 6; i += 1) {
+    await page.request.post("/api/auth/admin/create-user", {
+      headers: { origin: base },
+      data: { email: `pg-${Date.now()}-${i}@example.com`, password: "password123", name: `Pg${i}`, role: "user" },
+    });
+  }
+  await page.reload();
+  const nav = page.getByRole("navigation", { name: "pagination" });
+  await expect(nav).toBeVisible();
+  await expect(nav.getByRole("button", { name: "Page 2" })).toBeVisible();
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/users.ui.spec.ts

@@ -0,0 +1,19 @@
+import { expect, test } from "@playwright/test";
+
+test("admin sees the user list and can search @smoke", async ({ page }) => {
+  await page.goto("/admin/users");
+  await expect(page.getByRole("heading", { name: "Users" })).toBeVisible();
+  await expect(page.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
+  await page.getByPlaceholder("Search by email…").fill("user@");
+  await expect(page.getByRole("cell", { name: "user@example.com" })).toBeVisible();
+  await expect(page.getByRole("cell", { name: "admin@example.com" })).toHaveCount(0);
+});
+
+test("row menu exposes admin actions", async ({ page }) => {
+  await page.goto("/admin/users");
+  await page.getByPlaceholder("Search by email…").fill("user@example.com");
+  const row = page.getByRole("row", { name: /user@example.com/ });
+  await row.getByRole("button").click();
+  await expect(page.getByRole("menuitem", { name: "Manage" })).toBeVisible();
+  await expect(page.getByRole("menuitem", { name: "Impersonate" })).toBeVisible();
+});

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -0,0 +1,41 @@
+{
+  "name": "admin-dashboard",
+  "description": "Admin dashboard UI (SvelteKit + shadcn-svelte): login/signup/password-reset, a sidebar shell, and user + session management via the better-auth admin plugin. Requires auth.",
+  "requires": [
+    "auth"
+  ],
+  "targetApp": "web",
+  "env": [
+    "# admin-dashboard: emails auto-promoted to the admin role on sign-up (comma-separated)",
+    "ADMIN_EMAILS=admin@example.com"
+  ],
+  "inject": [
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "marker": "// podokit:auth-imports",
+      "text": "import { admin } from \"better-auth/plugins\";"
+    },
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "marker": "// podokit:auth-plugins",
+      "text": "plugins.push(admin({ defaultRole: \"user\", adminRoles: [\"admin\"] }));"
+    },
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "marker": "// podokit:auth-email-password",
+      "text": "sendResetPassword: async ({ user, url }) => {\n      console.log(`[auth] password reset for ${user.email}: ${url}`);\n    },"
+    },
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "marker": "// podokit:auth-options",
+      "text": "trustedOrigins: (process.env.CORS_ORIGIN ?? \"http://localhost:5173\").split(\",\").map((origin) => origin.trim()),\n  databaseHooks: {\n    user: {\n      create: {\n        before: async (user) => ({\n          data: {\n            ...user,\n            role: (process.env.ADMIN_EMAILS ?? \"\")\n              .split(\",\")\n              .map((email) => email.trim().toLowerCase())\n              .includes(user.email.toLowerCase())\n              ? \"admin\"\n              : \"user\",\n          },\n        }),\n      },\n    },\n  },"
+    }
+  ],
+  "instructions": [
+    "Set ADMIN_EMAILS in .env (comma-separated). Those emails become admins on sign-up.",
+    "Re-run the auth migration to add the admin columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
+    "Start the app (npm run dev), open /signup, register an ADMIN_EMAILS address, then sign in.",
+    "Admin pages: /dashboard/users (list, ban, set role, revoke sessions). Everyone: /dashboard/sessions, /dashboard/account.",
+    "Password reset: the reset link is logged to the API console in dev; wire a real mailer via emailAndPassword.sendResetPassword for production."
+  ]
+}

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.decorator.ts

@@ -0,0 +1,9 @@
+import { applyDecorators, UseGuards } from "@nestjs/common";
+import { Public } from "@thallesp/nestjs-better-auth";
+import { ApiKeyGuard } from "./api-key.guard";
+
+// Opens a route to API-key holders: skips the user-session guard and
+// requires a valid X-API-Key instead. For machine/service clients.
+export function ApiKeyProtected(): ReturnType<typeof applyDecorators> {
+  return applyDecorators(Public(), UseGuards(ApiKeyGuard));
+}

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.guard.ts

@@ -0,0 +1,29 @@
+import { type CanActivate, type ExecutionContext, Injectable, UnauthorizedException } from "@nestjs/common";
+import { timingSafeEqual } from "node:crypto";
+import type { Request } from "express";
+
+// Validates the X-API-Key header against the API_KEYS allowlist.
+@Injectable()
+export class ApiKeyGuard implements CanActivate {
+  private readonly keys = (process.env.API_KEYS ?? "")
+    .split(",")
+    .map((key) => key.trim())
+    .filter(Boolean);
+
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<Request>();
+    const provided = request.header("x-api-key");
+    if (!provided) {
+      throw new UnauthorizedException("Missing X-API-Key");
+    }
+    const supplied = Buffer.from(provided);
+    const valid = this.keys.some((key) => {
+      const expected = Buffer.from(key);
+      return expected.length === supplied.length && timingSafeEqual(expected, supplied);
+    });
+    if (!valid) {
+      throw new UnauthorizedException("Invalid API key");
+    }
+    return true;
+  }
+}

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.module.ts

@@ -0,0 +1,9 @@
+import { Module } from "@nestjs/common";
+import { MachineController } from "../machine/machine.controller";
+import { ApiKeyGuard } from "./api-key.guard";
+
+@Module({
+  controllers: [MachineController],
+  providers: [ApiKeyGuard],
+})
+export class ApiKeyModule {}

package/dist/templates/modules/api-key-auth/files/apps/api/src/machine/machine.controller.ts

@@ -0,0 +1,14 @@
+import { Controller, Get } from "@nestjs/common";
+import { ApiTags } from "@nestjs/swagger";
+import { ApiKeyProtected } from "../api-key/api-key.decorator";
+
+@ApiTags("machine")
+@Controller("machine")
+export class MachineController {
+  // Reachable with a valid X-API-Key, no user session required.
+  @ApiKeyProtected()
+  @Get("ping")
+  ping(): { ok: true; via: "api-key" } {
+    return { ok: true, via: "api-key" };
+  }
+}

package/dist/templates/modules/api-key-auth/module.manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "api-key-auth",
+  "description": "API-key auth for machine/service clients (X-API-Key), separate from user sessions. Provides an ApiKeyGuard and @ApiKeyProtected() to open a route to key holders. Requires auth.",
+  "requires": ["auth"],
+  "targetApp": "api",
+  "env": [
+    "# api keys for machine clients (comma-separated)",
+    "API_KEYS=dev-key-please-change"
+  ],
+  "inject": [
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { ApiKeyModule } from \"./api-key/api-key.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "ApiKeyModule," }
+  ],
+  "instructions": [
+    "Set API_KEYS in .env (comma-separated).",
+    "Protect a route for machine clients with @ApiKeyProtected() (bypasses the user session, requires X-API-Key).",
+    "Call it:  curl -H 'x-api-key: dev-key-please-change' localhost:3000/machine/ping"
+  ]
+}

package/dist/templates/modules/audit-log/files/apps/api/src/audit/README.md

@@ -0,0 +1,59 @@
+# Audit log
+
+An append-only trail of **who did what, to which resource, when** — the
+actor / action / target model. Every entry flows through one pipeline
+(`AuditService` → the `audit_logs` table) so they all share one shape.
+
+## What gets recorded
+
+Nothing is recorded automatically except the built-in **auth/admin actions**
+(login, user create/update/delete, ban, role change, session revoke, ...),
+which the better-auth hook (`audit-hook.ts`) maps to semantic action codes like
+`user.create` and `auth.login`. Everything else is **opt-in** — you decide what
+matters.
+
+## Audit your own routes with `@Audit`
+
+```ts
+import { Audit } from "../audit/audit.decorator";
+
+@Post()
+@Audit("todo.create", (_req, todo) => ({ type: "todo", id: todo.id, label: todo.title }))
+create(@Body() dto: CreateTodoDto) {
+  return this.todos.create(dto);
+}
+```
+
+The interceptor resolves the acting user (name + email), attaches the target you
+return, and writes one entry when the handler succeeds.
+
+## Record from anywhere in code
+
+```ts
+import { recordAudit } from "../audit/audit-events";
+
+await recordAudit({
+  action: "invoice.paid",
+  actorId, actorName, actorEmail,
+  targetType: "invoice", targetId: invoice.id, targetLabel: invoice.number,
+  metadata: { amount },
+});
+```
+
+Or inject `AuditService` in a Nest provider and call `audit.record({ ... })`.
+Both never throw — a failed audit write never breaks the request.
+
+## Fields (`AuditEntry`)
+
+`action` (semantic code), `actorId/actorName/actorEmail` (denormalized so the log
+survives renames/deletes), `targetType/targetId/targetLabel`, `ip`, `metadata`
+(jsonb, free-form), `createdAt`.
+
+## Customize
+
+- **Auth actions:** edit the `ACTIONS` map in `audit-hook.ts`.
+- **Your routes:** add `@Audit("your.action")` where you want a trail.
+- **Schema:** add columns to `audit-log.entity.ts` + a migration, and keep the
+  `AuditEntry` type in `audit-events.ts` in sync.
+- **Reading:** `GET /audit-logs` returns the latest 50 (admin only); extend
+  `audit.controller.ts` for filtering/pagination.

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-events.ts

@@ -0,0 +1,34 @@
+// One audit pipeline for the whole app. Every source — the @Audit decorator, the
+// better-auth hook, and your own code — records through here, so all entries
+// share the actor/action/target shape and one write path (audit_logs).
+
+export type AuditEntry = {
+  // Stable semantic action code, e.g. "user.create", "invoice.paid".
+  action: string;
+  actorId?: string | null;
+  actorName?: string | null;
+  actorEmail?: string | null;
+  targetType?: string | null;
+  targetId?: string | null;
+  targetLabel?: string | null;
+  ip?: string | null;
+  metadata?: Record<string, unknown> | null;
+};
+
+type Recorder = (entry: AuditEntry) => Promise<void>;
+let recorder: Recorder | null = null;
+
+// AuditService registers the real recorder on startup. The registry lives outside
+// Nest's DI so code that runs outside the container (the better-auth hook,
+// background jobs, ...) can still write through the one pipeline.
+export function setAuditRecorder(fn: Recorder): void {
+  recorder = fn;
+}
+
+// Record a custom audit event from anywhere. Awaits the write; a no-op until the
+// AuditService has started. Example:
+//   await recordAudit({ action: "invoice.paid", actorId, targetLabel: invoice.number,
+//                       metadata: { amount } });
+export async function recordAudit(entry: AuditEntry): Promise<void> {
+  if (recorder) await recorder(entry);
+}

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-hook.ts

@@ -0,0 +1,70 @@
+import { createAuthMiddleware } from "better-auth/api";
+import { recordAudit } from "./audit-events";
+
+// Map mutating auth/admin endpoints to semantic action codes. better-auth is
+// mounted as middleware and bypasses the NestJS interceptor, so these security
+// events are caught here and recorded through the same pipeline.
+const ACTIONS: Record<string, string> = {
+  "/sign-in/email": "auth.login",
+  "/sign-up/email": "auth.signup",
+  "/sign-out": "auth.logout",
+  "/change-password": "auth.password_change",
+  "/change-email": "auth.email_change",
+  "/reset-password": "auth.password_reset",
+  "/update-user": "account.update",
+  "/delete-user": "account.delete",
+  "/revoke-session": "session.revoke",
+  "/revoke-sessions": "session.revoke_all",
+  "/revoke-other-sessions": "session.revoke_others",
+  "/two-factor/enable": "2fa.enable",
+  "/two-factor/disable": "2fa.disable",
+  "/admin/create-user": "user.create",
+  "/admin/update-user": "user.update",
+  "/admin/remove-user": "user.delete",
+  "/admin/set-role": "user.role_change",
+  "/admin/set-user-password": "user.password_set",
+  "/admin/ban-user": "user.ban",
+  "/admin/unban-user": "user.unban",
+  "/admin/revoke-user-session": "user.session_revoke",
+  "/admin/revoke-user-sessions": "user.session_revoke_all",
+  "/admin/impersonate-user": "user.impersonate",
+  "/admin/stop-impersonating": "user.stop_impersonate",
+};
+
+// The top-level `hooks.after` is a single middleware; it runs only on success,
+// so it records completed actions.
+export const auditAfterHook = createAuthMiddleware(async (ctx) => {
+  const action = ACTIONS[ctx.path];
+  if (!action) return;
+  const context = ctx.context as {
+    session?: { user?: { id?: string; name?: string; email?: string } };
+    newSession?: { user?: { id?: string; name?: string; email?: string } };
+  };
+  const actor = context.session?.user ?? context.newSession?.user;
+  const body = (ctx.body ?? {}) as { email?: string; userId?: string };
+
+  // Prefer a human-readable target: the email in the body, otherwise resolve the
+  // target user's email by id (falls back to the id for already-deleted users).
+  const targetId = body.userId ?? null;
+  let targetLabel = body.email ?? null;
+  if (!targetLabel && targetId) {
+    try {
+      const adapter = (ctx.context as { internalAdapter?: { findUserById?: (id: string) => Promise<{ email?: string } | null> } })
+        .internalAdapter;
+      const target = await adapter?.findUserById?.(targetId);
+      targetLabel = target?.email ?? targetId;
+    } catch {
+      targetLabel = targetId;
+    }
+  }
+
+  await recordAudit({
+    action,
+    actorId: actor?.id ?? null,
+    actorName: actor?.name ?? null,
+    actorEmail: actor?.email ?? null,
+    targetId,
+    targetLabel,
+    ip: ctx.headers?.get("x-forwarded-for") ?? null,
+  });
+});

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-log.entity.ts

@@ -0,0 +1,46 @@
+import { Column, CreateDateColumn, Entity, Index, PrimaryGeneratedColumn } from "typeorm";
+
+// An append-only audit trail. Fields follow the actor / action / target model:
+// who did what, to which resource, when — with human-readable labels stored
+// inline so entries stay meaningful even after users are renamed or deleted.
+@Entity("audit_logs")
+export class AuditLog {
+  @PrimaryGeneratedColumn("uuid")
+  id!: string;
+
+  // A stable, semantic action code, e.g. "user.create", "auth.login".
+  @Index()
+  @Column({ type: "varchar", length: 128 })
+  action!: string;
+
+  // Who performed it (denormalized display fields + id).
+  @Column({ type: "varchar", nullable: true })
+  actorId!: string | null;
+
+  @Column({ type: "varchar", nullable: true })
+  actorName!: string | null;
+
+  @Column({ type: "varchar", nullable: true })
+  actorEmail!: string | null;
+
+  // What it acted on (optional).
+  @Column({ type: "varchar", nullable: true })
+  targetType!: string | null;
+
+  @Column({ type: "varchar", nullable: true })
+  targetId!: string | null;
+
+  @Column({ type: "varchar", nullable: true })
+  targetLabel!: string | null;
+
+  @Column({ type: "varchar", nullable: true })
+  ip!: string | null;
+
+  // Free-form context for custom events.
+  @Column({ type: "jsonb", nullable: true })
+  metadata!: Record<string, unknown> | null;
+
+  @Index()
+  @CreateDateColumn({ type: "timestamptz" })
+  createdAt!: Date;
+}

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.controller.ts

@@ -0,0 +1,21 @@
+import { Controller, ForbiddenException, Get } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Session, type UserSession } from "@thallesp/nestjs-better-auth";
+import { ApiTags } from "@nestjs/swagger";
+import { Repository } from "typeorm";
+import { AuditLog } from "./audit-log.entity";
+
+@ApiTags("audit")
+@Controller("audit-logs")
+export class AuditController {
+  constructor(@InjectRepository(AuditLog) private readonly logs: Repository<AuditLog>) {}
+
+  // Audit entries are sensitive — admins only.
+  @Get()
+  recent(@Session() session: UserSession): Promise<AuditLog[]> {
+    if ((session.user as { role?: string | null }).role !== "admin") {
+      throw new ForbiddenException("Admins only");
+    }
+    return this.logs.find({ order: { createdAt: "DESC" }, take: 50 });
+  }
+}

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.decorator.ts

@@ -0,0 +1,23 @@
+import { SetMetadata } from "@nestjs/common";
+import type { Request } from "express";
+
+export const AUDIT_KEY = "podokit:audit";
+
+// Optionally derive the target (and extra metadata) from the request + handler
+// result, e.g. (req, result) => ({ type: "todo", id: result.id, label: result.title }).
+export type AuditTarget = {
+  type?: string;
+  id?: string;
+  label?: string;
+  metadata?: Record<string, unknown>;
+};
+export type AuditMeta = {
+  action: string;
+  resolve?: (req: Request, result: unknown) => AuditTarget | undefined;
+};
+
+// Mark a controller handler to be audited under a semantic action code:
+//   @Audit("todo.create", (_req, todo) => ({ type: "todo", id: todo.id, label: todo.title }))
+export function Audit(action: string, resolve?: AuditMeta["resolve"]): MethodDecorator {
+  return SetMetadata(AUDIT_KEY, { action, resolve } satisfies AuditMeta);
+}

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.interceptor.ts

@@ -0,0 +1,54 @@
+import { type CallHandler, type ExecutionContext, Injectable, type NestInterceptor } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { fromNodeHeaders } from "better-auth/node";
+import type { Request } from "express";
+import { type Observable, tap } from "rxjs";
+import { auth } from "../auth/auth";
+import { AUDIT_KEY, type AuditMeta } from "./audit.decorator";
+import { AuditService } from "./audit.service";
+
+// Records handlers explicitly marked with @Audit(...). Nothing is logged unless
+// you opt a route in, so the trail stays meaningful (semantic actions, not raw
+// HTTP). Auth/admin actions are recorded separately by the better-auth hook.
+@Injectable()
+export class AuditInterceptor implements NestInterceptor {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly audit: AuditService,
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const meta = this.reflector.get<AuditMeta | undefined>(AUDIT_KEY, context.getHandler());
+    if (!meta) return next.handle();
+    const req = context.switchToHttp().getRequest<Request>();
+    return next.handle().pipe(tap((result) => void this.log(meta, req, result)));
+  }
+
+  private async log(meta: AuditMeta, req: Request, result: unknown): Promise<void> {
+    let actorId: string | null = null;
+    let actorName: string | null = null;
+    let actorEmail: string | null = null;
+    try {
+      const session = await auth.api.getSession({ headers: fromNodeHeaders(req.headers) });
+      if (session?.user) {
+        actorId = session.user.id;
+        actorName = session.user.name ?? null;
+        actorEmail = session.user.email ?? null;
+      }
+    } catch {
+      /* unauthenticated */
+    }
+    const target = meta.resolve?.(req, result);
+    await this.audit.record({
+      action: meta.action,
+      actorId,
+      actorName,
+      actorEmail,
+      targetType: target?.type ?? null,
+      targetId: target?.id ?? null,
+      targetLabel: target?.label ?? null,
+      ip: req.ip ?? null,
+      metadata: target?.metadata ?? null,
+    });
+  }
+}

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.module.ts

@@ -0,0 +1,14 @@
+import { Module } from "@nestjs/common";
+import { APP_INTERCEPTOR } from "@nestjs/core";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { AuditController } from "./audit.controller";
+import { AuditInterceptor } from "./audit.interceptor";
+import { AuditService } from "./audit.service";
+import { AuditLog } from "./audit-log.entity";
+
+@Module({
+  imports: [TypeOrmModule.forFeature([AuditLog])],
+  controllers: [AuditController],
+  providers: [AuditService, { provide: APP_INTERCEPTOR, useClass: AuditInterceptor }],
+})
+export class AuditModule {}

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.service.ts

@@ -0,0 +1,36 @@
+import { Injectable, type OnModuleInit } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { AuditLog } from "./audit-log.entity";
+import { setAuditRecorder, type AuditEntry } from "./audit-events";
+
+// The one place audit entries are written. Inject it to record from Nest code,
+// or call recordAudit() from anywhere else — both end up here.
+@Injectable()
+export class AuditService implements OnModuleInit {
+  constructor(@InjectRepository(AuditLog) private readonly logs: Repository<AuditLog>) {}
+
+  onModuleInit(): void {
+    setAuditRecorder((entry) => this.record(entry));
+  }
+
+  async record(entry: AuditEntry): Promise<void> {
+    try {
+      await this.logs.save(
+        this.logs.create({
+          action: entry.action,
+          actorId: entry.actorId ?? null,
+          actorName: entry.actorName ?? null,
+          actorEmail: entry.actorEmail ?? null,
+          targetType: entry.targetType ?? null,
+          targetId: entry.targetId ?? null,
+          targetLabel: entry.targetLabel ?? null,
+          ip: entry.ip ?? null,
+          metadata: entry.metadata ?? null,
+        }),
+      );
+    } catch {
+      // An audit write must never break the request it describes.
+    }
+  }
+}