@podosoft/podokit 1.6.2 → 1.6.4

package/dist/templates/modules/auth/files/apps/api/src/auth/admin-emails.ts

@@ -0,0 +1,68 @@
+import { APIError } from "better-auth/api";
+import { PUBLIC_SIGNUP_DISABLED } from "./feature-gate";
+
+// Domains reserved for documentation and testing (RFC 2606, RFC 6761). They
+// receive no mail, so an address on one, such as admin@example.com, is a
+// placeholder that nobody can prove.
+const RESERVED_DOMAINS = ["example.com", "example.net", "example.org"];
+const RESERVED_TOP_LEVEL = new Set(["example", "test", "invalid", "localhost"]);
+
+/** Why an ADMIN_EMAILS entry cannot name a real administrator, or null when it can. */
+export function adminEmailProblem(entry: string): string | null {
+  const domain = entry.slice(entry.lastIndexOf("@") + 1);
+  if (
+    RESERVED_DOMAINS.some((name) => domain === name || domain.endsWith(`.${name}`)) ||
+    RESERVED_TOP_LEVEL.has(domain.slice(domain.lastIndexOf(".") + 1))
+  ) {
+    return "a placeholder on a reserved domain";
+  }
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(entry) ? null : "not an email address";
+}
+
+/**
+ * The administrator addresses in ADMIN_EMAILS, lowercased. In production an
+ * entry that is not an address, or a placeholder such as admin@example.com,
+ * stops the API: a placeholder means the administrators were never configured.
+ */
+export function adminEmailsFrom(
+  value: string | undefined,
+  production = process.env.NODE_ENV === "production",
+): ReadonlySet<string> {
+  const entries = (value ?? "")
+    .split(",")
+    .map((email) => email.trim().toLowerCase())
+    .filter(Boolean);
+  if (production) {
+    const problems = entries.flatMap((entry) => {
+      const problem = adminEmailProblem(entry);
+      return problem ? [`"${entry}" is ${problem}`] : [];
+    });
+    if (problems.length > 0) {
+      throw new Error(
+        `ADMIN_EMAILS must list real administrator addresses in production, or stay empty: ${problems.join("; ")}.`,
+      );
+    }
+  }
+  return new Set(entries);
+}
+
+/**
+ * Whether a new account becomes an administrator through ADMIN_EMAILS. Only an
+ * account that has proven its address does: one created with a verified email
+ * (a social provider's verified address, a magic link or email code, or
+ * admin:bootstrap) or one an administrator creates. Any other account with a
+ * listed address is refused, so nobody can register an administrator's address
+ * before its owner and take the role, the approval, or the address itself.
+ */
+export function becomesAdministrator(
+  user: { email: string; emailVerified?: boolean | null },
+  createdByAdmin: boolean,
+  administrators: ReadonlySet<string>,
+): boolean {
+  if (!administrators.has(user.email.toLowerCase())) return false;
+  if (user.emailVerified === true || createdByAdmin) return true;
+  throw APIError.from("FORBIDDEN", {
+    code: PUBLIC_SIGNUP_DISABLED,
+    message: "This email address cannot be registered by sign-up.",
+  });
+}

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -17,18 +17,14 @@ import { authBaseUrl, authSecret } from "./auth-environment";
 import { isMaintenanceCommand } from "./maintenance";
 import { CLIENT_ADDRESS_HEADER } from "../core/client-address";
 import { revokeEveryOtherSession } from "./revoke-other-sessions";
+import { adminEmailsFrom, becomesAdministrator } from "./admin-emails";
 // podokit:begin:auth-imports
 // podokit:end:auth-imports
 
 // Web origin(s) where the browser runs (WebAuthn ceremonies must match these).
 const webOrigins = (process.env.CORS_ORIGIN ?? "http://localhost:5001").split(",").map((o) => o.trim());
 
-const adminEmails = new Set(
-  (process.env.ADMIN_EMAILS ?? "")
-    .split(",")
-    .map((email) => email.trim().toLowerCase())
-    .filter(Boolean),
-);
+const adminEmails = adminEmailsFrom(process.env.ADMIN_EMAILS);
 
 // Enabled social providers, from the resolved config (DB-first, env fallback).
 // Admins add/edit/remove providers dynamically (Settings page), so this maps the
@@ -45,6 +41,56 @@ function buildSocial(config: AuthConfig): NonNullable<BetterAuthOptions["socialP
   return providers as NonNullable<BetterAuthOptions["socialProviders"]>;
 }
 
+// The account and session rules of buildAuth: who may be created, who starts as
+// an administrator or approved, and who may hold a session.
+export function databaseHooksFor(
+  config: Pick<AuthConfig, "requireSignupApproval">,
+  administrators: ReadonlySet<string>,
+  signupOpen: () => Promise<boolean>,
+): NonNullable<BetterAuthOptions["databaseHooks"]> {
+  return {
+    user: {
+      create: {
+        before: async (user, context) => {
+          const createdByAdmin = context?.path === "/admin/create-user";
+          assertUserCreationAllowed(await readSignupOpen(signupOpen), context?.path);
+          const adminEmail = becomesAdministrator(user, createdByAdmin, administrators);
+          return {
+            data: {
+              ...user,
+              // The admin plugin contributes `role` before this hook. Preserve an
+              // explicitly requested admin-created role, while ADMIN_EMAILS
+              // addresses always become administrators.
+              ...(Object.prototype.hasOwnProperty.call(user, "role")
+                ? { role: adminEmail ? "admin" : user.role }
+                : {}),
+              // Existing rows are treated as approved through the field default.
+              // Only self-registration while the policy is enabled starts pending.
+              signupApproved: adminEmail || createdByAdmin || !config.requireSignupApproval,
+            },
+          };
+        },
+      },
+    },
+    session: {
+      create: {
+        before: async (session, context) => {
+          if (!context) return;
+          const user = (await context.context.internalAdapter.findUserById(session.userId)) as {
+            signupApproved?: boolean | null;
+          } | null;
+          if (user?.signupApproved === false) {
+            throw APIError.from("FORBIDDEN", {
+              code: SIGNUP_APPROVAL_REQUIRED,
+              message: "Your account is waiting for administrator approval.",
+            });
+          }
+        },
+      },
+    },
+  };
+}
+
 // Build a better-auth instance from resolved config. Called at boot and rebuilt by
 // auth-provider.ts when the DB config changes, so admin edits (OAuth credentials,
 // server-enforced toggles) apply without a restart. Everything below the injection
@@ -147,47 +193,7 @@ export function buildAuth(config: AuthConfig) {
   // podokit:begin:auth-plugins
   // podokit:end:auth-plugins
 
-  const databaseHooks: NonNullable<BetterAuthOptions["databaseHooks"]> = {
-    user: {
-      create: {
-        before: async (user, context) => {
-          const adminEmail = adminEmails.has(user.email.toLowerCase());
-          const createdByAdmin = context?.path === "/admin/create-user";
-          assertUserCreationAllowed(await readSignupOpen(isSignupOpen), context?.path);
-          return {
-            data: {
-              ...user,
-              // The admin plugin contributes `role` before this hook. Preserve an
-              // explicitly requested admin-created role, while bootstrap emails
-              // always become administrators.
-              ...(Object.prototype.hasOwnProperty.call(user, "role")
-                ? { role: adminEmail ? "admin" : user.role }
-                : {}),
-              // Existing rows are treated as approved through the field default.
-              // Only self-registration while the policy is enabled starts pending.
-              signupApproved: adminEmail || createdByAdmin || !config.requireSignupApproval,
-            },
-          };
-        },
-      },
-    },
-    session: {
-      create: {
-        before: async (session, context) => {
-          if (!context) return;
-          const user = (await context.context.internalAdapter.findUserById(session.userId)) as {
-            signupApproved?: boolean | null;
-          } | null;
-          if (user?.signupApproved === false) {
-            throw APIError.from("FORBIDDEN", {
-              code: SIGNUP_APPROVAL_REQUIRED,
-              message: "Your account is waiting for administrator approval.",
-            });
-          }
-        },
-      },
-    },
-  };
+  const databaseHooks = databaseHooksFor(config, adminEmails, isSignupOpen);
 
   // Request-time hooks. The feature gate turns the admin Settings toggles into a
   // real server boundary (disabled features 404) for endpoint calls, including

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/SKILL.md

@@ -98,7 +98,7 @@ export MAIL_FROM="Example <noreply@example.com>"
 2. Open `/login` and confirm the provider button appears.
 3. With sign-up approval enabled, register a disposable account and confirm it reaches `/pending-approval` without a session.
 4. Open `/admin/users`, filter by **Pending approval**, approve the account, and confirm sign-in succeeds.
-5. Confirm administrator-created users and emails in `ADMIN_EMAILS` do not enter the approval queue.
+5. Confirm administrator-created users and administrators made from `ADMIN_EMAILS` do not enter the approval queue, and that an email and password sign-up with an `ADMIN_EMAILS` address is refused.
 6. Send a real verification or password-reset email and inspect SPF, DKIM, and DMARC results in the receiving mailbox.
 
 ## Preserve provider independence

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/bootstrap-admin.md

@@ -9,8 +9,15 @@ Do not create the first administrator through the public sign-up page.
 
 Set `ADMIN_EMAILS` in the same deployment environment used by the API. Include
 the exact lowercase-normalized address selected for the initial administrator.
-Keep this value after bootstrap so future matching sign-ups retain the same role
-policy.
+Use the administrators' real addresses: with `NODE_ENV=production` the API
+refuses to start when an entry is not an address or is on a reserved
+documentation name such as `example.com`, and `podo deploy doctor` fails on it.
+
+Keep this value after bootstrap. A later account with a listed address becomes
+an administrator only when its address is proven as the account is created: by
+`admin:bootstrap`, an administrator, a social provider that reports the email
+verified, a magic link, or an email code. An email and password sign-up with a
+listed address is refused, so nobody can claim it before its owner.
 
 ## Inject credentials for one command
 

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.4",
   "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": {