@podosoft/podokit 1.6.2 → 1.6.3

package/dist/templates/fullstack/apps/api/src/database/database.spec.ts

@@ -1,5 +1,7 @@
 import { SQL } from "bun";
 import { describe, expect, it } from "bun:test";
+import { createSocket } from "node:dgram";
+import { Resolver } from "node:dns/promises";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { connect, createServer, type AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
@@ -62,6 +64,45 @@ function probedSql(): ProbedSql {
   };
 }
 
+interface LocalDns {
+  resolver: Resolver;
+  close: () => void;
+}
+
+// A resolver that asks a DNS server on a local UDP port instead of the system's,
+// whose answers depend on the machine. The server answers every query with
+// NXDOMAIN, or never answers when `answers` is false.
+async function localDns(answers: boolean): Promise<LocalDns> {
+  const server = createSocket("udp4");
+  if (answers) {
+    server.on("message", (query, peer) => {
+      // The header and the question, flagged as a response with RCODE 3 and no records.
+      let end = 12;
+      while (end < query.length && query[end] !== 0) end += (query[end] ?? 0) + 1;
+      const response = Buffer.from(query.subarray(0, end + 5));
+      response[2] = 0x80 | ((query[2] ?? 0) & 0x01);
+      response[3] = 0x83;
+      response.writeUInt16BE(1, 4);
+      response.fill(0, 6, 12);
+      server.send(response, peer.port, peer.address);
+    });
+  }
+  await new Promise<void>((resolve) => server.bind(0, "127.0.0.1", resolve));
+  // Bun waits at least a second for an answer; a single try keeps that the whole wait.
+  const resolver = new Resolver({ timeout: 200, tries: 1 });
+  resolver.setServers([`127.0.0.1:${server.address().port}`]);
+  return { resolver, close: () => server.close() };
+}
+
+async function lookupError(answers: boolean): Promise<unknown> {
+  const dns = await localDns(answers);
+  try {
+    return await dns.resolver.resolve4("database.invalid").then(() => undefined, (reason: unknown) => reason);
+  } finally {
+    dns.close();
+  }
+}
+
 describe("database provider", () => {
   it("uses DATABASE_URL as the canonical connection setting", () => {
     const provider = databaseProvider();
@@ -266,11 +307,16 @@ describe("isDatabaseUnavailable", () => {
   });
 
   it("recognizes a real lookup of a host that does not exist", async () => {
-    // .invalid never resolves (RFC 2606). A resolver that does not answer at all
-    // fails with ETIMEOUT after about 16 seconds, which is recognized too.
-    const error: unknown = await fetch("http://database.invalid/").then(() => undefined, (reason: unknown) => reason);
+    const error = await lookupError(true);
+    expect((error as { code?: unknown }).code).toBe("ENOTFOUND");
     expect(isDatabaseUnavailable(error)).toBe(true);
-  }, 30_000);
+  });
+
+  it("recognizes a real lookup that the resolver never answers", async () => {
+    const error = await lookupError(false);
+    expect((error as { code?: unknown }).code).toBe("ETIMEOUT");
+    expect(isDatabaseUnavailable(error)).toBe(true);
+  });
 
   it("recognizes a real refused connection to localhost", async () => {
     const server = createServer();

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";
@@ -171,7 +171,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/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/audit-log/files/apps/api/src/audit/README.md

@@ -16,10 +16,17 @@ 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 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 +103,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

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

@@ -1,25 +1,82 @@
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { createHash, createHmac } from "node:crypto";
+import { apiKey } from "@better-auth/api-key";
 import { oauthProvider } from "@better-auth/oauth-provider";
 import { envAuthConfig } from "@podosoft/podokit-auth";
-import { betterAuth } from "better-auth";
+import { betterAuth, type BetterAuthOptions, type BetterAuthPlugin } from "better-auth";
 import { memoryAdapter } from "better-auth/adapters/memory";
+import { APIError, createAuthEndpoint } from "better-auth/api";
+import { setSessionCookie } from "better-auth/cookies";
 import { getAuthTables } from "better-auth/db";
-import { admin, emailOTP, jwt, magicLink, twoFactor } from "better-auth/plugins";
+import { admin, bearer, emailOTP, jwt, magicLink, multiSession, twoFactor } from "better-auth/plugins";
 import { buildAuth } from "../auth/auth";
 import { setAuditRecorder, type AuditEntry } from "./audit-events";
-import { auditPlugin, SIGN_IN_METHODS } from "./audit-hook";
+import { auditPlugin, NOT_SIGN_INS, SIGN_IN_METHODS } from "./audit-hook";
 
 const BASE_URL = "http://localhost:5002";
 const PASSWORD = "Podokit3e-Str0ng!pw";
 
-// Endpoints that look like a sign-in but never start a session of their own.
+// The plugins PodoKit's auth.ts and modules configure. Endpoints of other
+// plugins, such as one an application adds, are not classified below: the
+// audit plugin records their sign-ins by default.
+const PODOKIT_PLUGINS = new Set([
+  "podokit-feature-gate",
+  "podokit-revoke-every-other-session",
+  "two-factor",
+  "magic-link",
+  "email-otp",
+  "username",
+  "multi-session",
+  "phone-number",
+  "api-key",
+  "passkey",
+  "organization",
+  "bearer",
+  "jwt",
+  "oauth-provider",
+  "open-api",
+  "have-i-been-pwned",
+  "admin",
+  "podokit-audit",
+]);
+
+// Endpoints of Better Auth and of those plugins that never end with a session
+// other than the one the request came with, which some of them set again. A
+// Better Auth upgrade that adds an endpoint fails "classifies every endpoint"
+// until the endpoint is added here, to SIGN_IN_METHODS, or to NOT_SIGN_INS.
 const STARTS_NO_SESSION = new Set([
-  "/sign-in/magic-link", // emails the link that /magic-link/verify signs in with
-  "/passkey/verify-registration", // adds a passkey for the signed-in user
-  "/verify-password", // checks the signed-in user's password again
-  "/delete-user/callback", // confirms an account deletion
-  "/email-otp/check-verification-otp", // checks a code without using it
+  "/.well-known/oauth-authorization-server", "/.well-known/openid-configuration", "/account-info",
+  "/admin/ban-user", "/admin/create-user", "/admin/get-user", "/admin/has-permission",
+  "/admin/list-user-sessions", "/admin/list-users", "/admin/oauth2/create-client", "/admin/oauth2/resources",
+  "/admin/oauth2/resources/:identifier", "/admin/oauth2/resources/:identifier/clients/:client_id",
+  "/admin/oauth2/update-client", "/admin/remove-user", "/admin/revoke-user-session", "/admin/revoke-user-sessions",
+  "/admin/set-role", "/admin/set-user-password", "/admin/unban-user", "/admin/update-user",
+  "/api-key/create", "/api-key/delete", "/api-key/get", "/api-key/list", "/api-key/update",
+  "/change-email", "/delete-user", "/delete-user/callback",
+  "/email-otp/change-email", "/email-otp/check-verification-otp", "/email-otp/request-email-change",
+  "/email-otp/request-password-reset", "/email-otp/reset-password", "/email-otp/send-verification-otp",
+  "/error", "/forget-password/email-otp", "/get-access-token", "/get-session", "/is-username-available", "/jwks",
+  "/link-social", "/list-accounts", "/list-sessions", "/multi-session/list-device-sessions",
+  "/oauth2/authorize", "/oauth2/client/rotate-keys", "/oauth2/client/rotate-secret", "/oauth2/consent",
+  "/oauth2/continue", "/oauth2/create-client", "/oauth2/delete-client", "/oauth2/delete-consent",
+  "/oauth2/end-session", "/oauth2/end-session/confirm", "/oauth2/get-client", "/oauth2/get-clients",
+  "/oauth2/get-consent", "/oauth2/get-consents", "/oauth2/introspect", "/oauth2/public-client",
+  "/oauth2/public-client-prelogin", "/oauth2/register", "/oauth2/revoke", "/oauth2/token", "/oauth2/update-client",
+  "/oauth2/update-consent", "/oauth2/userinfo", "/ok", "/open-api/generate-schema",
+  "/organization/accept-invitation", "/organization/cancel-invitation", "/organization/check-slug",
+  "/organization/create", "/organization/delete", "/organization/get-active-member",
+  "/organization/get-active-member-role", "/organization/get-full-organization", "/organization/get-invitation",
+  "/organization/get-organization", "/organization/has-permission", "/organization/invite-member",
+  "/organization/leave", "/organization/list", "/organization/list-invitations", "/organization/list-members",
+  "/organization/list-user-invitations", "/organization/reject-invitation", "/organization/remove-member",
+  "/organization/set-active", "/organization/update", "/organization/update-member-role",
+  "/passkey/delete-passkey", "/passkey/generate-authenticate-options", "/passkey/generate-register-options",
+  "/passkey/list-user-passkeys", "/passkey/update-passkey", "/passkey/verify-registration",
+  "/phone-number/request-password-reset", "/phone-number/reset-password", "/phone-number/send-otp",
+  "/reference", "/refresh-token", "/request-password-reset", "/reset-password", "/reset-password/:token",
+  "/revoke-other-sessions", "/revoke-session", "/revoke-sessions", "/send-verification-email",
+  "/sign-in/magic-link", "/sign-out", "/token", "/two-factor/generate-backup-codes", "/two-factor/get-totp-uri",
+  "/two-factor/send-otp", "/unlink-account", "/update-session", "/update-user", "/verify-password",
 ]);
 
 interface Mailbox {
@@ -52,15 +109,42 @@ afterEach(() => restoreRecorder());
 const logins = (): AuditEntry[] => entries.filter((entry) => entry.action === "auth.login");
 const actions = (action: string): AuditEntry[] => entries.filter((entry) => entry.action === action);
 
-// The sign-in methods PodoKit's auth.ts enables, on an in-memory database, with
-// the audit plugin pushed last as the audit-log module does.
-function startAuth(enabled: () => Promise<boolean> = async () => true) {
+// Like @better-auth/electron's /electron/token, which a desktop app calls with
+// the code its browser sign-in handed over: an endpoint of an application's own
+// plugin that starts a session for a user it looks up.
+function desktopSignIn(): BetterAuthPlugin {
+  return {
+    id: "desktop-sign-in",
+    endpoints: {
+      desktopToken: createAuthEndpoint("/desktop/token", { method: "POST" }, async (ctx) => {
+        const { code } = (ctx.body ?? {}) as { code?: string };
+        const found = code ? await ctx.context.internalAdapter.findUserByEmail(code) : null;
+        if (!found) throw new APIError("NOT_FOUND", { message: "Invalid or expired token." });
+        const session = await ctx.context.internalAdapter.createSession(found.user.id);
+        await setSessionCookie(ctx, { session, user: found.user });
+        return ctx.json({ token: session.token });
+      }),
+    },
+  };
+}
+
+interface StartOptions {
+  enabled?: () => Promise<boolean>;
+  session?: BetterAuthOptions["session"];
+}
+
+// The sign-in methods PodoKit's auth.ts enables and plugins that set or swap
+// sessions without a sign-in, on an in-memory database, with the audit plugin
+// pushed last as the audit-log module does.
+function startAuth({ enabled = async () => true, session }: StartOptions = {}) {
   const mail: Mailbox = { magicLink: "", otp: "", verification: "" };
   const db: Record<string, Record<string, unknown>[]> = {};
   const options = {
     baseURL: BASE_URL,
     secret: "audit-hook-test-secret-0123456789abcdef",
     database: memoryAdapter(db),
+    ...(session ? { session } : {}),
+    user: { changeEmail: { enabled: true, updateEmailWithoutVerification: true } },
     emailAndPassword: { enabled: true },
     emailVerification: {
       autoSignInAfterVerification: true,
@@ -103,28 +187,37 @@ function startAuth(enabled: () => Promise<boolean> = async () => true) {
           mail.otp = otp;
         },
       }),
+      multiSession(),
+      apiKey({ enableSessionForAPIKeys: true, rateLimit: { enabled: false } }),
+      bearer({ requireSignature: true }),
       jwt({ disableSettingJwtHeader: true }),
       oauthProvider({ loginPage: "/login", consentPage: "/oauth2/consent" }),
       admin(),
+      desktopSignIn(),
       auditPlugin({ enabled }),
     ],
   };
   for (const table of Object.values(getAuthTables(options))) db[table.modelName] = [];
-  return { auth: betterAuth(options), mail };
+  return { auth: betterAuth(options), mail, db };
 }
 
-// A cookie jar in front of the Better Auth router, like a browser's.
+// A cookie jar in front of the Better Auth router, like a browser's, or a client
+// that sends the same headers with every request.
 class Browser {
   private readonly auth: AuthHandler;
+  private readonly sent: Record<string, string>;
   private readonly cookies = new Map<string, string>();
 
-  constructor(auth: AuthHandler) {
+  constructor(auth: AuthHandler, sent: Record<string, string> = {}) {
     this.auth = auth;
+    this.sent = sent;
   }
 
   /** Request headers that carry this browser's cookies, for a server-side auth.api call. */
   headers(): Headers {
-    return new Headers({ cookie: [...this.cookies].map(([name, value]) => `${name}=${value}`).join("; ") });
+    const headers = new Headers(this.sent);
+    if (this.cookies.size > 0) headers.set("cookie", [...this.cookies].map(([name, value]) => `${name}=${value}`).join("; "));
+    return headers;
   }
 
   get(path: string): Promise<Response> {
@@ -160,6 +253,10 @@ async function signUp(auth: AuthHandler, email: string): Promise<Browser> {
   return browser;
 }
 
+async function userId(browser: Browser): Promise<string> {
+  return ((await (await browser.get("/get-session")).json()) as { user: { id: string } }).user.id;
+}
+
 // The current code for an otpauth:// URI, as an authenticator app computes it.
 function totp(uri: string): string {
   const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
@@ -179,6 +276,8 @@ describe("audit plugin", () => {
   test("records a password sign-in once and a wrong password not at all", async () => {
     const { auth } = startAuth();
     await signUp(auth, "password@example.com");
+    // Signing up starts a session too, recorded as the sign-up only.
+    expect(entries.map((entry) => entry.action)).toEqual(["auth.signup"]);
 
     const wrong = await new Browser(auth).post("/sign-in/email", { email: "password@example.com", password: "Wrong-password-1" });
     expect(wrong.status).toBe(401);
@@ -329,6 +428,28 @@ describe("audit plugin", () => {
     expect(signedIn.status).toBe(200);
     expect(await signedIn.json()).toMatchObject({ redirect: true, url: expect.stringContaining("code=") });
     expect(logins()).toEqual([expect.objectContaining({ actorEmail: "oauth@example.com", metadata: { method: "password" } })]);
+
+    // Authorizing again with that session and exchanging the code sign nobody in.
+    const again = await browser.get(`/oauth2/authorize?${query}`);
+    expect(again.status).toBe(302);
+    const code = new URL(again.headers.get("location") ?? "").searchParams.get("code") ?? "";
+    expect(code).not.toBe("");
+    const exchange = new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: "https://client.example.com/callback",
+      code_verifier: verifier,
+    });
+    const credentials = Buffer.from(`${client.client_id}:${client.client_secret ?? ""}`).toString("base64");
+    const token = await auth.handler(
+      new Request(`${BASE_URL}/api/auth/oauth2/token`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", authorization: `Basic ${credentials}` },
+        body: exchange,
+      }),
+    );
+    expect(token.status).toBe(200);
+    expect(logins()).toHaveLength(1);
   });
 
   test("does not record failed account and admin requests", async () => {
@@ -354,8 +475,108 @@ describe("audit plugin", () => {
     expect(logins()).toEqual([]);
   });
 
+  test("records a sign-in through an endpoint of an application's plugin with its path", async () => {
+    const { auth } = startAuth();
+    await signUp(auth, "desktop@example.com");
+    entries = [];
+
+    const desktop = new Browser(auth);
+    expect((await desktop.post("/desktop/token", { code: "nobody@example.com" })).status).toBe(404);
+    expect(logins()).toEqual([]);
+    expect((await desktop.post("/desktop/token", { code: "desktop@example.com" })).status).toBe(200);
+    expect(logins()).toEqual([
+      expect.objectContaining({ actorEmail: "desktop@example.com", metadata: { method: "/desktop/token" } }),
+    ]);
+    // The session it started is then the desktop app's own.
+    expect((await desktop.get("/get-session")).status).toBe(200);
+    expect((await desktop.post("/update-user", { name: "Desktop" })).status).toBe(200);
+    expect(logins()).toHaveLength(1);
+  });
+
+  test("records no sign-in for reads and updates that refresh the session", async () => {
+    // Every session read extends the session and the cookie cache expires at once.
+    const { auth } = startAuth({ session: { updateAge: 0, cookieCache: { enabled: true, maxAge: 1 } } });
+    const owner = await signUp(auth, "refresh@example.com");
+    entries = [];
+    expect((await owner.get("/get-session")).status).toBe(200);
+    expect((await owner.get("/get-session?disableCookieCache=true")).status).toBe(200);
+    expect((await owner.post("/update-user", { name: "Refreshed" })).status).toBe(200);
+    expect((await owner.post("/change-email", { newEmail: "refreshed@example.com" })).status).toBe(200);
+    expect((await owner.post("/update-session", {})).status).toBeLessThan(500);
+    expect((await owner.get("/token")).status).toBe(200);
+    expect((await owner.get("/list-sessions")).status).toBe(200);
+    expect(actions("account.update")).toHaveLength(1);
+    expect(actions("auth.email_change")).toHaveLength(1);
+    expect(logins()).toEqual([]);
+  });
+
+  test("records no sign-in for bearer and API key requests", async () => {
+    const { auth } = startAuth({ session: { updateAge: 0 } });
+    const owner = await signUp(auth, "client@example.com");
+    const signIn = await new Browser(auth).post("/sign-in/email", { email: "client@example.com", password: PASSWORD });
+    const token = signIn.headers.get("set-auth-token") ?? "";
+    expect(token).not.toBe("");
+    const created = await owner.post("/api-key/create", {});
+    expect(created.status).toBe(200);
+    const { key } = (await created.json()) as { key: string };
+    entries = [];
+
+    for (const client of [new Browser(auth, { authorization: `Bearer ${token}` }), new Browser(auth, { "x-api-key": key })]) {
+      for (let i = 0; i < 3; i++) expect((await client.get("/get-session")).status).toBe(200);
+      expect((await client.post("/update-user", { name: "Client" })).status).toBe(200);
+      expect((await client.get("/list-sessions")).status).toBe(200);
+    }
+    expect(actions("account.update")).toHaveLength(2);
+    expect(logins()).toEqual([]);
+  });
+
+  test("records no sign-in when an administrator impersonates a user or a browser switches accounts", async () => {
+    const { auth, db } = startAuth();
+    const operator = await signUp(auth, "operator@example.com");
+    const operatorId = await userId(operator);
+    const row = db.user?.find((user) => user.id === operatorId);
+    if (row) row.role = "admin";
+    const target = await signUp(auth, "impersonated@example.com");
+    const targetId = await userId(target);
+    entries = [];
+
+    expect((await operator.post("/admin/impersonate-user", { userId: targetId })).status).toBe(200);
+    expect(await userId(operator)).toBe(targetId);
+    expect((await operator.post("/admin/stop-impersonating", {})).status).toBe(200);
+    expect(await userId(operator)).toBe(operatorId);
+    expect(actions("user.impersonate")).toHaveLength(1);
+    expect(actions("user.stop_impersonate")).toHaveLength(1);
+    expect(logins()).toEqual([]);
+
+    // Signing in to a second account in the same browser is a sign-in; switching
+    // between the two and signing one out are not.
+    const second = await operator.post("/sign-in/email", { email: "impersonated@example.com", password: PASSWORD });
+    expect(second.status).toBe(200);
+    expect(logins()).toEqual([expect.objectContaining({ actorEmail: "impersonated@example.com" })]);
+    const sessions = (await (await operator.get("/multi-session/list-device-sessions")).json()) as Array<{
+      session: { token: string };
+      user: { id: string };
+    }>;
+    const tokenOf = (id: string): string => sessions.find((entry) => entry.user.id === id)?.session.token ?? "";
+    expect((await operator.post("/multi-session/set-active", { sessionToken: tokenOf(operatorId) })).status).toBe(200);
+    expect(await userId(operator)).toBe(operatorId);
+    expect((await operator.post("/multi-session/revoke", { sessionToken: tokenOf(operatorId) })).status).toBe(200);
+    expect(await userId(operator)).toBe(targetId);
+    expect((await operator.post("/revoke-other-sessions", {})).status).toBe(200);
+    expect((await operator.post("/revoke-sessions", {})).status).toBe(200);
+    expect(logins()).toHaveLength(1);
+
+    const again = await new Browser(auth).post("/sign-in/email", { email: "operator@example.com", password: PASSWORD });
+    expect(again.status).toBe(200);
+    const signedOut = new Browser(auth);
+    await signedOut.post("/sign-in/email", { email: "operator@example.com", password: PASSWORD });
+    expect((await signedOut.post("/sign-out", {})).status).toBe(200);
+    expect(actions("auth.logout")).toHaveLength(1);
+    expect(logins()).toHaveLength(3);
+  });
+
   test("records nothing while auditing is off", async () => {
-    const { auth } = startAuth(async () => false);
+    const { auth } = startAuth({ enabled: async () => false });
     await signUp(auth, "off@example.com");
     expect((await new Browser(auth).post("/sign-in/email", { email: "off@example.com", password: PASSWORD })).status).toBe(200);
     expect(entries).toEqual([]);
@@ -370,16 +591,19 @@ describe("the app's Better Auth", () => {
     expect(instance.options.hooks?.after).toBeUndefined();
   });
 
-  test("classifies every endpoint that can sign a user in", () => {
+  test("classifies every endpoint of Better Auth and PodoKit's plugins", () => {
     const instance = buildAuth(envAuthConfig());
-    const paths = new Set(Object.values(instance.api as Record<string, { path?: string }>).map((endpoint) => endpoint.path ?? ""));
-    expect(Object.keys(SIGN_IN_METHODS).filter((path) => !paths.has(path))).toEqual([]);
-    const unclassified = [...paths].filter(
-      (path) =>
-        (path.startsWith("/sign-in/") || /callback|verify/.test(path)) &&
-        SIGN_IN_METHODS[path] === undefined &&
-        !STARTS_NO_SESSION.has(path),
+    type Endpoints = Record<string, { path?: string }> | undefined;
+    const pathsOf = (endpoints: Endpoints): string[] =>
+      Object.values(endpoints ?? {}).flatMap((endpoint) => (endpoint.path ? [endpoint.path] : []));
+    const plugins = instance.options.plugins as Array<{ id: string; endpoints?: Endpoints }>;
+    const applications = new Set(
+      plugins.filter((plugin) => !PODOKIT_PLUGINS.has(plugin.id)).flatMap((plugin) => pathsOf(plugin.endpoints)),
     );
-    expect(unclassified).toEqual([]);
+    const paths = new Set(pathsOf(instance.api as Endpoints).filter((path) => !applications.has(path)));
+    expect(Object.keys(SIGN_IN_METHODS).filter((path) => !paths.has(path))).toEqual([]);
+    const classified = (path: string): boolean =>
+      SIGN_IN_METHODS[path] !== undefined || NOT_SIGN_INS.has(path) || STARTS_NO_SESSION.has(path);
+    expect([...paths].filter((path) => !classified(path))).toEqual([]);
   });
 });

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

@@ -1,12 +1,15 @@
 import type { BetterAuthPlugin } from "better-auth";
 import { createAuthMiddleware, isAPIError } from "better-auth/api";
+import { parseSetCookieHeader } from "better-auth/cookies";
 import { clientAddressOf } from "../core/client-address";
 import { recordAudit } from "./audit-events";
 import { auditEnabled } from "./audit-enabled";
 
-// Endpoints that sign a user in, with the method their auth.login entry records.
-// ctx.path is the route pattern an endpoint was registered with, not the request
-// URL, so every social provider's callback arrives as "/callback/:id".
+// The method that auth.login records for Better Auth's sign-in endpoints. A
+// sign-in through any other endpoint, such as one of a plugin the application
+// adds, is recorded too, with the endpoint's path as its method. ctx.path is
+// the route pattern an endpoint was registered with, not the request URL, so
+// every social provider's callback arrives as "/callback/:id".
 export const SIGN_IN_METHODS: Readonly<Record<string, string>> = {
   "/sign-in/email": "password",
   "/sign-in/username": "username",
@@ -24,6 +27,21 @@ export const SIGN_IN_METHODS: Readonly<Record<string, string>> = {
   "/email-otp/verify-email": "email-otp-verification",
 };
 
+// Endpoints that can end with a session the request did not come with without
+// signing anyone in: a sign-up, recorded as auth.signup; an administrator
+// starting or ending an impersonation; a switch to another session the browser
+// already holds; and requests that replace the signed-in user's own session.
+export const NOT_SIGN_INS: ReadonlySet<string> = new Set([
+  "/sign-up/email",
+  "/admin/impersonate-user",
+  "/admin/stop-impersonating",
+  "/multi-session/set-active",
+  "/multi-session/revoke",
+  "/two-factor/enable",
+  "/two-factor/disable",
+  "/change-password",
+]);
+
 // Other auth and admin endpoints, with the action each records once it succeeds.
 const ACTIONS: Readonly<Record<string, string>> = {
   "/sign-up/email": "auth.signup",
@@ -58,6 +76,18 @@ interface SessionRecord {
   user: { id: string; name?: string | null; email?: string | null };
 }
 
+interface SignInContext {
+  path: string;
+  context: {
+    session: SessionRecord | null;
+    responseHeaders?: Headers;
+    secret: string;
+    authCookies: { sessionToken: { name: string } };
+    internalAdapter: { findSession: (token: string) => Promise<unknown> };
+  };
+  getSignedCookie: (name: string, secret: string) => Promise<string | null | false>;
+}
+
 // After hooks run for failed requests too, with the APIError the endpoint threw
 // in ctx.context.returned. Redirects are APIErrors as well: a 3xx status, and an
 // `error` query parameter on the location when the redirect reports a failure.
@@ -73,19 +103,33 @@ function failed(returned: unknown): boolean {
   }
 }
 
-// A sign-in ends with a session the request did not come with. Two requests end
-// with a new session without signing anyone in: confirming two-factor replaces
-// the signed-in user's session, which two-factor loaded into ctx.context.session,
-// and verifying the signed-in user's email sets the cookie of the session the
-// request came with again. oauthProvider() also puts the new session into
-// ctx.context.session when a sign-in resumes an authorization request.
-function signedIn(
-  created: SessionRecord | null | undefined,
-  current: SessionRecord | null | undefined,
-  presentedToken: string | null | false,
-): created is SessionRecord {
-  if (!created || created.session.token === presentedToken) return false;
-  return !(current && current.user.id === created.user.id && current.session.token !== created.session.token);
+// A sign-in ends with a session the request did not come with, on any endpoint
+// but those in NOT_SIGN_INS.
+// - Its response sets the session cookie to the new session. An endpoint that
+//   another one dispatches, as oauthProvider() runs /oauth2/authorize when a
+//   sign-in resumes an authorization request, inherits that request's new
+//   session without setting it.
+// - A request that refreshes its own session, such as a session read that
+//   extends it or a profile update, sets it again: the session cookie it sent,
+//   or the one bearer() made of its Authorization header, has the same token.
+// - Confirming two-factor replaces the signed-in user's session, which the
+//   endpoint loaded into ctx.context.session.
+// - When the session the endpoint loaded is the new one, a stored session is a
+//   sign-in: oauthProvider() loads it when a sign-in resumes an authorization
+//   request. The session of an API key request (apiKey's
+//   enableSessionForAPIKeys) has the key as its token and is not stored.
+async function signedIn(ctx: SignInContext, created: SessionRecord): Promise<boolean> {
+  if (NOT_SIGN_INS.has(ctx.path)) return false;
+  const { token } = created.session;
+  const set = parseSetCookieHeader(ctx.context.responseHeaders?.get("set-cookie") ?? "");
+  const cookie = set.get(ctx.context.authCookies.sessionToken.name)?.value;
+  if (decodeURIComponent(cookie ?? "").split(".")[0] !== token) return false;
+  const presented = await ctx.getSignedCookie(ctx.context.authCookies.sessionToken.name, ctx.context.secret);
+  if (token === presented) return false;
+  const current = ctx.context.session;
+  if (!current) return true;
+  if (current.session.token !== token) return current.user.id !== created.user.id;
+  return Boolean(await ctx.context.internalAdapter.findSession(token));
 }
 
 export interface AuditPluginOptions {
@@ -96,7 +140,9 @@ export interface AuditPluginOptions {
 // Records auth and admin actions through the application audit pipeline. Pushed
 // after every other plugin, because after hooks run in plugin order and earlier
 // ones change the outcome: two-factor turns a password sign-in into a pending
-// challenge by clearing ctx.context.newSession.
+// challenge by clearing ctx.context.newSession. It runs for every endpoint, the
+// server-side session lookup of each API request included, so a request with
+// neither an action nor a new session returns before any other work.
 export function auditPlugin(options: AuditPluginOptions = {}): BetterAuthPlugin & { id: "podokit-audit" } {
   const enabled = options.enabled ?? auditEnabled;
   return {
@@ -104,15 +150,19 @@ export function auditPlugin(options: AuditPluginOptions = {}): BetterAuthPlugin
     hooks: {
       after: [
         {
-          matcher: (context) => Boolean(context.path && (SIGN_IN_METHODS[context.path] || ACTIONS[context.path])),
+          matcher: (context) => Boolean(context.path),
           handler: createAuthMiddleware(async (ctx) => {
+            const action = ACTIONS[ctx.path];
+            const created = ctx.context.newSession;
+            if (!action && !created) return;
             if (failed(ctx.context.returned)) return;
+            const login = created && (await signedIn(ctx, created)) ? created : null;
+            if (!action && !login) return;
             // AuditService checks the toggle again on write; checking here as well
             // skips the lookups below when auditing is off.
             if (!(await enabled())) return;
             const ip = clientAddressOf(ctx.headers) ?? null;
 
-            const action = ACTIONS[ctx.path];
             if (action) {
               const actor = ctx.context.session?.user ?? ctx.context.newSession?.user;
               const body = (ctx.body ?? {}) as { email?: string; userId?: string };
@@ -140,21 +190,18 @@ export function auditPlugin(options: AuditPluginOptions = {}): BetterAuthPlugin
               });
             }
 
-            const method = SIGN_IN_METHODS[ctx.path];
-            if (!method) return;
-            const created = ctx.context.newSession;
-            const presented = await ctx.getSignedCookie(ctx.context.authCookies.sessionToken.name, ctx.context.secret);
-            if (!signedIn(created, ctx.context.session, presented)) return;
+            if (!login) return;
+            const method = SIGN_IN_METHODS[ctx.path] ?? ctx.path;
             const params = (ctx.params ?? {}) as { id?: string };
             const body = (ctx.body ?? {}) as { provider?: string };
             const provider = method === "social" ? (params.id ?? body.provider) : undefined;
             await recordAudit({
               action: "auth.login",
-              actorId: created.user.id,
-              actorName: created.user.name ?? null,
-              actorEmail: created.user.email ?? null,
-              targetId: created.user.id,
-              targetLabel: created.user.email ?? null,
+              actorId: login.user.id,
+              actorName: login.user.name ?? null,
+              actorEmail: login.user.email ?? null,
+              targetId: login.user.id,
+              targetLabel: login.user.email ?? null,
               ip,
               metadata: provider ? { method, provider } : { method },
             });

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -20,11 +20,41 @@ const origin = { origin: base };
 // RateLimit-Limit and RateLimit-Remaining headers. The spec reads the limits from
 // them, so it follows whatever limits the stack runs with. When the runner's
 // environment sets RATE_LIMIT_MAX, RATE_LIMIT_AUTH_MAX, or RATE_LIMIT_RUNTIME_MAX,
-// the spec also expects the stack to use that value. It sends one more request
-// than the general limit, so a run that should not spend that many on a raised
-// limit sets E2E_SKIP_RATE_LIMIT=true to skip the file.
+// the spec also expects the stack to use that value. A test that sends a budget's
+// worth of requests times the first ones and skips, with the reason, when the
+// rest would not fit in its time, as with raised local limits. A run that should
+// not send them at all sets E2E_SKIP_RATE_LIMIT=true to skip the file.
 test.skip(process.env.E2E_SKIP_RATE_LIMIT === "true", "E2E_SKIP_RATE_LIMIT is true");
 
+/** Requests a test times before it judges whether the rest fit in its time. */
+const PACE_SAMPLE = 50;
+
+let testStarted = Date.now();
+test.beforeEach(() => {
+  testStarted = Date.now();
+});
+
+function seconds(ms: number): string {
+  return `${(ms / 1000).toFixed(1)} s`;
+}
+
+/**
+ * Why `left` more requests, sent at the pace of the `sent` ones since `since`,
+ * would not end within half of the time this test has left, or undefined when
+ * they would. The other half leaves room for a slower stretch.
+ */
+function outOfTime(sent: number, since: number, left: number): string | undefined {
+  const { timeout } = test.info();
+  if (timeout === 0) return undefined;
+  const now = Date.now();
+  const perRequest = (now - since) / sent;
+  const needed = perRequest * left;
+  const available = timeout - (now - testStarted);
+  if (needed <= available / 2) return undefined;
+  const pace = Math.round(1000 / perRequest);
+  return `${left} more requests at ${pace} per second take about ${seconds(needed)}, more than half of the ${seconds(available)} this test has left`;
+}
+
 /** Requires a session, so a session's requests count under its user from the first one. */
 const PROBE = "/api/account/me";
 const HEALTH = ["/api/health", "/api/health/ready"];
@@ -64,11 +94,14 @@ async function inOneWindow(check: () => Promise<void>): Promise<void> {
 }
 
 /**
- * Requests the probe until the limiter answers 429, or null when the general
- * window keeps ending first. More remaining than on the request before means a
- * new window started, which starts the count over.
+ * Requests the probe until the limiter answers 429, or returns why it stopped
+ * first: the general window kept ending first, or the requests left to the
+ * limit would not fit in the test's time. More remaining than on the request
+ * before means a new window started, which starts the count over.
  */
-async function untilLimited(ctx: APIRequestContext, limit: number): Promise<APIResponse | null> {
+async function untilLimited(ctx: APIRequestContext, limit: number): Promise<APIResponse | string> {
+  const started = Date.now();
+  let sent = 0;
   let windows = 1;
   let counted = 0;
   let previous = Number.POSITIVE_INFINITY;
@@ -77,15 +110,21 @@ async function untilLimited(ctx: APIRequestContext, limit: number): Promise<APIR
     if (response.status() === 429) return response;
     expect(response.status(), `${PROBE} request ${counted + 1} of window ${windows}`).toBe(200);
     const { remaining } = budget(response);
+    sent += 1;
     if (remaining >= previous) {
       windows += 1;
       counted = 0;
-      if (windows > 3) return null;
+      if (windows > 3) return `the general window ends before this client sends ${limit} requests`;
     }
     previous = remaining;
     counted += 1;
     // A window holds at most `limit` served requests.
     expect(counted, `requests served in one general window`).toBeLessThanOrEqual(limit);
+    // Judged in each window, since a new one needs the whole limit again.
+    if (counted === PACE_SAMPLE) {
+      const late = outOfTime(sent, started, remaining + 1);
+      if (late) return `reaching the general limit (${limit}): ${late}`;
+    }
   }
 }
 
@@ -139,7 +178,6 @@ test("rate limit: health probes stay available while ordinary routes return 429
   expect(probe.status()).toBe(200);
   const { limit } = budget(probe);
   expectConfigured("RATE_LIMIT_MAX", limit);
-  test.skip(limit > 10_000, `the general budget (${limit}) is too large to exhaust here`);
 
   // Health probes are not counted: they carry no budget and leave the general one as it was.
   await inOneWindow(async () => {
@@ -156,9 +194,12 @@ test("rate limit: health probes stay available while ordinary routes return 429
 
   // A window serves `limit` requests and rejects the next one.
   const limited = await untilLimited(ctx, limit);
-  test.skip(limited === null, `the general window ends before this client sends ${limit} requests`);
-  expect(limited?.headers()["retry-after"]).toBeTruthy();
-  expect(await limited?.json()).toMatchObject({
+  if (typeof limited === "string") {
+    test.skip(true, limited);
+    return;
+  }
+  expect(limited.headers()["retry-after"]).toBeTruthy();
+  expect(await limited.json()).toMatchObject({
     success: false,
     error: { code: "RATE_LIMIT_EXCEEDED", statusCode: 429 },
   });
@@ -239,10 +280,14 @@ test("rate limit: session reads do not consume the strict authentication budget"
     reads + 1 > runtimeLimit,
     `the authentication budget (${authLimit}) is not far enough below the runtime budget (${runtimeLimit})`,
   );
-  test.skip(authLimit > 1000, `the authentication budget (${authLimit}) is too large to exhaust here`);
-  for (let i = 0; i < reads; i++) {
+  const started = Date.now();
+  for (let i = 1; i <= reads; i++) {
     const response = await ctx.get("/api/auth/get-session");
-    expect(response.status(), `session request ${i + 1}`).toBe(200);
+    expect(response.status(), `session request ${i}`).toBe(200);
+    if (i === PACE_SAMPLE) {
+      const late = outOfTime(i, started, reads - i);
+      test.skip(late !== undefined, `reading past the authentication budget (${authLimit}): ${late}`);
+    }
   }
   await ctx.dispose();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {