@podosoft/podokit 0.4.0 → 0.5.1

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

@@ -1,17 +1,49 @@
 import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+test("admin can create a user with a custom role @smoke", async ({ page }) => {
+  await ready(page, "/admin/users");
+  await page.getByRole("button", { name: "Add user" }).click();
+  const role = page.locator("#c-role");
+  test.skip((await role.count()) === 0, "role picker not present");
+  const email = `mod-${Date.now()}@example.com`;
+  await page.getByLabel("Name", { exact: true }).fill("Mod");
+  await page.getByLabel("Email", { exact: true }).fill(email);
+  await page.getByLabel("Password", { exact: true }).fill("Podokit3e-Str0ng!pw");
+  await page.getByLabel("Confirm password").fill("Podokit3e-Str0ng!pw");
+  // pick the Moderator role from the select
+  await role.click();
+  await page.getByRole("option", { name: "Moderator" }).click();
+  await page.getByRole("button", { name: "Create", exact: true }).click();
+  await expect(page.getByText("User created")).toBeVisible();
+  // it appears in the list, filterable by the Moderator role
+  await page.locator("#toolbar-search").fill(email);
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  await expect(page.getByRole("cell", { name: email })).toBeVisible();
+});
 
 test("admin sees the user list and can search @smoke", async ({ page }) => {
-  await page.goto("/admin/users");
+  await ready(page, "/admin/users");
   await expect(page.getByRole("heading", { name: "Users" })).toBeVisible();
+  // Search by exact address — robust to pagination as the user count grows.
+  await page.locator("#toolbar-search").fill("admin@example.com");
+  await page.getByRole("button", { name: "Search", exact: true }).click();
   await expect(page.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
-  await page.getByPlaceholder("Search by email…").fill("user@");
+  await page.locator("#toolbar-search").fill("user@example.com");
+  await page.getByRole("button", { name: "Search", exact: true }).click();
   await expect(page.getByRole("cell", { name: "user@example.com" })).toBeVisible();
   await expect(page.getByRole("cell", { name: "admin@example.com" })).toHaveCount(0);
 });
 
+test("user list shows the joined column @smoke", async ({ page }) => {
+  await ready(page, "/admin/users");
+  await expect(page.getByRole("columnheader", { name: "Joined" })).toBeVisible();
+});
+
 test("row menu exposes admin actions", async ({ page }) => {
   await page.goto("/admin/users");
-  await page.getByPlaceholder("Search by email…").fill("user@example.com");
+  await page.locator("#toolbar-search").fill("user@example.com");
+  await page.getByRole("button", { name: "Search", exact: true }).click();
   const row = page.getByRole("row", { name: /user@example.com/ });
   await row.getByRole("button").click();
   await expect(page.getByRole("menuitem", { name: "Manage" })).toBeVisible();

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

@@ -5,6 +5,12 @@
     "auth"
   ],
   "targetApp": "web",
+  "dependencies": {
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@types/qrcode": "^1.5.5"
+  },
   "env": [
     "# admin-dashboard: emails auto-promoted to the admin role on sign-up (comma-separated)",
     "ADMIN_EMAILS=admin@example.com"
@@ -12,23 +18,23 @@
   "inject": [
     {
       "file": "apps/api/src/auth/auth.ts",
-      "marker": "// podokit:auth-imports",
+      "marker": "// podokit:end: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\"] }));"
+      "marker": "// podokit:end:auth-imports",
+      "text": "import { ac, roles } from \"./permissions\";"
     },
     {
       "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    },"
+      "marker": "// podokit:end:auth-plugins",
+      "text": "plugins.push(admin({ defaultRole: \"user\", adminRoles: [\"admin\"], ac, roles }));"
     },
     {
       "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  },"
+      "marker": "// podokit:end:auth-options",
+      "text": "trustedOrigins: (process.env.CORS_ORIGIN ?? \"http://localhost:5001\").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": [

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

@@ -8,12 +8,12 @@
     "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," }
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { ApiKeyModule } from \"./api-key/api-key.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end: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"
+    "Call it:  curl -H 'x-api-key: dev-key-please-change' localhost:5002/machine/ping"
   ]
 }

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

@@ -0,0 +1,16 @@
+import { pool } from "../auth/db";
+import { createConfigStore } from "@podosoft/podokit-auth";
+
+// Audit logging is an admin-managed, DB-backed server toggle (auth_config `server`
+// row, env fallback AUDIT_LOG_ENABLED), read through the shared config store's
+// short TTL cache — the same mechanism as the other server-enforced toggles.
+// Toggling it on the Settings page takes effect within the cache TTL, no restart.
+const store = createConfigStore(pool);
+
+export async function auditEnabled(): Promise<boolean> {
+  try {
+    return (await store.capabilitiesSnapshot()).auditLog;
+  } catch {
+    return true; // never let a config read failure silently drop the audit trail
+  }
+}

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

@@ -1,5 +1,6 @@
 import { createAuthMiddleware } from "better-auth/api";
 import { recordAudit } from "./audit-events";
+import { auditEnabled } from "./audit-enabled";
 
 // Map mutating auth/admin endpoints to semantic action codes. better-auth is
 // mounted as middleware and bypasses the NestJS interceptor, so these security
@@ -11,6 +12,8 @@ const ACTIONS: Record<string, string> = {
   "/change-password": "auth.password_change",
   "/change-email": "auth.email_change",
   "/reset-password": "auth.password_reset",
+  "/send-verification-email": "auth.verification_sent",
+  "/verify-email": "auth.email_verified",
   "/update-user": "account.update",
   "/delete-user": "account.delete",
   "/revoke-session": "session.revoke",
@@ -36,6 +39,7 @@ const ACTIONS: Record<string, string> = {
 export const auditAfterHook = createAuthMiddleware(async (ctx) => {
   const action = ACTIONS[ctx.path];
   if (!action) return;
+  if (!(await auditEnabled())) return;
   const context = ctx.context as {
     session?: { user?: { id?: string; name?: string; email?: string } };
     newSession?: { user?: { id?: string; name?: string; email?: string } };

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

@@ -6,6 +6,7 @@ import { type Observable, tap } from "rxjs";
 import { auth } from "../auth/auth";
 import { AUDIT_KEY, type AuditMeta } from "./audit.decorator";
 import { AuditService } from "./audit.service";
+import { auditEnabled } from "./audit-enabled";
 
 // Records handlers explicitly marked with @Audit(...). Nothing is logged unless
 // you opt a route in, so the trail stays meaningful (semantic actions, not raw
@@ -25,6 +26,7 @@ export class AuditInterceptor implements NestInterceptor {
   }
 
   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;

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

@@ -1,39 +1,45 @@
 {
   "name": "audit-log",
-  "description": "Audit logging: records who did each mutating request (who/method/path/status) to an audit_logs table — a NestJS interceptor for your own API routes plus a better-auth hook for auth/admin actions (login, ban, role changes, ...). 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": [
-    "# audit-log: surfaces the admin Audit log page in the dashboard",
+    "# 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",
+      "marker": "// podokit:end:imports",
       "text": "import { AuditModule } from \"./audit/audit.module\";"
     },
     {
       "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:module-imports",
+      "marker": "// podokit:end:module-imports",
       "text": "AuditModule,"
     },
     {
       "file": "apps/api/src/auth/auth.ts",
-      "marker": "// podokit:auth-imports",
+      "marker": "// podokit:end:auth-imports",
       "text": "import { auditAfterHook } from \"../audit/audit-hook\";"
     },
     {
       "file": "apps/api/src/auth/auth.ts",
-      "marker": "// podokit:auth-options",
-      "text": "hooks: { after: auditAfterHook },"
+      "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",
     "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:3000/audit-logs"
-  ]
+    "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,30 +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";
 
-type Capabilities = { twoFactor: boolean; providers: string[]; deleteAccount: boolean; auditLog: boolean };
+// 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")
-  capabilities(): Capabilities {
-    const providers = [
-      process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET ? "google" : null,
-      process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET ? "github" : null,
-    ].filter((p): p is string => p !== null);
+  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: process.env.AUTH_TWO_FACTOR === "true",
-      providers,
-      deleteAccount: process.env.AUTH_ALLOW_DELETE === "true",
-      auditLog: process.env.AUDIT_LOG_ENABLED === "true",
+      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();
+}