@podosoft/podokit 1.6.1 → 1.6.3

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/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/files/tests/ui/theme-mode.ui.spec.ts

@@ -10,11 +10,11 @@ async function chooseTheme(page: Page, mode: "Light" | "Dark" | "System"): Promi
 // mode-watcher marks <html> with `.dark` or `.light`, so component libraries
 // that follow either class, and fall back to the OS setting otherwise, match the
 // theme the visitor chose rather than the system one. The managed ThemeToggle
-// renders on the page app-paths.ts names as the account menu page.
+// renders on the page app-paths.ts names as themeToggle.
 test("the chosen theme is named on <html> in both modes", async ({ page }) => {
-  test.skip(paths.accountMenu === null, "no page renders the theme toggle (tests/helpers/app-paths.ts)");
+  test.skip(paths.themeToggle === null, "no page renders the theme toggle (tests/helpers/app-paths.ts)");
   await page.emulateMedia({ colorScheme: "dark" });
-  await ready(page, paths.accountMenu ?? "/");
+  await ready(page, paths.themeToggle ?? "/");
   const html = page.locator("html");
 
   await chooseTheme(page, "Light");

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

@@ -8,10 +8,26 @@ actor / action / target model. Every entry flows through one pipeline
 
 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
+which the Better Auth plugin in `audit-hook.ts` maps to semantic action codes like
 `user.create` and `auth.login`. Everything else is **opt-in** — you decide what
 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
+`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 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
 
 ```ts
@@ -86,7 +102,13 @@ survives renames/deletes), `targetType/targetId/targetLabel`, `ip`, `metadata`
 
 ## Customize
 
-- **Auth actions:** edit the `ACTIONS` map in `audit-hook.ts`.
+- **Auth actions:** `ACTIONS` in `audit-hook.ts` maps Better Auth endpoints to
+  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