@podosoft/podokit 1.6.3 → 1.6.4

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

@@ -1,13 +1,13 @@
-import type { BetterAuthPlugin } from "better-auth";
+import type { BetterAuthOptions, 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 { recordAudit, type AuditEntry } from "./audit-events";
 import { auditEnabled } from "./audit-enabled";
 
-// 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 method that auth.login and auth.signup record 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>> = {
@@ -43,14 +43,19 @@ export const NOT_SIGN_INS: ReadonlySet<string> = new Set([
 ]);
 
 // Other auth and admin endpoints, with the action each records once it succeeds.
+// A new account records auth.signup from the plugin's database hook instead, so
+// every endpoint that creates one is covered.
 const ACTIONS: Readonly<Record<string, string>> = {
-  "/sign-up/email": "auth.signup",
   "/sign-out": "auth.logout",
   "/change-password": "auth.password_change",
   "/change-email": "auth.email_change",
+  "/email-otp/change-email": "auth.email_change",
   "/reset-password": "auth.password_reset",
+  "/email-otp/reset-password": "auth.password_reset",
+  "/phone-number/reset-password": "auth.password_reset",
   "/send-verification-email": "auth.verification_sent",
   "/verify-email": "auth.email_verified",
+  "/email-otp/verify-email": "auth.email_verified",
   "/update-user": "account.update",
   "/delete-user": "account.delete",
   "/revoke-session": "session.revoke",
@@ -71,9 +76,56 @@ const ACTIONS: Readonly<Record<string, string>> = {
   "/admin/stop-impersonating": "user.stop_impersonate",
 };
 
+interface AuditUser {
+  id: string;
+  name?: string | null;
+  email?: string | null;
+}
+
 interface SessionRecord {
-  session: { token: string };
-  user: { id: string; name?: string | null; email?: string | null };
+  session: { token: string; impersonatedBy?: string | null };
+  user: AuditUser;
+}
+
+// What the plugin's database hooks saw one request do. Better Auth copies its
+// context for every endpoint call and hands that copy, ctx.context, to the
+// endpoint, to the database hooks the endpoint triggers, and to its own hooks,
+// so the copy identifies the request.
+interface Observed {
+  /** The user /admin/create-user created. */
+  created?: AuditUser;
+  /** The user the request last updated, such as the one an email link verified. */
+  updated?: AuditUser;
+  /** The user whose password-reset link the request presented. */
+  resetUserId?: string;
+  /** The owners of the sessions the request ended, in order. */
+  endedSessions: string[];
+}
+
+const observations = new WeakMap<object, Observed>();
+
+function observe(context: object): Observed {
+  let observed = observations.get(context);
+  if (!observed) {
+    observed = { endedSessions: [] };
+    observations.set(context, observed);
+  }
+  return observed;
+}
+
+interface RequestShape {
+  path?: string;
+  params?: unknown;
+  body?: unknown;
+}
+
+// How a request signed someone in or up: the name in SIGN_IN_METHODS, otherwise
+// the endpoint's path, and the provider of a social sign-in.
+function methodOf({ path = "", params, body }: RequestShape): Record<string, string> {
+  const method = path === "/sign-up/email" ? "password" : (SIGN_IN_METHODS[path] ?? path);
+  if (method !== "social") return { method };
+  const provider = (params as { id?: string } | undefined)?.id ?? (body as { provider?: string } | undefined)?.provider;
+  return provider ? { method, provider } : { method };
 }
 
 interface SignInContext {
@@ -137,17 +189,87 @@ export interface AuditPluginOptions {
   enabled?: () => Promise<boolean>;
 }
 
+type DatabaseHooks = NonNullable<BetterAuthOptions["databaseHooks"]>;
+type HookContext = Parameters<NonNullable<NonNullable<NonNullable<DatabaseHooks["user"]>["create"]>["after"]>>[1];
+
+const who = (user: AuditUser | null | undefined): Pick<AuditEntry, "actorId" | "actorName" | "actorEmail"> => ({
+  actorId: user?.id ?? null,
+  actorName: user?.name ?? null,
+  actorEmail: user?.email ?? null,
+});
+
 // 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. 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.
+//
+// Its database hooks see what a request did to users and sessions, so entries
+// name the user even when the request carries no session: a new account is
+// recorded when it is stored, whichever endpoint creates it and even when the
+// request then fails (a social sign-up that waits for approval gets no
+// session), and a sign-out names the owner of the session it ended.
 export function auditPlugin(options: AuditPluginOptions = {}): BetterAuthPlugin & { id: "podokit-audit" } {
   const enabled = options.enabled ?? auditEnabled;
+
+  async function recordSignUp(user: AuditUser, context: HookContext): Promise<void> {
+    if (!(await enabled())) return;
+    if (context?.path === "/admin/create-user") {
+      // Recorded as user.create by the request's after hook.
+      observe(context.context).created = user;
+      return;
+    }
+    await recordAudit({
+      action: "auth.signup",
+      ...(context ? who(user) : {}),
+      targetId: user.id,
+      targetLabel: user.email ?? null,
+      ip: clientAddressOf(context?.headers) ?? null,
+      ...(context ? { metadata: methodOf(context) } : {}),
+    });
+  }
+
+  const databaseHooks: DatabaseHooks = {
+    user: {
+      create: { after: async (user, context) => recordSignUp(user, context) },
+      update: {
+        after: async (user, context) => {
+          if (context) observe(context.context).updated = user;
+        },
+      },
+    },
+    session: {
+      delete: {
+        // deleteWithHooks reads the row before it deletes it, so this costs no query.
+        before: async (session, context) => {
+          if (context) observe(context.context).endedSessions.push(session.userId);
+        },
+      },
+    },
+  };
+
   return {
     id: "podokit-audit",
+    init: () => ({ options: { databaseHooks } }),
     hooks: {
+      before: [
+        {
+          // The endpoint consumes the link's token, so find its user first.
+          matcher: (context) => context.path === "/reset-password",
+          handler: createAuthMiddleware(async (ctx) => {
+            const token =
+              (ctx.body as { token?: string } | undefined)?.token ?? (ctx.query as { token?: string } | undefined)?.token;
+            if (!token || !(await enabled())) return;
+            try {
+              const verification = await ctx.context.internalAdapter.findVerificationValue(`reset-password:${token}`);
+              if (verification?.value) observe(ctx.context).resetUserId = verification.value;
+            } catch {
+              // The entry then names no account; the reset itself goes ahead.
+            }
+          }),
+        },
+      ],
       after: [
         {
           matcher: (context) => Boolean(context.path),
@@ -162,48 +284,72 @@ export function auditPlugin(options: AuditPluginOptions = {}): BetterAuthPlugin
             // skips the lookups below when auditing is off.
             if (!(await enabled())) return;
             const ip = clientAddressOf(ctx.headers) ?? null;
+            const seen = observations.get(ctx.context);
+            // A failed lookup leaves the entry without that user; it never fails the request.
+            const quietly = async (find: () => Promise<AuditUser | null | undefined>): Promise<AuditUser | null> => {
+              try {
+                return (await find()) ?? null;
+              } catch {
+                return null;
+              }
+            };
+            const userById = async (id: string | null | undefined): Promise<AuditUser | null> =>
+              id ? quietly(() => ctx.context.internalAdapter.findUserById(id)) : null;
 
-            if (action) {
-              const actor = ctx.context.session?.user ?? ctx.context.newSession?.user;
-              const body = (ctx.body ?? {}) as { email?: string; userId?: string };
+            if (action === "auth.logout") {
+              // One entry per account whose session ended: multiSession() signs
+              // out every account of the browser. A sign-out without a session
+              // ends none and records nothing.
+              for (const id of new Set(seen?.endedSessions)) {
+                const user = (await userById(id)) ?? { id };
+                await recordAudit({ action, ...who(user), targetId: id, targetLabel: user.email ?? null, ip });
+              }
+            } else if (action) {
+              const session = ctx.context.session;
+              const body = (ctx.body ?? {}) as { email?: string; userId?: string; phoneNumber?: string };
+              let actor: AuditUser | null = session?.user ?? ctx.context.newSession?.user ?? null;
+              // The user the request acted on when its body does not name one.
+              let subject: AuditUser | null = null;
+              if (action === "user.create") subject = seen?.created ?? null;
+              else if (action === "user.session_revoke") subject = await userById(seen?.endedSessions[0]);
+              else if (action === "user.stop_impersonate" && session?.session.impersonatedBy) {
+                // The session is the impersonated user's; the administrator ends it.
+                subject = session.user;
+                actor = (await userById(session.session.impersonatedBy)) ?? actor;
+              } else if (action === "auth.email_verified") {
+                subject = seen?.updated ?? null;
+                actor ??= subject;
+              } else if (action === "auth.password_reset") {
+                // Whoever holds the link or code acts as the account's owner.
+                if (ctx.path === "/reset-password") subject = await userById(seen?.resetUserId);
+                else if (ctx.path === "/email-otp/reset-password" && body.email) {
+                  const email = body.email;
+                  subject = await quietly(async () => (await ctx.context.internalAdapter.findUserByEmail(email))?.user);
+                } else if (ctx.path === "/phone-number/reset-password" && body.phoneNumber) {
+                  const phoneNumber = body.phoneNumber;
+                  subject = await quietly(() =>
+                    ctx.context.adapter.findOne<AuditUser>({ model: "user", where: [{ field: "phoneNumber", value: phoneNumber }] }),
+                  );
+                }
+                actor ??= subject;
+              }
 
               // Prefer a human-readable target: the email in the body, otherwise
               // the target user's email by id (the id for already-deleted users).
-              const targetId = body.userId ?? null;
-              let targetLabel = body.email ?? null;
-              if (!targetLabel && targetId) {
-                try {
-                  const target = await ctx.context.internalAdapter.findUserById(targetId);
-                  targetLabel = target?.email ?? targetId;
-                } catch {
-                  targetLabel = targetId;
-                }
-              }
-              await recordAudit({
-                action,
-                actorId: actor?.id ?? null,
-                actorName: actor?.name ?? null,
-                actorEmail: actor?.email ?? null,
-                targetId,
-                targetLabel,
-                ip,
-              });
+              const targetId = body.userId ?? subject?.id ?? null;
+              let targetLabel = body.email ?? subject?.email ?? body.phoneNumber ?? null;
+              if (!targetLabel && targetId) targetLabel = (await userById(targetId))?.email ?? targetId;
+              await recordAudit({ action, ...who(actor), targetId, targetLabel, ip });
             }
 
             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: login.user.id,
-              actorName: login.user.name ?? null,
-              actorEmail: login.user.email ?? null,
+              ...who(login.user),
               targetId: login.user.id,
               targetLabel: login.user.email ?? null,
               ip,
-              metadata: provider ? { method, provider } : { method },
+              metadata: methodOf(ctx),
             });
           }),
         },

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

@@ -0,0 +1,232 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import { join } from "node:path";
+import { betterAuth } from "better-auth";
+import { memoryAdapter } from "better-auth/adapters/memory";
+import { getAuthTables } from "better-auth/db";
+import { admin, magicLink } from "better-auth/plugins";
+import { adminEmailProblem, adminEmailsFrom, becomesAdministrator } from "./admin-emails";
+import { databaseHooksFor } from "./auth";
+import { PUBLIC_SIGNUP_DISABLED } from "./feature-gate";
+
+const BASE_URL = "http://localhost:5002";
+const PASSWORD = "Podokit3e-Str0ng!pw";
+const ADMIN_EMAIL = "owner@podokit.dev";
+
+describe("ADMIN_EMAILS", () => {
+  test("keeps placeholders outside production and refuses them in production", () => {
+    expect([...adminEmailsFrom(" Admin@Example.com, ,ops@podokit.dev ", false)]).toEqual([
+      "admin@example.com",
+      "ops@podokit.dev",
+    ]);
+    expect([...adminEmailsFrom("owner@podokit.dev,ops@mail.podokit.dev", true)]).toHaveLength(2);
+    expect(adminEmailsFrom(undefined, true).size).toBe(0);
+    expect(adminEmailsFrom("", true).size).toBe(0);
+    for (const entry of [
+      "admin@example.com",
+      "a@mail.example.org",
+      "a@example.net",
+      "a@host.test",
+      "a@host.example",
+      "a@host.invalid",
+      "a@localhost",
+      "admin",
+      "a@b",
+    ]) {
+      expect(() => adminEmailsFrom(`owner@podokit.dev,${entry}`, true)).toThrow(`"${entry}"`);
+    }
+  });
+
+  test("stops a production API whose ADMIN_EMAILS holds a placeholder", () => {
+    const load = (adminEmails: string): { exitCode: number; stderr: string } => {
+      const result = Bun.spawnSync(
+        [process.execPath, "--eval", `await import(${JSON.stringify(join(__dirname, "auth.ts"))}); process.exit(0);`],
+        {
+          env: {
+            PATH: process.env.PATH ?? "",
+            NODE_ENV: "production",
+            ADMIN_EMAILS: adminEmails,
+            BETTER_AUTH_SECRET: "admin-emails-production-secret-0123456789",
+            BETTER_AUTH_URL: "https://app.podokit.dev",
+          },
+          stderr: "pipe",
+        },
+      );
+      return { exitCode: result.exitCode, stderr: result.stderr.toString() };
+    };
+    const placeholder = load("admin@example.com");
+    expect(placeholder.exitCode).not.toBe(0);
+    expect(placeholder.stderr).toContain('ADMIN_EMAILS must list real administrator addresses in production');
+    expect(load("owner@podokit.dev").exitCode).toBe(0);
+  });
+
+  test("names why an entry is no administrator's address", () => {
+    expect(adminEmailProblem("admin@example.com")).toBe("a placeholder on a reserved domain");
+    expect(adminEmailProblem("someone@example.company")).toBeNull();
+    expect(adminEmailProblem("admin")).toBe("not an email address");
+    expect(adminEmailProblem("owner@podokit.dev")).toBeNull();
+  });
+
+  test("promotes a listed address only once it is proven", () => {
+    const listed = new Set([ADMIN_EMAIL]);
+    expect(becomesAdministrator({ email: "Owner@Podokit.dev", emailVerified: true }, false, listed)).toBe(true);
+    expect(becomesAdministrator({ email: ADMIN_EMAIL, emailVerified: false }, true, listed)).toBe(true);
+    expect(becomesAdministrator({ email: "else@podokit.dev", emailVerified: false }, false, listed)).toBe(false);
+    expect(() => becomesAdministrator({ email: ADMIN_EMAIL, emailVerified: false }, false, listed)).toThrow(
+      "cannot be registered",
+    );
+  });
+});
+
+interface StartOptions {
+  requireSignupApproval?: boolean;
+  googleEmailVerified?: boolean;
+}
+
+// The account rules of the generated auth.ts on an in-memory database, with
+// sign-up open and ADMIN_EMAILS naming ADMIN_EMAIL.
+function startAuth({ requireSignupApproval = false, googleEmailVerified = true }: StartOptions = {}) {
+  const mail = { magicLink: "" };
+  const db: Record<string, Record<string, unknown>[]> = {};
+  const options = {
+    baseURL: BASE_URL,
+    secret: "admin-emails-test-secret-0123456789abcdef",
+    database: memoryAdapter(db),
+    emailAndPassword: { enabled: true, autoSignIn: !requireSignupApproval },
+    user: { additionalFields: { signupApproved: { type: "boolean" as const, required: false, defaultValue: true, input: false } } },
+    socialProviders: {
+      google: {
+        clientId: "client",
+        clientSecret: "secret",
+        getUserInfo: async () => ({
+          user: { email: ADMIN_EMAIL, name: "Owner", emailVerified: googleEmailVerified },
+          data: {
+            sub: "google-1",
+            email: ADMIN_EMAIL,
+            email_verified: googleEmailVerified,
+            name: "Owner",
+            given_name: "Owner",
+            family_name: "Podokit",
+            picture: "https://podokit.dev/owner.png",
+            aud: "client",
+            azp: "client",
+            iss: "https://accounts.google.com",
+            iat: 0,
+            exp: 0,
+          },
+        }),
+      },
+    },
+    plugins: [
+      magicLink({
+        sendMagicLink: async ({ url }) => {
+          mail.magicLink = url;
+        },
+      }),
+      admin(),
+    ],
+    databaseHooks: databaseHooksFor({ requireSignupApproval }, new Set([ADMIN_EMAIL]), async () => true),
+  };
+  for (const table of Object.values(getAuthTables(options))) db[table.modelName] = [];
+  const auth = betterAuth(options);
+  const users = (): Array<{ email: string; role?: string; signupApproved?: boolean; emailVerified?: boolean }> =>
+    (db.user ?? []) as Array<{ email: string; role?: string; signupApproved?: boolean; emailVerified?: boolean }>;
+  const request = (path: string, init: { method?: string; body?: unknown; cookie?: string } = {}): Promise<Response> =>
+    auth.handler(
+      new Request(path.startsWith("http") ? path : `${BASE_URL}/api/auth${path}`, {
+        method: init.method ?? (init.body === undefined ? "GET" : "POST"),
+        headers: {
+          origin: BASE_URL,
+          ...(init.body === undefined ? {} : { "content-type": "application/json" }),
+          ...(init.cookie ? { cookie: init.cookie } : {}),
+        },
+        body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        redirect: "manual",
+      }),
+    );
+  return { auth, mail, users, request };
+}
+
+const cookiesOf = (response: Response): string =>
+  response.headers
+    .getSetCookie()
+    .map((cookie) => cookie.split(";")[0])
+    .join("; ");
+
+// Signs in with Google, answering the provider's token request.
+async function googleSignIn(started: ReturnType<typeof startAuth>): Promise<Response> {
+  const realFetch = globalThis.fetch;
+  const tokenEndpoint = spyOn(globalThis, "fetch").mockImplementation(((input: RequestInfo | URL, init?: RequestInit) => {
+    const url = input instanceof Request ? input.url : String(input);
+    if (url.startsWith("https://oauth2.googleapis.com/token")) {
+      return Promise.resolve(Response.json({ access_token: "access", expires_in: 3600, token_type: "Bearer" }));
+    }
+    return realFetch(input, init);
+  }) as typeof fetch);
+  try {
+    const begin = await started.request("/sign-in/social", { body: { provider: "google", callbackURL: `${BASE_URL}/` } });
+    const state = new URL(((await begin.json()) as { url: string }).url).searchParams.get("state") ?? "";
+    return await started.request(`/callback/google?code=code&state=${encodeURIComponent(state)}`, {
+      cookie: cookiesOf(begin),
+    });
+  } finally {
+    tokenEndpoint.mockRestore();
+  }
+}
+
+describe("accounts with an ADMIN_EMAILS address", () => {
+  test("refuses an unverified email sign-up instead of making an administrator", async () => {
+    const open = startAuth();
+    const refused = await open.request("/sign-up/email", { body: { email: ADMIN_EMAIL, password: PASSWORD, name: "Claim" } });
+    expect(refused.status).toBe(403);
+    expect(((await refused.json()) as { code?: string }).code).toBe(PUBLIC_SIGNUP_DISABLED);
+    expect(open.users()).toEqual([]);
+
+    // With sign-up approval on, Better Auth answers a refused sign-up like any
+    // other, so the response does not reveal the address; still no account.
+    const pending = startAuth({ requireSignupApproval: true });
+    const hidden = await pending.request("/sign-up/email", { body: { email: ADMIN_EMAIL, password: PASSWORD, name: "Claim" } });
+    expect(hidden.status).toBe(200);
+    expect(pending.users()).toEqual([]);
+    const signIn = await pending.request("/sign-in/email", { body: { email: ADMIN_EMAIL, password: PASSWORD } });
+    expect(signIn.status).toBe(401);
+
+    // Other addresses sign up as before: pending under the approval policy.
+    expect((await pending.request("/sign-up/email", { body: { email: "member@podokit.dev", password: PASSWORD, name: "M" } })).status).toBe(200);
+    expect(pending.users()).toEqual([expect.objectContaining({ email: "member@podokit.dev", role: "user", signupApproved: false })]);
+  });
+
+  test("makes an approved administrator of a social sign-in with a verified address", async () => {
+    const started = startAuth({ requireSignupApproval: true });
+    const callback = await googleSignIn(started);
+    expect(callback.status).toBe(302);
+    expect(new URL(callback.headers.get("location") ?? "", BASE_URL).searchParams.get("error")).toBeNull();
+    expect(started.users()).toEqual([
+      expect.objectContaining({ email: ADMIN_EMAIL, role: "admin", signupApproved: true, emailVerified: true }),
+    ]);
+
+    const unverified = startAuth({ requireSignupApproval: true, googleEmailVerified: false });
+    const refused = await googleSignIn(unverified);
+    expect(refused.status).toBe(302);
+    expect(new URL(refused.headers.get("location") ?? "", BASE_URL).searchParams.get("error")).toBeTruthy();
+    expect(unverified.users()).toEqual([]);
+  });
+
+  test("makes an administrator of a magic link sign-in, which proves the address", async () => {
+    const started = startAuth({ requireSignupApproval: true });
+    await started.request("/sign-in/magic-link", { body: { email: ADMIN_EMAIL, callbackURL: `${BASE_URL}/` } });
+    expect((await started.request(started.mail.magicLink)).status).toBe(302);
+    expect(started.users()).toEqual([expect.objectContaining({ email: ADMIN_EMAIL, role: "admin", signupApproved: true })]);
+  });
+
+  test("creates the administrator that admin:bootstrap asks for", async () => {
+    const started = startAuth({ requireSignupApproval: true });
+    // scripts/bootstrap-admin.mjs creates the account through this call.
+    await started.auth.api.createUser({
+      body: { email: ADMIN_EMAIL, password: PASSWORD, name: "Administrator", role: "admin", data: { emailVerified: true, signupApproved: true } },
+    });
+    expect(started.users()).toEqual([
+      expect.objectContaining({ email: ADMIN_EMAIL, role: "admin", signupApproved: true, emailVerified: true }),
+    ]);
+    expect((await started.request("/sign-in/email", { body: { email: ADMIN_EMAIL, password: PASSWORD } })).status).toBe(200);
+  });
+});

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.",
+  });
+}