@podosoft/podokit 1.6.2 → 1.6.4

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/references/profile.md

@@ -41,7 +41,7 @@ Review these fields before planning:
 - `runtimeConfig`: non-sensitive environment values only
 - `verification`: HTTPS origin and checks with exact statuses and optional JSON fields
 
-The cluster namespace and referenced Secrets must already exist. PodoKit asks `kubectl` to output only Secret key names and never prints or stores their values; the Kubernetes client still materializes the Secret while evaluating that output.
+The cluster namespace and referenced Secrets must already exist. PodoKit asks `kubectl` to output only Secret key names and never prints or stores their values; the Kubernetes client still materializes the Secret while evaluating that output. The one exception is `ADMIN_EMAILS` of the API Secret, an allowlist of addresses rather than a credential: with the `auth` module installed, the doctor reads it and fails on a placeholder such as `admin@example.com`.
 
 Required keys:
 
@@ -94,7 +94,8 @@ The fields that differ from the Kubernetes driver:
 
 Credentials live in env files **on the target host**, never in the profile and never
 in the rendered Compose project. The doctor reads only the key names, in a throwaway
-container that mounts the file read-only. Create those files with the host's own
+container that mounts the file read-only, plus the `ADMIN_EMAILS` line of the API env
+file when the `auth` module is installed, to fail on a placeholder such as `admin@example.com`. Create those files with the host's own
 secret tooling before deploying; PodoKit does not write them.
 
 Required keys:

package/dist/templates/fullstack/tests/README.md

@@ -68,3 +68,14 @@ tests not run, and selecting an exclusive test runs every other test first. Use
 
 Application-owned projects in `playwright.projects.cjs` get twins too. A project
 that another project depends on is a setup project and keeps a single copy.
+
+## Email tests
+
+The email specs that the `admin-dashboard` module adds read messages from the
+Mailpit at `MAILPIT_URL` (default `http://localhost:8025`). Before the first one,
+each worker has the app send a password reset email to a throwaway account and
+waits up to five seconds for it there. When it does not arrive, because the app
+has no SMTP or sends to a catcher other than the one on that port, the email
+tests skip with that cause. Set `MAILPIT_URL` to the Mailpit that receives the
+app's mail to run them, and `E2E_REQUIRE_MAIL=true` to make a missing probe
+message fail them instead of skipping.

package/dist/templates/modules/admin-dashboard/files/tests/api/audit.api.spec.ts

@@ -1,7 +1,7 @@
 import type { APIRequestContext } from "@playwright/test";
 import { expect, test } from "../helpers/disposable-users";
 import { ADMIN, USER } from "../helpers/accounts";
-import { mailpitReachable, waitForOtp } from "../helpers/mailpit";
+import { skipUnlessMailReachesMailpit, waitForOtp } from "../helpers/mailpit";
 import { totpCode } from "../helpers/totp";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
@@ -12,6 +12,7 @@ type Entry = {
   id: string;
   action: string;
   actorEmail: string | null;
+  targetId: string | null;
   targetLabel: string | null;
   metadata: Record<string, unknown> | null;
   createdAt: string;
@@ -61,6 +62,31 @@ test("audit log records auth/admin actions", async ({ playwright, disposableUser
   await admin.dispose();
 });
 
+test("a sign-up and a sign-out are audited with the user", async ({ playwright, disposableUsers }) => {
+  const admin = await signedIn(playwright, ADMIN);
+  test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
+  const email = `audit-signup-${Date.now()}@example.com`;
+  const visitor = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const signup = await visitor.post("/api/auth/sign-up/email", { data: { email, password: PASSWORD, name: "Signup" } });
+  test.skip(signup.status() === 403, "public sign-up is closed");
+  const userId = await disposableUsers.trackResponse(signup);
+  const entries = async (action: string): Promise<Entry[]> =>
+    (await (await admin.get(auditQuery({ action, target: email }))).json()) as Entry[];
+
+  expect(await entries("auth.signup")).toEqual([
+    expect.objectContaining({ actorEmail: email, targetId: userId, metadata: { method: "password" } }),
+  ]);
+  if (!(await visitor.get("/api/auth/get-session").then((response) => response.json()))?.session) {
+    expect((await visitor.post("/api/auth/sign-in/email", { data: { email, password: PASSWORD } })).ok()).toBeTruthy();
+  }
+  expect((await visitor.post("/api/auth/sign-out", { data: {} })).ok()).toBeTruthy();
+  expect(await entries("auth.logout"), "the sign-out names the user whose session ended").toEqual([
+    expect.objectContaining({ actorEmail: email, targetId: userId }),
+  ]);
+  await visitor.dispose();
+  await admin.dispose();
+});
+
 test("the audit log is admin-only", async ({ playwright }) => {
   const admin = await signedIn(playwright, ADMIN);
   test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
@@ -171,7 +197,7 @@ test("a wrong password is not audited as a sign-in", async ({ playwright, dispos
 });
 
 test("an email code sign-in is audited once", async ({ playwright, disposableUsers }) => {
-  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  await skipUnlessMailReachesMailpit();
   const admin = await signedIn(playwright, ADMIN);
   test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
   const caps = await (await admin.get("/api/account/capabilities")).json();

package/dist/templates/modules/admin-dashboard/files/tests/api/auth.api.spec.ts

@@ -470,6 +470,30 @@ test("ADMIN_EMAILS account has the admin role @smoke", async ({ playwright }) =>
   await ctx.dispose();
 });
 
+// An ADMIN_EMAILS address with no account yet, such as a placeholder that was
+// never replaced: a sign-up with it must not create an account, let alone an
+// approved administrator.
+test("a sign-up cannot claim an ADMIN_EMAILS address", async ({ playwright }) => {
+  const email = process.env.E2E_UNCLAIMED_ADMIN_EMAIL;
+  test.skip(!email, "set E2E_UNCLAIMED_ADMIN_EMAIL to an ADMIN_EMAILS address that has no account");
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const password = "Podokit3e-Str0ng!pw";
+  const signUp = await ctx.post("/api/auth/sign-up/email", { data: { email, password, name: "Claim" } });
+  // Refused, or answered like any sign-up while approval or email verification
+  // hides whether an address can register.
+  expect([200, 403], await signUp.text()).toContain(signUp.status());
+  expect((await ctx.post("/api/auth/sign-in/email", { data: { email, password } })).ok()).toBe(false);
+  expect((await (await ctx.get("/api/auth/get-session")).json())?.user ?? null).toBeNull();
+  await ctx.dispose();
+
+  const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await admin.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
+  const found = await admin.get(`/api/auth/admin/list-users?searchField=email&searchOperator=contains&searchValue=${encodeURIComponent(email ?? "")}`);
+  expect(found.ok()).toBeTruthy();
+  expect(((await found.json()) as { users: unknown[] }).users).toEqual([]);
+  await admin.dispose();
+});
+
 test("admin can list users, a normal user cannot (403)", async ({ playwright }) => {
   const adminCtx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   await adminCtx.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });

package/dist/templates/modules/admin-dashboard/files/tests/api/email.api.spec.ts

@@ -1,11 +1,11 @@
 import { expect, test } from "@playwright/test";
-import { mailpitReachable, waitForLink, waitForOtp } from "../helpers/mailpit";
+import { skipUnlessMailReachesMailpit, waitForLink, waitForOtp } from "../helpers/mailpit";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
 
 test("email one-time code signs a user in", async ({ playwright }) => {
-  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  await skipUnlessMailReachesMailpit();
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const caps = await (await ctx.get("/api/account/capabilities")).json();
   test.skip(!caps?.emailOtp, "email OTP not enabled");
@@ -49,7 +49,7 @@ test("organization invitation can be sent and accepted", async ({ playwright })
 });
 
 test("magic link signs a user in", async ({ playwright }) => {
-  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  await skipUnlessMailReachesMailpit();
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const caps = await (await ctx.get("/api/account/capabilities")).json();
   test.skip(!caps?.magicLink, "magic link not enabled");
@@ -74,7 +74,7 @@ function tokenFromRedirect(location: string): string | null {
 }
 
 test("password reset delivers an email and updates the password @smoke", async ({ playwright }) => {
-  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  await skipUnlessMailReachesMailpit();
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const email = `reset-${Date.now()}@example.com`;
   const signup = await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "Reset" } });
@@ -99,7 +99,7 @@ test("password reset delivers an email and updates the password @smoke", async (
 });
 
 test("email verification blocks sign-in until the address is confirmed", async ({ playwright }) => {
-  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  await skipUnlessMailReachesMailpit();
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const email = `verify-${Date.now()}@example.com`;
   const signup = await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "Verify", callbackURL: `${base}/admin` } });

package/dist/templates/modules/admin-dashboard/files/tests/helpers/mailpit.ts

@@ -1,33 +1,82 @@
-// Helpers for the local Mailpit catcher (docker-compose / CI service). Tests that
-// exercise email flows skip when it isn't reachable (see MAILPIT_URL). Each test
+import { request, test } from "@playwright/test";
+
+// Helpers for the local Mailpit catcher (docker-compose / CI service). Each test
 // mails an address of its own and reads the newest message to it; the inbox is
 // shared with tests on other workers, so no test empties it.
 const MAILPIT = process.env.MAILPIT_URL ?? "http://localhost:8025";
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const PROBE_WAIT_MS = 5000;
+
+type MailpitList = { messages: Array<{ ID: string; To: Array<{ Address: string }> }> };
+type MailpitMessage = { Text?: string; HTML?: string };
 
-export async function mailpitReachable(): Promise<boolean> {
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+async function newestMessageTo(to: string): Promise<string | undefined> {
+  const list = (await (await fetch(`${MAILPIT}/api/v1/messages`)).json()) as MailpitList;
+  return list.messages?.find((m) => m.To?.some((t) => t.Address === to))?.ID;
+}
+
+// A Mailpit answering on MAILPIT_URL may belong to another stack while this app
+// sends no mail or sends it elsewhere, so ask the app to mail an address of the
+// probe's own and wait for that message. Returns why email tests cannot run, or
+// null when the message arrives.
+async function mailDeliveryProblem(): Promise<string | null> {
   try {
-    return (await fetch(`${MAILPIT}/readyz`)).ok;
+    if (!(await fetch(`${MAILPIT}/readyz`)).ok) return `Mailpit at ${MAILPIT} is not ready`;
   } catch {
-    return false;
+    return `no Mailpit answers at ${MAILPIT}`;
   }
+  const email = `mail-probe-${Date.now()}-${process.pid}@example.com`;
+  const app = await request.newContext({ baseURL: base, extraHTTPHeaders: { origin: base } });
+  try {
+    const signUp = await app.post("/api/auth/sign-up/email", {
+      data: { email, password: "Podokit3e-Str0ng!pw", name: "Mail probe" },
+    });
+    if (!signUp.ok()) return `the mail probe could not sign up (HTTP ${signUp.status()})`;
+    const reset = await app.post("/api/auth/request-password-reset", {
+      data: { email, redirectTo: `${base}/reset-password` },
+    });
+    if (!reset.ok()) return `the app could not send the probe email (HTTP ${reset.status()})`;
+  } finally {
+    await app.dispose();
+  }
+  const deadline = Date.now() + PROBE_WAIT_MS;
+  while (Date.now() < deadline) {
+    if (await newestMessageTo(email)) return null;
+    await sleep(250);
+  }
+  return `Mailpit at ${MAILPIT} does not receive this app's mail: a probe email to ${email} did not arrive within ${PROBE_WAIT_MS / 1000} s`;
 }
 
-type MailpitList = { messages: Array<{ ID: string; To: Array<{ Address: string }> }> };
-type MailpitMessage = { Text?: string; HTML?: string };
+let delivery: Promise<string | null> | undefined;
+
+/**
+ * Skip the current test unless the app under test delivers its mail to the
+ * Mailpit these helpers read. The probe runs once per worker. With
+ * E2E_REQUIRE_MAIL=true, which a harness that wires the app's SMTP to that
+ * Mailpit sets, a failed probe fails the test instead.
+ */
+export async function skipUnlessMailReachesMailpit(): Promise<void> {
+  delivery ??= mailDeliveryProblem().catch((error: unknown) => `the mail probe failed: ${String(error)}`);
+  const problem = await delivery;
+  if (problem === null) return;
+  if (process.env.E2E_REQUIRE_MAIL === "true") throw new Error(`E2E_REQUIRE_MAIL is set, but ${problem}`);
+  test.skip(true, problem);
+}
 
 // Poll for the newest message addressed to `to` and return the first match of
 // `pattern` in its text/HTML body.
 async function waitForMatch(to: string, pattern: RegExp, label: string, timeoutMs: number): Promise<string> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    const list = (await (await fetch(`${MAILPIT}/api/v1/messages`)).json()) as MailpitList;
-    const msg = list.messages?.find((m) => m.To?.some((t) => t.Address === to));
-    if (msg) {
-      const full = (await (await fetch(`${MAILPIT}/api/v1/message/${msg.ID}`)).json()) as MailpitMessage;
+    const id = await newestMessageTo(to);
+    if (id) {
+      const full = (await (await fetch(`${MAILPIT}/api/v1/message/${id}`)).json()) as MailpitMessage;
       const match = `${full.Text ?? ""} ${full.HTML ?? ""}`.match(pattern);
       if (match) return match[0];
     }
-    await new Promise((r) => setTimeout(r, 300));
+    await sleep(300);
   }
   throw new Error(`no email with ${label} to ${to} within ${timeoutMs}ms`);
 }

package/dist/templates/modules/admin-dashboard/files/tests/seed.setup.ts

@@ -41,17 +41,29 @@ function withTestLocale(state: StorageState): StorageState {
 // cookies as storageState for the browser `ui` project to reuse. Pin the suite
 // locale because UI locators use the generated English catalog and must not
 // inherit an application's configured default language.
+//
+// The user signs up here. The administrator cannot: the API refuses a sign-up
+// with an ADMIN_EMAILS address that has not proven it, so the account comes
+// from admin:bootstrap before the suite runs.
 async function seedSession(
   playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
   account: Account,
   path: string,
+  { signUp }: { signUp: boolean },
 ): Promise<void> {
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: { origin: base } });
-  await ctx.post("/api/auth/sign-up/email", { data: account }).catch(() => undefined); // idempotent
+  if (signUp) await ctx.post("/api/auth/sign-up/email", { data: account }).catch(() => undefined); // idempotent
   const res = await ctx.post("/api/auth/sign-in/email", {
     data: { email: account.email, password: account.password },
   });
-  expect(res.ok(), `sign-in ${account.email}`).toBeTruthy();
+  expect(
+    res.ok(),
+    signUp
+      ? `sign-in ${account.email}`
+      : `sign-in ${account.email}: create the administrator first with ` +
+          `ADMIN_BOOTSTRAP_EMAIL=${account.email} ADMIN_BOOTSTRAP_PASSWORD=<its password> ADMIN_BOOTSTRAP_NAME="${account.name}" {{apiRun}} admin:bootstrap{{apiWorkspaceArg}}, ` +
+          "or name an existing administrator as tests/helpers/accounts.ts describes",
+  ).toBeTruthy();
   // Each run signs in again, so keep a long-lived local database from piling up
   // this account's sessions: the seeded one is the only one left.
   expect((await ctx.post("/api/auth/revoke-other-sessions")).ok(), `clear old sessions for ${account.email}`).toBeTruthy();
@@ -60,7 +72,7 @@ async function seedSession(
 }
 
 setup("seed admin session", async ({ playwright }) => {
-  await seedSession(playwright, ADMIN, adminState);
+  await seedSession(playwright, ADMIN, adminState, { signUp: false });
 });
 
 // Feature flags are DB-backed (seeded by the app_setting migration). phoneNumber
@@ -75,7 +87,7 @@ setup("enable optional features", async ({ playwright }) => {
 });
 
 setup("seed user session", async ({ playwright }) => {
-  await seedSession(playwright, USER, userState);
+  await seedSession(playwright, USER, userState, { signUp: true });
 });
 
 setup("capture the user cleanup baseline", async ({ playwright }) => {

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

@@ -1,6 +1,6 @@
 import { expect, test } from "../helpers/disposable-users";
 import { ready } from "../helpers/hydration";
-import { mailpitReachable, waitForLink } from "../helpers/mailpit";
+import { skipUnlessMailReachesMailpit, waitForLink } from "../helpers/mailpit";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 
@@ -17,7 +17,7 @@ test("verification badges stay hidden when the feature is off", async ({ page })
 
 // Admin can trigger a password-reset email for a user (not verification-gated).
 test("admin sends a password reset email to a user", async ({ page, disposableUsers }) => {
-  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  await skipUnlessMailReachesMailpit();
   await ready(page, "/admin/users");
   const email = `admin-reset-${Date.now()}@example.com`;
   await disposableUsers.create({ email, name: "AR" });

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

@@ -1,7 +1,7 @@
 import { expect, test } from "@playwright/test";
 import { anonState } from "../helpers/accounts";
 import { ready } from "../helpers/hydration";
-import { mailpitReachable, waitForLink } from "../helpers/mailpit";
+import { skipUnlessMailReachesMailpit, waitForLink } from "../helpers/mailpit";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -10,7 +10,7 @@ const origin = { origin: base };
 test.use({ storageState: anonState });
 
 test("forgot password: request, open the emailed link, set a new password, sign in", async ({ page, playwright }) => {
-  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  await skipUnlessMailReachesMailpit();
   const email = `ui-reset-${Date.now()}@example.com`;
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const signup = await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "UIReset" } });

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

@@ -1,7 +1,7 @@
 import { expect, test } from "@playwright/test";
 import { anonState } from "../helpers/accounts";
 import { ready } from "../helpers/hydration";
-import { mailpitReachable, waitForOtp } from "../helpers/mailpit";
+import { skipUnlessMailReachesMailpit, waitForOtp } from "../helpers/mailpit";
 
 test.use({ storageState: anonState });
 
@@ -24,7 +24,7 @@ test("login: an emailed one-time code signs a user in", async ({ page, playwrigh
   const api = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const caps = await (await api.get("/api/account/capabilities")).json();
   test.skip(!caps?.emailOtp, "email otp disabled");
-  test.skip(!(await mailpitReachable()), "mailpit unreachable");
+  await skipUnlessMailReachesMailpit();
 
   const email = `ui-otp-${Date.now()}@example.com`;
   await api.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "OTP" } });

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

@@ -57,8 +57,8 @@ test("settings: open and save the SMTP dialog", { tag: "@exclusive" }, async ({
   await page.getByRole("button", { name: "SMTP settings" }).click();
   const dialog = page.getByRole("dialog");
   try {
-    // Point at the same Mailpit the env already uses, so saving can't re-route mail
-    // for the other email specs.
+    // SMTP stays switched off, so saving these values can't re-route mail for the
+    // other email specs: the mailer keeps the environment's transport.
     await dialog.locator("#smtp-host").fill("localhost");
     await dialog.locator("#smtp-port").fill("1125");
     await dialog.getByRole("button", { name: "Save", exact: true }).click();

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

@@ -51,7 +51,9 @@
     }
   },
   "env": [
-    "# admin-dashboard: emails auto-promoted to the admin role on sign-up (comma-separated)",
+    "# admin-dashboard: administrator emails (comma-separated). An account with one becomes an",
+    "# admin when admin:bootstrap creates it or a sign-in verifies the address; an email and",
+    "# password sign-up with one is refused. A production API refuses placeholders (example.com).",
     "ADMIN_EMAILS=admin@example.com"
   ],
   "migrations": [
@@ -140,7 +142,7 @@
   "instructions": [
     "Set ADMIN_EMAILS in .env (comma-separated). After building and migrating, inject ADMIN_BOOTSTRAP_EMAIL and ADMIN_BOOTSTRAP_PASSWORD for one command only, then run {{apiRun}} admin:bootstrap{{apiWorkspaceArg}}. The command creates a verified, approved admin or safely verifies an existing one.",
     "Run all migrations to add the admin and sign-up approval columns: bun run --cwd apps/api migrate:all",
-    "Remove ADMIN_BOOTSTRAP_PASSWORD from the environment after bootstrap. Keep ADMIN_EMAILS so matching future sign-ups are promoted consistently.",
+    "Remove ADMIN_BOOTSTRAP_PASSWORD from the environment after bootstrap. Keep ADMIN_EMAILS with the administrators' real addresses: a later account with one becomes an administrator only when a sign-in verifies the address as it creates the account, an email and password sign-up with one is refused, and a production API refuses to start with a placeholder such as an example.com address.",
     "Admin pages: /admin/users (list, approve pending registrations, ban, set role, revoke sessions). Signed-in users manage their profile, profile image, and security at /account; /admin/account remains available in the admin shell. Profile images accept PNG, JPEG, and WebP up to 2 MB and 2048 by 2048 pixels. Admin, account, authentication, maintenance, and API responses include X-Robots-Tag: noindex, nofollow by default.",
     "Password reset emails go through the mailer module (installed automatically with auth); in dev without SMTP they are logged to the API console. Configure SMTP in admin settings or via SMTP_* env for production."
   ]

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

@@ -13,13 +13,33 @@ which the Better Auth plugin in `audit-hook.ts` maps to semantic action codes li
 matters.
 
 The plugin records an action only when the request succeeded, so a wrong
-password or a forbidden admin call leaves no entry. Every sign-in method records
+password or a forbidden admin call leaves no entry. The exception is a new
+account: `auth.signup` is recorded when Better Auth stores the user, whichever
+endpoint creates it (email sign-up, a social provider's callback, a magic link,
+an email code, or a plugin the app adds), and even when the request then fails,
+as a social sign-up that waits for approval does when it is refused a session.
+Its `metadata.method` names the endpoint the way `auth.login` does, with the
+provider for a social sign-up, for example
+`{ "method": "social", "provider": "google" }`. A user an administrator creates
+is recorded as `user.create` only. Entries name the user even when the request
+carries no session: `auth.logout` names each account whose session the sign-out
+ended (a sign-out without a session records nothing), a password reset by link
+or code and an email verification name the account they changed,
+`user.session_revoke` names the owner of the revoked session, and
+`user.stop_impersonate` names the administrator. Every sign-in method records
 `auth.login` with the method in `metadata.method` (`password`, `email-otp`,
 `magic-link`, `passkey`, `two-factor-totp`, ...) and, for social sign-in, the
-provider in `metadata.provider`. A two-factor sign-in is recorded when the second
-factor completes it, not at the password step. `auth.ts` pushes the plugin after
-every other plugin: Better Auth runs after hooks in plugin order, and two-factor
-changes the outcome of a password sign-in in its own after hook.
+provider in `metadata.provider`. A sign-in through an endpoint of a plugin the
+app adds, such as `@better-auth/electron`'s `/electron/token`, is recorded too,
+with the endpoint's path as the method: any request that ends with a new session
+it did not come with is a sign-in, except the endpoints in `NOT_SIGN_INS`
+(sign-up, impersonation, switching between a browser's sessions, and requests
+that replace the signed-in user's own session). Session reads and updates that
+refresh the request's own session, including bearer and API key requests, are
+not. A two-factor sign-in is recorded when the second factor completes it, not
+at the password step. `auth.ts` pushes the plugin after every other plugin:
+Better Auth runs after hooks in plugin order, and two-factor changes the outcome
+of a password sign-in in its own after hook.
 
 ## Audit your own Elysia routes
 
@@ -96,9 +116,12 @@ survives renames/deletes), `targetType/targetId/targetLabel`, `ip`, `metadata`
 ## Customize
 
 - **Auth actions:** `ACTIONS` in `audit-hook.ts` maps Better Auth endpoints to
-  action codes, and `SIGN_IN_METHODS` lists the endpoints that sign a user in.
-  The `audit-hook.spec.ts` test fails when the app's Better Auth gains a sign-in
-  endpoint that neither list classifies.
+  action codes, `SIGN_IN_METHODS` names the method of Better Auth's sign-in
+  endpoints, and `NOT_SIGN_INS` lists the endpoints that start or swap a session
+  without a sign-in. The `audit-hook.spec.ts` test fails when Better Auth or a
+  plugin PodoKit configures gains an endpoint that it has not classified; the
+  endpoints of plugins the app adds are recorded as sign-ins when they start a
+  session, without a change to these lists.
 - **Your routes:** call `AuditService.recordRequest()` after successful operations;
   pass `{ defer: true }` only for high-volume, non-security events.
 - **Schema:** add columns with a migration, and keep the