@podosoft/podokit 0.3.0 → 0.5.0

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

@@ -1,25 +1,46 @@
-import { Column, CreateDateColumn, Entity, PrimaryGeneratedColumn } from "typeorm";
+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 })
-  userId!: string | null;
+  actorId!: string | null;
 
-  @Column({ type: "varchar", length: 10 })
-  method!: string;
+  @Column({ type: "varchar", nullable: true })
+  actorName!: string | null;
 
-  @Column({ type: "varchar", length: 2048 })
-  path!: string;
+  @Column({ type: "varchar", nullable: true })
+  actorEmail!: string | null;
 
-  @Column({ type: "int" })
-  statusCode!: number;
+  // 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

@@ -1,5 +1,6 @@
-import { Controller, Get } from "@nestjs/common";
+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";
@@ -9,8 +10,12 @@ import { AuditLog } from "./audit-log.entity";
 export class AuditController {
   constructor(@InjectRepository(AuditLog) private readonly logs: Repository<AuditLog>) {}
 
+  // Audit entries are sensitive — admins only.
   @Get()
-  recent(): Promise<AuditLog[]> {
+  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

@@ -1,39 +1,56 @@
 import { type CallHandler, type ExecutionContext, Injectable, type NestInterceptor } from "@nestjs/common";
-import { InjectRepository } from "@nestjs/typeorm";
+import { Reflector } from "@nestjs/core";
 import { fromNodeHeaders } from "better-auth/node";
-import type { Request, Response } from "express";
+import type { Request } from "express";
 import { type Observable, tap } from "rxjs";
-import { Repository } from "typeorm";
 import { auth } from "../auth/auth";
-import { AuditLog } from "./audit-log.entity";
+import { AUDIT_KEY, type AuditMeta } from "./audit.decorator";
+import { AuditService } from "./audit.service";
+import { auditEnabled } from "./audit-enabled";
 
-const AUDITED_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
-
-// Records who performed each mutating request. Skips the auth endpoints.
+// 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(@InjectRepository(AuditLog) private readonly logs: Repository<AuditLog>) {}
+  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>();
-    const path = req.originalUrl ?? req.url;
-    if (!AUDITED_METHODS.has(req.method) || path.startsWith("/api/auth")) {
-      return next.handle();
-    }
-    const res = context.switchToHttp().getResponse<Response>();
-    return next.handle().pipe(tap(() => void this.record(req, res, path)));
+    return next.handle().pipe(tap((result) => void this.log(meta, req, result)));
   }
 
-  private async record(req: Request, res: Response, path: string): Promise<void> {
-    let userId: string | null = null;
+  private async log(meta: AuditMeta, req: Request, result: unknown): Promise<void> {
+    if (!(await auditEnabled())) return;
+    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) });
-      userId = session?.user?.id ?? null;
+      if (session?.user) {
+        actorId = session.user.id;
+        actorName = session.user.name ?? null;
+        actorEmail = session.user.email ?? null;
+      }
     } catch {
-      userId = null;
+      /* unauthenticated */
     }
-    await this.logs.save(
-      this.logs.create({ userId, method: req.method, path, statusCode: res.statusCode, ip: req.ip ?? null }),
-    );
+    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

@@ -3,11 +3,12 @@ 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: [{ provide: APP_INTERCEPTOR, useClass: AuditInterceptor }],
+  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.
+    }
+  }
+}

package/dist/templates/modules/audit-log/files/apps/api/src/migrations/1720300000000-InitAuditLogs.ts

@@ -8,15 +8,21 @@ export class InitAuditLogs1720300000000 implements MigrationInterface {
     await queryRunner.query(`
       CREATE TABLE "audit_logs" (
         "id" uuid NOT NULL DEFAULT gen_random_uuid(),
-        "userId" character varying,
-        "method" character varying(10) NOT NULL,
-        "path" character varying(2048) NOT NULL,
-        "statusCode" integer NOT NULL,
+        "action" character varying(128) NOT NULL,
+        "actorId" character varying,
+        "actorName" character varying,
+        "actorEmail" character varying,
+        "targetType" character varying,
+        "targetId" character varying,
+        "targetLabel" character varying,
         "ip" character varying,
+        "metadata" jsonb,
         "createdAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
         CONSTRAINT "PK_audit_logs_id" PRIMARY KEY ("id")
       )
     `);
+    await queryRunner.query(`CREATE INDEX "IDX_audit_logs_action" ON "audit_logs" ("action")`);
+    await queryRunner.query(`CREATE INDEX "IDX_audit_logs_createdAt" ON "audit_logs" ("createdAt")`);
   }
 
   async down(queryRunner: QueryRunner): Promise<void> {

package/dist/templates/modules/audit-log/module.manifest.json

@@ -1,16 +1,45 @@
 {
   "name": "audit-log",
-  "description": "Audit logging: a global interceptor records who did each mutating request (who/method/path/status) to an audit_logs table. Requires auth.",
-  "requires": ["auth"],
+  "description": "Audit logging: records who did each mutating request (who/method/path/status) to an audit_logs table \u2014 a NestJS interceptor for your own API routes plus a better-auth hook for auth/admin actions (login, ban, role changes, ...). Requires auth.",
+  "requires": [
+    "auth"
+  ],
   "targetApp": "api",
-  "env": [],
+  "env": [
+    "# audit-log: on/off is managed on the admin Settings page (stored in the DB,",
+    "# applied live, no restart). This env var is the fallback default used until an",
+    "# admin sets it \u2014 leave it 'true' so the trail is on out of the box; the DB value",
+    "# (Settings page) overrides it once set.",
+    "AUDIT_LOG_ENABLED=true"
+  ],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { AuditModule } from \"./audit/audit.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "AuditModule," }
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:imports",
+      "text": "import { AuditModule } from \"./audit/audit.module\";"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:module-imports",
+      "text": "AuditModule,"
+    },
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "marker": "// podokit:end:auth-imports",
+      "text": "import { auditAfterHook } from \"../audit/audit-hook\";"
+    },
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "marker": "// podokit:end:auth-hooks",
+      "text": "hooks.after = auditAfterHook;"
+    }
   ],
   "instructions": [
     "Run migrations to create the audit_logs table:  npm run migration:run -w <app>-api",
-    "Mutating requests (POST/PUT/PATCH/DELETE) are recorded with the acting user.",
-    "List recent entries (requires a session):  curl -b cookies.txt localhost:3000/audit-logs"
-  ]
+    "Auth/admin actions (login, ban, role changes, session revocation, user CRUD) are recorded via a better-auth hook; your own mutating NestJS routes are recorded by the interceptor.",
+    "List recent entries (admin session required):  curl -b cookies.txt localhost:5002/audit-logs"
+  ],
+  "dependencies": {
+    "@podosoft/podokit-auth": "^0.1.0"
+  }
 }

package/dist/templates/modules/auth/files/apps/api/src/account/account.controller.ts

@@ -1,13 +1,95 @@
-import { Controller, Get } from "@nestjs/common";
-import { Session, type UserSession } from "@thallesp/nestjs-better-auth";
+import { Body, Controller, ForbiddenException, Get, Post, Put, Req } from "@nestjs/common";
+import type { Request } from "express";
+import { fromNodeHeaders } from "better-auth/node";
+import { Public, Session, type UserSession } from "@thallesp/nestjs-better-auth";
 import { ApiTags } from "@nestjs/swagger";
+import { FEATURE_FLAGS, SettingsService, type FeatureFlag } from "../settings/settings.service";
+import { ROLE_NAMES } from "../auth/permissions";
+import { auth } from "../auth/auth";
+import { pool } from "../auth/db";
+import { createConfigStore } from "@podosoft/podokit-auth";
+import type { Capabilities } from "@podosoft/podokit-contracts";
+
+// Reads OAuth/server-toggle state (DB-first, env fallback) for capabilities.
+const configStore = createConfigStore(pool);
+
+function isAdmin(session: UserSession): boolean {
+  const role = session.user?.role;
+  const roles = Array.isArray(role) ? role : (role ?? "").split(",").map((r: string) => r.trim());
+  return roles.includes("admin");
+}
 
-// Protected by the global AuthGuard. Use @Session() to read the current user.
 @ApiTags("account")
 @Controller("account")
 export class AccountController {
+  constructor(private readonly settings: SettingsService) {}
+
   @Get("me")
   me(@Session() session: UserSession) {
     return session.user;
   }
+
+  // Which optional auth features are enabled, so the UI can show/hide sections.
+  // Public so the login page (unauthenticated) can offer available sign-in methods.
+  @Public()
+  @Get("capabilities")
+  async capabilities(): Promise<Capabilities> {
+    const flags = this.settings.flags();
+    // OAuth providers + server-enforced toggles are DB-backed (env fallback) and
+    // applied live, so read them from the config store rather than process.env.
+    const snapshot = await configStore.capabilitiesSnapshot();
+    return {
+      twoFactor: flags.twoFactor,
+      magicLink: flags.magicLink,
+      emailOtp: flags.emailOtp,
+      username: flags.username,
+      multiSession: flags.multiSession,
+      phoneNumber: flags.phoneNumber,
+      apiKey: flags.apiKey,
+      passkey: flags.passkey,
+      organization: flags.organization,
+      oidcProvider: flags.oidcProvider,
+      providers: snapshot.providers,
+      deleteAccount: snapshot.allowDelete,
+      emailVerification: snapshot.requireEmailVerification,
+      passwordBreachCheck: snapshot.passwordBreachCheck,
+      auditLog: snapshot.auditLog,
+      roles: ROLE_NAMES,
+    };
+  }
+
+  // Admin-only: toggle feature flags. Stored in the DB and reflected immediately in
+  // capabilities (UI). Server-enforced behaviours (email verification, breach check)
+  // are read by the auth server at startup, so those take effect on the next restart.
+  @Put("settings")
+  async updateSettings(
+    @Session() session: UserSession,
+    @Body() body: Partial<Record<FeatureFlag, boolean>>,
+  ): Promise<Record<FeatureFlag, boolean>> {
+    if (!isAdmin(session)) throw new ForbiddenException("Admins only");
+    const update: Partial<Record<FeatureFlag, boolean>> = {};
+    for (const flag of FEATURE_FLAGS) {
+      if (typeof body?.[flag] === "boolean") update[flag] = body[flag];
+    }
+    return this.settings.setMany(update);
+  }
+
+  // Add an existing user to an organization with a role (e.g. "manager"), so several
+  // members can hold it. better-auth's addMember is server-only; this exposes it and
+  // delegates org-level authorization to better-auth via the caller's session headers.
+  @Post("org-member")
+  async addOrgMember(
+    @Req() req: Request,
+    @Body() body: { organizationId: string; userId: string; role: string },
+  ): Promise<unknown> {
+    // addMember is a server-only better-auth endpoint (not on the typed public api);
+    // it exists at runtime, so reach it through a narrow cast.
+    const api = auth.api as unknown as {
+      addMember: (opts: { body: { organizationId: string; userId: string; role: string }; headers: Headers }) => Promise<unknown>;
+    };
+    return api.addMember({
+      body: { organizationId: body.organizationId, userId: body.userId, role: body.role },
+      headers: fromNodeHeaders(req.headers),
+    });
+  }
 }

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

@@ -1,5 +1,6 @@
 import { Module } from "@nestjs/common";
+import { SettingsModule } from "../settings/settings.module";
 import { AccountController } from "./account.controller";
 
-@Module({ controllers: [AccountController] })
+@Module({ imports: [SettingsModule], controllers: [AccountController] })
 export class AccountModule {}

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

@@ -0,0 +1,73 @@
+import { auth as bootstrapAuth, buildAuth } from "./auth";
+import { pool } from "./db";
+import { createConfigStore } from "@podosoft/podokit-auth";
+
+// Runtime auth instance that rebuilds when the DB config changes, so admin edits
+// (OAuth credentials, SMTP, server-enforced toggles) apply WITHOUT a restart.
+//
+// @thallesp/nestjs-better-auth reads `auth.handler` exactly once (via toNodeHandler)
+// and `auth.api` per request. We hand it a Proxy: `.handler` is a STABLE delegating
+// function (so the adapter's captured reference stays valid) that redispatches each
+// request to the currently-built instance; every other access forwards to the
+// current instance too. The guard/session behavior is unchanged (session tokens are
+// signed with the stable BETTER_AUTH_SECRET; trustedOrigins is baked into every build).
+
+const store = createConfigStore(pool);
+const TTL_MS = 3_000;
+
+let current = bootstrapAuth;
+let currentVersion = "env"; // matches envAuthConfig() bootstrap
+let checkedAt = 0;
+let inflight: Promise<void> | null = null;
+
+export function getAuth(): typeof bootstrapAuth {
+  return current;
+}
+
+/** Rebuild the instance if the DB config version changed. Cheap and throttled to
+ *  TTL; single-flight so concurrent requests trigger at most one rebuild; keeps the
+ *  last-good instance if loading/building fails, so auth never goes down. */
+export async function refreshIfStale(): Promise<void> {
+  if (checkedAt !== 0 && Date.now() - checkedAt < TTL_MS) return;
+  checkedAt = Date.now();
+  let latest: string;
+  try {
+    latest = await store.currentVersion();
+  } catch {
+    return; // DB blip — keep serving the last-good instance
+  }
+  if (latest === currentVersion) return;
+  if (inflight) return inflight;
+  inflight = (async () => {
+    try {
+      const config = await store.load();
+      current = buildAuth(config);
+      currentVersion = config.version;
+    } catch (err) {
+      console.error("[auth-config] rebuild failed; keeping last-good auth instance:", err instanceof Error ? err.message : err);
+    } finally {
+      inflight = null;
+    }
+  })();
+  return inflight;
+}
+
+// Stable handler reference the adapter captures once; redispatches per request.
+const dynamicHandler: typeof bootstrapAuth.handler = async (request) => {
+  await refreshIfStale();
+  return current.handler(request);
+};
+
+export const authRuntime: typeof bootstrapAuth = new Proxy(bootstrapAuth, {
+  get(_target, prop) {
+    if (prop === "handler") return dynamicHandler;
+    const value = Reflect.get(current, prop, current);
+    return typeof value === "function" ? value.bind(current) : value;
+  },
+});
+
+/** Optional boot preload so the first request doesn't pay the initial DB read. */
+export async function primeAuth(): Promise<void> {
+  checkedAt = 0;
+  await refreshIfStale();
+}