@podosoft/podokit 0.3.0 → 0.5.0

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

@@ -0,0 +1,52 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// admin storageState (project default) — organizations is an admin-only view
+test("admin can create an organization @smoke", async ({ page }) => {
+  await ready(page, "/admin");
+  const nav = page.getByRole("link", { name: "Organizations" });
+  test.skip((await nav.count()) === 0, "organizations not enabled");
+  await nav.click();
+  await expect(page).toHaveURL(/\/admin\/organizations/);
+  await page.getByRole("button", { name: "New organization" }).click();
+  const name = `Acme ${Date.now()}`;
+  await page.getByLabel("Name", { exact: true }).fill(name);
+  await page.getByRole("dialog").getByRole("button", { name: "Create", exact: true }).click();
+  await expect(page.getByText("Organization created").first()).toBeVisible();
+  await expect(page.getByRole("cell", { name })).toBeVisible();
+  // clean up so the shared admin account keeps no leftover org
+  await page.getByRole("row", { name: new RegExp(name) }).getByRole("button", { name: "Delete" }).click();
+  await expect(page.getByText("Organization deleted").first()).toBeVisible();
+});
+
+test("create an org with a non-ascii name, a parent, and a manager @smoke", async ({ page }) => {
+  await ready(page, "/admin/organizations");
+  const newBtn = page.getByRole("button", { name: "New organization" });
+  test.skip((await newBtn.count()) === 0, "organizations not enabled");
+
+  // Parent org first (Korean name → slug falls back, so it still saves).
+  const parent = `본사 ${Date.now()}`;
+  await newBtn.click();
+  await page.getByLabel("Name", { exact: true }).fill(parent);
+  await page.getByRole("dialog").getByRole("button", { name: "Create", exact: true }).click();
+  await expect(page.getByText("Organization created").first()).toBeVisible();
+  await expect(page.getByRole("cell", { name: parent })).toBeVisible();
+
+  // Child org: pick the parent + a manager (an existing user).
+  const child = `영업 ${Date.now()}`;
+  await page.getByRole("button", { name: "New organization" }).click();
+  await page.getByLabel("Name", { exact: true }).fill(child);
+  await page.locator("#o-parent").click();
+  await page.getByRole("option", { name: parent }).click();
+  await page.getByRole("checkbox").first().click(); // first existing user as a manager
+  await page.getByRole("dialog").getByRole("button", { name: "Create", exact: true }).click();
+  await expect(page.getByText("Organization created").first()).toBeVisible();
+  // child row shows the parent org name
+  await expect(page.getByRole("row", { name: new RegExp(child) })).toContainText(parent);
+
+  // clean up both
+  for (const n of [child, parent]) {
+    await page.getByRole("row", { name: new RegExp(n) }).getByRole("button", { name: "Delete" }).click();
+    await expect(page.getByText("Organization deleted").first()).toBeVisible();
+  }
+});

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

@@ -0,0 +1,36 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// Full passkey round trip on a throwaway account — never touches the shared admin.
+test.use({ storageState: { cookies: [], origins: [] } });
+
+test("register a passkey and sign in with it @smoke", async ({ page, baseURL }) => {
+  const origin = { origin: baseURL ?? "" };
+  // A virtual authenticator answers both the register (create) and sign-in (get)
+  // WebAuthn ceremonies without hardware.
+  const client = await page.context().newCDPSession(page);
+  await client.send("WebAuthn.enable");
+  await client.send("WebAuthn.addVirtualAuthenticator", {
+    options: { protocol: "ctap2", transport: "internal", hasResidentKey: true, hasUserVerification: true, isUserVerified: true, automaticPresenceSimulation: true },
+  });
+
+  // Sign up a throwaway user (shares the page's cookie jar) and register a passkey.
+  const email = `pk-${Date.now()}@example.com`;
+  const pw = "Podokit3e-Str0ng!pw";
+  const signup = await page.context().request.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "PK" }, headers: origin });
+  expect(signup.ok()).toBeTruthy();
+
+  await ready(page, "/admin/account");
+  await page.getByRole("button", { name: "Security" }).click();
+  const addBtn = page.getByRole("button", { name: "Add passkey" });
+  test.skip((await addBtn.count()) === 0, "passkeys not enabled");
+  await page.getByLabel("Name", { exact: true }).fill("My device");
+  await addBtn.click();
+  await expect(page.getByText("Passkey added")).toBeVisible();
+
+  // Sign out, then sign back in using only the passkey.
+  await page.context().request.post("/api/auth/sign-out", { headers: origin });
+  await ready(page, "/login");
+  await page.getByRole("button", { name: "Use a passkey" }).click();
+  await expect(page).toHaveURL(/\/admin(\/|$)/);
+});

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

@@ -0,0 +1,22 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// admin storageState (project default) — sessions is an admin-only view
+test("sessions table shows the expires column @smoke", async ({ page }) => {
+  await ready(page, "/admin/sessions");
+  await expect(page.getByRole("columnheader", { name: "Expires" })).toBeVisible();
+});
+
+test("admin sees user sessions across users @smoke", async ({ page }) => {
+  await ready(page, "/admin/sessions");
+  await expect(page.getByRole("heading", { name: "User sessions" })).toBeVisible();
+  // Search by exact address — robust to pagination as sessions accumulate (the
+  // admin account alone can fill the first page). This is the across-users view.
+  await page.locator("#toolbar-search").fill("user@example.com");
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  await expect(page.getByRole("main").getByText("user@example.com").first()).toBeVisible();
+  // row actions are available
+  await page.getByRole("row", { name: /user@example.com/ }).first().getByRole("button").click();
+  await expect(page.getByRole("menuitem", { name: "Revoke session" })).toBeVisible();
+  await expect(page.getByRole("menuitem", { name: "Revoke all for user" })).toBeVisible();
+});

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

@@ -0,0 +1,34 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// admin storageState (project default)
+test("settings lists the auth features and their status @smoke", async ({ page }) => {
+  await ready(page, "/admin/settings");
+  await expect(page.getByRole("heading", { name: "Settings" })).toBeVisible();
+  await expect(page.getByText("Email & password")).toBeVisible();
+  await expect(page.getByText("Two-factor authentication")).toBeVisible();
+  await expect(page.getByText("Breached-password check")).toBeVisible();
+  await expect(page.getByText("Magic link")).toBeVisible();
+  // each feature carries an explicit status
+  await expect(page.getByText("Enabled", { exact: true }).first()).toBeVisible();
+});
+
+test("settings is reachable from the sidebar @smoke", async ({ page }) => {
+  await ready(page, "/admin");
+  await page.getByRole("link", { name: "Settings" }).click();
+  await expect(page).toHaveURL(/\/admin\/settings/);
+});
+
+test("admin can toggle a feature flag and it applies live @smoke", async ({ page }) => {
+  await ready(page, "/admin/settings");
+  const toggle = page.getByRole("switch", { name: "Magic link" });
+  test.skip((await toggle.count()) === 0, "magic link toggle not present");
+  // Serial workers (workers:1) make toggle-then-restore safe for other specs.
+  await expect(toggle).toBeChecked();
+  await toggle.click();
+  await expect(page.getByText("Setting updated")).toBeVisible();
+  await expect(toggle).not.toBeChecked(); // capabilities refreshed live
+  // restore so the shared magic-link/2FA specs keep their expected state
+  await toggle.click();
+  await expect(toggle).toBeChecked();
+});

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

@@ -0,0 +1,16 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// admin storageState (project default)
+test("collapsing the sidebar hides the brand instead of overflowing @smoke", async ({ page }) => {
+  await ready(page, "/admin");
+  const brand = page.getByTestId("sidebar-brand");
+  const toggle = page.getByRole("button", { name: "Toggle Sidebar" });
+  await expect(brand).toBeVisible();
+
+  await toggle.click();
+  await expect(brand).toBeHidden(); // icon-collapsed: label is hidden, not spilling out
+
+  await toggle.click();
+  await expect(brand).toBeVisible();
+});

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

@@ -0,0 +1,32 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// The shared toolbar: filters + search both commit on the Search button; the
+// search field itself is selectable (Email, Name, ...).
+test("users toolbar searches only when Search is pressed @smoke", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const main = page.getByRole("main");
+  await page.locator("#toolbar-search").fill("admin@example.com");
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  await expect(main.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
+  await expect(main.getByRole("cell", { name: "user@example.com" })).toHaveCount(0);
+});
+
+test("users toolbar applies filter + search together on Search", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const main = page.getByRole("main");
+  await page.locator('button[data-slot="select-trigger"]').first().click(); // Role select
+  await page.getByRole("option", { name: "Admin", exact: true }).click();
+  // Selecting a filter stages it; nothing applies until Search is pressed.
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  await expect(main.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
+  await expect(main.getByRole("cell", { name: "user@example.com" })).toHaveCount(0);
+});
+
+test("users toolbar can pick the search field", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const fieldSelect = page.locator('button[data-slot="select-trigger"]').last(); // after the filters
+  await fieldSelect.click();
+  await page.getByRole("option", { name: "Name", exact: true }).click();
+  await expect(fieldSelect).toContainText("Name");
+});

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

@@ -0,0 +1,145 @@
+import { expect, test, type Page } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+
+// 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: "Podokit3e-Str0ng!pw", 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.locator("#toolbar-search").fill(email);
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  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("Podokit3e-Str0ng!pw");
+  await dialog.getByLabel("Confirm password").fill("Podokit3e-Str0ng!pw");
+  await dialog.getByRole("button", { name: "Create" }).click();
+  // Wait for the create to settle (dialog closes + list reloads) before searching,
+  // otherwise the search input can be refilled by the post-create reload.
+  await expect(page.getByRole("dialog")).toBeHidden();
+  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("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("Podokit3e-Str0ng!pw");
+  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("Podokit3e-N3wStr0ng!pw");
+  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("Podokit3e-N3wStr0ng!pw");
+  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: "Podokit3e-Str0ng!pw" } })).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.locator("#toolbar-search").fill(email);
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  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: "Podokit3e-Str0ng!pw", 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();
+});
+
+test("manage modal closes from its footer", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const email = `ui-close-${Date.now()}@example.com`;
+  await seedUser(page, email);
+  await openManage(page, email);
+  // footer Close (a visible button, distinct from the header X) dismisses the modal
+  await page.getByRole("dialog").getByRole("button", { name: "Close", exact: true }).last().click();
+  await expect(page.getByRole("dialog")).toBeHidden();
+});

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

@@ -0,0 +1,51 @@
+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 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.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.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();
+  await expect(page.getByRole("menuitem", { name: "Impersonate" })).toBeVisible();
+});

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

@@ -0,0 +1,47 @@
+{
+  "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",
+  "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"
+  ],
+  "inject": [
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "marker": "// podokit:end:auth-imports",
+      "text": "import { admin } from \"better-auth/plugins\";"
+    },
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "marker": "// podokit:end:auth-imports",
+      "text": "import { ac, roles } from \"./permissions\";"
+    },
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "marker": "// podokit:end:auth-plugins",
+      "text": "plugins.push(admin({ defaultRole: \"user\", adminRoles: [\"admin\"], ac, roles }));"
+    },
+    {
+      "file": "apps/api/src/auth/auth.ts",
+      "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": [
+    "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/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/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-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-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,74 @@
+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
+// 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",
+  "/send-verification-email": "auth.verification_sent",
+  "/verify-email": "auth.email_verified",
+  "/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;
+  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 } };
+  };
+  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,
+  });
+});