@podosoft/podokit 1.1.6 → 1.2.0

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

@@ -1,8 +1,10 @@
 import type { Capabilities } from "@podosoft/podokit-contracts";
 import { Elysia, t } from "elysia";
+import { EVENTS } from "@podosoft/podokit-runtime";
 import {
   ACCESS_POLICY,
   DATABASE,
+  LOGGER,
   OPENAPI,
   REQUEST_GUARDS,
   REQUEST_IDENTITY,
@@ -17,10 +19,11 @@ import {
 import { FEATURE_FLAGS, SettingsService, type FeatureFlag } from "../settings/settings.service";
 import { authConfigStore } from "./auth-config-store";
 import { getAuth, authRuntime, primeAuth } from "./auth-provider";
-import { generateAuthOpenApiDocument } from "./auth.openapi";
+import { cachedAuthOpenApiDocuments } from "./auth.openapi";
 import { ROLE_NAMES } from "./permissions";
-import { AuthService } from "./auth.service";
+import { AuthService, createRequestIdentity } from "./auth.service";
 import { configureAuthQueryDatabase } from "./db";
+import { configEvents, publishConfigChanged } from "./config-events";
 import { setMailConfigStore } from "../mail/mailer";
 
 export const AUTH = Symbol("auth") as ServiceKey<AuthService>;
@@ -69,12 +72,14 @@ const accountPlugin: AppPlugin = ({ services }) => {
     }, {
       detail: { tags: ["account"], summary: "Get the current account" },
     })
-    .get("/account/require-2fa", () => ({ require2fa: settings.getBool("require2fa") }), {
+    .get("/account/require-2fa", async () => ({ require2fa: await settings.getBool("require2fa") }), {
       detail: { tags: ["account"], summary: "Get the two-factor enrolment policy" },
     })
     .get("/account/capabilities", async (): Promise<Capabilities> => {
-      const flags = settings.flags();
-      const snapshot = await authConfigStore.capabilitiesSnapshot();
+      const [flags, snapshot] = await Promise.all([
+        settings.flags(),
+        authConfigStore.capabilitiesSnapshot(),
+      ]);
       return {
         twoFactor: flags.twoFactor,
         magicLink: flags.magicLink,
@@ -86,6 +91,7 @@ const accountPlugin: AppPlugin = ({ services }) => {
         passkey: flags.passkey,
         organization: flags.organization,
         oidcProvider: flags.oidcProvider,
+        require2fa: flags.require2fa,
         providers: snapshot.providers,
         deleteAccount: snapshot.allowDelete,
         emailVerification: snapshot.requireEmailVerification,
@@ -151,26 +157,35 @@ export const authModule: PodokitModule = {
     configureAuthQueryDatabase(database.sql);
     setMailConfigStore(authConfigStore);
     const accessPolicy = services.resolve(ACCESS_POLICY);
-    const settings = new SettingsService(database.sql);
+    const settings = new SettingsService(database.sql, authConfigStore, publishConfigChanged);
     const authService = new AuthService(settings, accessPolicy);
     services.register(SETTINGS, settings);
-    services.register(AUTH_CONFIG, new AuthConfigService(database.sql));
+    services.register(AUTH_CONFIG, new AuthConfigService(database.sql, database.provider));
     services.register(AUTH, authService, () => authService.close());
     services.onStart(async () => {
-      await settings.refresh();
       await primeAuth();
+      // Optional: with an events provider, other replicas' settings writes apply
+      // at once instead of at the next version probe.
+      const events = services.tryResolve(EVENTS);
+      if (!events) return;
+      try {
+        await configEvents.listen(events, () => authConfigStore.invalidate());
+      } catch (error) {
+        services.resolve(LOGGER).warn(
+          { reason: error instanceof Error ? error.message : String(error) },
+          "Settings change events are unavailable; replicas converge on the settings TTL",
+        );
+      }
     });
-    services.override(REQUEST_IDENTITY, {
-      userId: async (request) => (await authService.session(request))?.user.id,
-    });
+    services.override(REQUEST_IDENTITY, createRequestIdentity(authService));
     accessPolicy.register("*", "/api/auth", "public");
     accessPolicy.register("*", "/api/auth/*", "public");
     accessPolicy.register("GET", "/account/capabilities", "public");
+    const authOpenApiDocument = cachedAuthOpenApiDocuments();
     services.resolve(OPENAPI).register("better-auth", async () => {
       await primeAuth();
-      const document = await generateAuthOpenApiDocument(getAuth().api);
       return {
-        document,
+        document: await authOpenApiDocument(getAuth()),
         pathPrefix: "/api/auth",
       };
     });

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

@@ -1,5 +1,23 @@
-import { describe, expect, it } from "bun:test";
-import { generateAuthOpenApiDocument, isAuthOpenApiApi } from "./auth.openapi";
+import { describe, expect, it, mock, type Mock } from "bun:test";
+import {
+  cachedAuthOpenApiDocuments,
+  generateAuthOpenApiDocument,
+  isAuthOpenApiApi,
+} from "./auth.openapi";
+
+type GenerateSchema = () => Promise<Record<string, unknown>>;
+
+function authInstance(version: string): { api: { generateOpenAPISchema: Mock<GenerateSchema> } } {
+  return {
+    api: {
+      generateOpenAPISchema: mock<GenerateSchema>(async () => ({
+        openapi: "3.1.0",
+        info: { version },
+        paths: {},
+      })),
+    },
+  };
+}
 
 describe("Better Auth OpenAPI integration", () => {
   it("accepts the generated OpenAPI API without weakening the auth type", async () => {
@@ -17,4 +35,40 @@ describe("Better Auth OpenAPI integration", () => {
       "invalid OpenAPI document",
     );
   });
+
+  it("reuses the generated document for the same auth instance", async () => {
+    const documents = cachedAuthOpenApiDocuments();
+    const auth = authInstance("1");
+
+    const first = await documents(auth);
+    const second = await documents(auth);
+
+    expect(second).toBe(first);
+    expect(auth.api.generateOpenAPISchema).toHaveBeenCalledTimes(1);
+  });
+
+  it("generates a fresh document after the auth instance is rebuilt", async () => {
+    const documents = cachedAuthOpenApiDocuments();
+    const original = authInstance("1");
+    const rebuilt = authInstance("2");
+
+    const before = await documents(original);
+    const after = await documents(rebuilt);
+
+    expect(after).not.toBe(before);
+    expect(after).toMatchObject({ info: { version: "2" } });
+    expect(rebuilt.api.generateOpenAPISchema).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries after a rejected generation instead of caching the failure", async () => {
+    const documents = cachedAuthOpenApiDocuments();
+    const auth = authInstance("1");
+    auth.api.generateOpenAPISchema.mockImplementationOnce(async () => {
+      throw new Error("plugin endpoints unavailable");
+    });
+
+    await expect(documents(auth)).rejects.toThrow("plugin endpoints unavailable");
+    await expect(documents(auth)).resolves.toMatchObject({ openapi: "3.1.0" });
+    expect(auth.api.generateOpenAPISchema).toHaveBeenCalledTimes(2);
+  });
 });

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

@@ -20,3 +20,25 @@ export async function generateAuthOpenApiDocument(api: unknown): Promise<Record<
   }
   return document;
 }
+
+export interface AuthWithApi {
+  api: unknown;
+}
+
+export type AuthOpenApiDocuments = (auth: AuthWithApi) => Promise<Record<string, unknown>>;
+
+/** Generating the schema rebuilds every plugin's endpoints, so reuse it until the
+ *  auth instance is rebuilt. A rejected generation is dropped so the next call retries. */
+export function cachedAuthOpenApiDocuments(): AuthOpenApiDocuments {
+  const documents = new WeakMap<AuthWithApi, Promise<Record<string, unknown>>>();
+  return (auth) => {
+    const cached = documents.get(auth);
+    if (cached) return cached;
+    const document = generateAuthOpenApiDocument(auth.api);
+    documents.set(auth, document);
+    document.catch(() => {
+      if (documents.get(auth) === document) documents.delete(auth);
+    });
+    return document;
+  };
+}

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

@@ -1,14 +1,27 @@
-import { describe, expect, test } from "bun:test";
-import { AccessPolicy } from "../core/services";
+import { describe, expect, mock, test } from "bun:test";
+import { AccessPolicy, type RequestIdentity } from "../core/services";
 import type { SettingsService } from "../settings/settings.service";
-import { AuthService, rolesOf, type AuthSession } from "./auth.service";
+import {
+  AuthService,
+  createRequestIdentity,
+  rolesOf,
+  type AuthSession,
+  type SessionResolver,
+} from "./auth.service";
 
 function settings(require2fa: boolean): SettingsService {
   return { getBool: () => require2fa } as unknown as SettingsService;
 }
 
-function session(overrides: Partial<AuthSession["user"]> = {}): AuthSession {
-  return { user: { id: "user-1", ...overrides }, session: {} };
+function session(
+  overrides: Partial<AuthSession["user"]> = {},
+  sessionFields: Record<string, unknown> = {},
+): AuthSession {
+  return { user: { id: "user-1", ...overrides }, session: sessionFields };
+}
+
+function identityFor(resolver: SessionResolver): RequestIdentity {
+  return createRequestIdentity(new AuthService(settings(false), new AccessPolicy(), resolver));
 }
 
 describe("AuthService", () => {
@@ -50,3 +63,66 @@ describe("AuthService", () => {
       .rejects.toMatchObject({ code: "ADMIN_REQUIRED", statusCode: 403 });
   });
 });
+
+describe("createRequestIdentity", () => {
+  const request = (): Request => new Request("http://localhost/events");
+
+  test("treats a request without a session as anonymous", async () => {
+    const identity = identityFor(async () => null);
+    const anonymous = request();
+    expect(await identity.userId(anonymous)).toBeUndefined();
+    expect(await identity.isAdmin(anonymous)).toBe(false);
+    expect(await identity.roles(anonymous)).toEqual([]);
+    expect(await identity.activeOrganizationId(anonymous)).toBeUndefined();
+  });
+
+  test("reads every role from the comma-separated admin plugin format", async () => {
+    const identity = identityFor(async () => session({ role: "user,admin" }));
+    const signedIn = request();
+    expect(await identity.userId(signedIn)).toBe("user-1");
+    expect(await identity.roles(signedIn)).toEqual(["user", "admin"]);
+    expect(await identity.isAdmin(signedIn)).toBe(true);
+  });
+
+  test("reads roles stored as an array", async () => {
+    const identity = identityFor(async () => session({ role: ["moderator"] }));
+    const signedIn = request();
+    expect(await identity.roles(signedIn)).toEqual(["moderator"]);
+    expect(await identity.isAdmin(signedIn)).toBe(false);
+  });
+
+  test("returns no roles when the user has none", async () => {
+    const identity = identityFor(async () => session({ role: null }));
+    expect(await identity.roles(request())).toEqual([]);
+  });
+
+  test("reads the active organization from the session", async () => {
+    const active = identityFor(async () => session({}, { activeOrganizationId: "org-1" }));
+    expect(await active.activeOrganizationId(request())).toBe("org-1");
+
+    const cleared = identityFor(async () => session({}, { activeOrganizationId: null }));
+    expect(await cleared.activeOrganizationId(request())).toBeUndefined();
+
+    const missing = identityFor(async () => session());
+    expect(await missing.activeOrganizationId(request())).toBeUndefined();
+  });
+
+  test("resolves the session once per request across all questions", async () => {
+    const resolver = mock(async (_headers: Headers): Promise<AuthSession | null> =>
+      session({ role: "admin" }, { activeOrganizationId: "org-1" }));
+    const identity = identityFor(resolver);
+    const first = request();
+
+    await Promise.all([
+      identity.userId(first),
+      identity.isAdmin(first),
+      identity.roles(first),
+      identity.activeOrganizationId(first),
+    ]);
+    await identity.roles(first);
+    expect(resolver).toHaveBeenCalledTimes(1);
+
+    await identity.userId(request());
+    expect(resolver).toHaveBeenCalledTimes(2);
+  });
+});

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

@@ -1,5 +1,5 @@
 import { AppException } from "@podosoft/podokit-contracts";
-import type { AccessPolicy } from "../core/services";
+import type { AccessPolicy, RequestIdentity } from "../core/services";
 import type { SettingsService } from "../settings/settings.service";
 import { getAuth, refreshIfStale } from "./auth-provider";
 import { closeAuthDatabase } from "./db";
@@ -28,6 +28,11 @@ export function rolesOf(user: AuthUser): string[] {
   return (user.role ?? "").split(",").map((role) => role.trim()).filter(Boolean);
 }
 
+function activeOrganizationOf(session: AuthSession): string | undefined {
+  const value = session.session.activeOrganizationId;
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
 export class AuthService {
   private readonly sessions = new WeakMap<Request, Promise<AuthSession | null>>();
 
@@ -62,7 +67,7 @@ export class AuthService {
   async guard(request: Request): Promise<void> {
     if (this.accessPolicy.resolve(request) !== "session") return;
     const session = await this.requireSession(request);
-    if (!this.settings.getBool("require2fa") || session.user.twoFactorEnabled) return;
+    if (session.user.twoFactorEnabled || !(await this.settings.getBool("require2fa"))) return;
     const path = new URL(request.url).pathname;
     if (path === "/account/require-2fa" || path === "/account/settings") return;
     throw new AppException(
@@ -76,3 +81,22 @@ export class AuthService {
     await closeAuthDatabase();
   }
 }
+
+/** Answers identity questions for other modules from the one session lookup memoized per request. */
+export function createRequestIdentity(auth: AuthService): RequestIdentity {
+  return {
+    userId: async (request) => (await auth.session(request))?.user.id,
+    isAdmin: async (request) => {
+      const session = await auth.session(request);
+      return session !== null && rolesOf(session.user).includes("admin");
+    },
+    roles: async (request) => {
+      const session = await auth.session(request);
+      return session ? rolesOf(session.user) : [];
+    },
+    activeOrganizationId: async (request) => {
+      const session = await auth.session(request);
+      return session ? activeOrganizationOf(session) : undefined;
+    },
+  };
+}

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

@@ -3,9 +3,10 @@ import { APIError } from "better-auth/api";
 import { twoFactor, haveIBeenPwned, magicLink, emailOTP, username, multiSession, phoneNumber, organization, jwt, bearer, openAPI } from "better-auth/plugins";
 import { actionEmail, sendMail } from "../mail/mailer";
 import { sendSms } from "../sms/sms";
-import { assertUserCreationAllowed, createFeatureGate, createSignupOpenCheck } from "./feature-gate";
+import { assertUserCreationAllowed, createFeatureGate, readSignupOpen } from "./feature-gate";
+import { featureFlags, isSignupOpen } from "./auth-config-store";
 import { orgAc, orgRoles } from "./org-permissions";
-import { authDatabase, readAppSettings } from "./db";
+import { authDatabase } from "./db";
 import { type AuthConfig, envAuthConfig, sessionIdleOptions, SUPPORTED_PROVIDER_IDS } from "@podosoft/podokit-auth";
 import { apiKey } from "@better-auth/api-key";
 import { passkey } from "@better-auth/passkey";
@@ -47,7 +48,6 @@ function buildSocial(config: AuthConfig): NonNullable<BetterAuthOptions["socialP
 // server-enforced toggles) apply without a restart. Everything below the injection
 // markers is contributed by other PodoKit modules (admin-dashboard, audit-log).
 export function buildAuth(config: AuthConfig) {
-  const isSignupOpen = createSignupOpenCheck(readAppSettings);
   const plugins: BetterAuthPlugin[] = [
     twoFactor(),
     magicLink({
@@ -112,9 +112,14 @@ export function buildAuth(config: AuthConfig) {
     // Accept the session token via `Authorization: Bearer <token>` (returned in the
     // `set-auth-token` response header on sign-in) instead of a cookie — for API and
     // mobile clients. Infrastructure plugin (always on), like jwt(); no UI toggle.
-    bearer(),
+    // requireSignature ignores unsigned values, so API keys and OAuth access tokens
+    // sent as bearer credentials never cost a session lookup that cannot match.
+    bearer({ requireSignature: true }),
     // JWT/JWKS signing keys — required by the OAuth provider to sign id_tokens.
-    jwt(),
+    // Without disableSettingJwtHeader, every session lookup (including server-side
+    // getSession calls) signs an unused `set-auth-jwt` header. Clients that need a
+    // JWT call GET /api/auth/token.
+    jwt({ disableSettingJwtHeader: true }),
     // Act as an OAuth2/OIDC identity provider: other apps can "Sign in with this app".
     // Register clients at /api/auth/oauth2/create-client; discovery at
     // /api/auth/.well-known/openid-configuration. See docs/modules.md.
@@ -137,7 +142,7 @@ export function buildAuth(config: AuthConfig) {
         before: async (user, context) => {
           const adminEmail = adminEmails.has(user.email.toLowerCase());
           const createdByAdmin = context?.path === "/admin/create-user";
-          assertUserCreationAllowed(await isSignupOpen(), context?.path);
+          assertUserCreationAllowed(await readSignupOpen(isSignupOpen), context?.path);
           return {
             data: {
               ...user,
@@ -174,10 +179,11 @@ export function buildAuth(config: AuthConfig) {
   };
 
   // Request-time hooks. The feature gate turns the admin Settings toggles into a
-  // real server boundary (disabled features 404). Other PodoKit modules add their
-  // own hooks below the marker.
+  // real server boundary (disabled features 404). It reads the process-wide
+  // settings snapshot, so a rebuild does not start a new cache. Other PodoKit
+  // modules add their own hooks below the marker.
   const hooks: NonNullable<BetterAuthOptions["hooks"]> = {
-    before: createFeatureGate(readAppSettings, isSignupOpen),
+    before: createFeatureGate({ flags: featureFlags, signupOpen: isSignupOpen }),
   };
   // podokit:begin:auth-hooks
   // podokit:end:auth-hooks

package/dist/templates/modules/auth/files/apps/api/src/auth/config-events.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { MemoryEventBus, type EventBus } from "@podosoft/podokit-runtime";
+import { CONFIG_CHANGED_TOPIC, createConfigEvents } from "./config-events";
+
+describe("settings change events", () => {
+  test("invalidates other processes but not the publisher", async () => {
+    const bus = new MemoryEventBus();
+    const replicaA = createConfigEvents();
+    const replicaB = createConfigEvents();
+    let changesA = 0;
+    let changesB = 0;
+    await replicaA.listen(bus, () => { changesA += 1; });
+    await replicaB.listen(bus, () => { changesB += 1; });
+
+    await replicaA.publish();
+    await Bun.sleep(0);
+    expect(changesA).toBe(0);
+    expect(changesB).toBe(1);
+    await bus.close();
+  });
+
+  test("does nothing without an events provider and tolerates a failing one", async () => {
+    await expect(createConfigEvents().publish()).resolves.toBeUndefined();
+
+    const failing: EventBus = {
+      ready: async () => undefined,
+      publish: async () => {
+        throw new Error("redis unavailable");
+      },
+      subscribe: async () => () => undefined,
+      close: () => undefined,
+    };
+    const events = createConfigEvents();
+    await events.listen(failing, () => undefined);
+    await expect(events.publish()).resolves.toBeUndefined();
+    expect(CONFIG_CHANGED_TOPIC).toBe("config.changed");
+  });
+});

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

@@ -0,0 +1,43 @@
+import type { EventBus } from "@podosoft/podokit-runtime";
+
+export const CONFIG_CHANGED_TOPIC = "config.changed";
+
+export interface ConfigEvents {
+  /** Run `onChange` when another process reports a settings write. */
+  listen(events: EventBus, onChange: () => void): Promise<void>;
+  /** Report a local settings write. Without a listening bus this does nothing. */
+  publish(): Promise<void>;
+}
+
+function originOf(event: unknown): unknown {
+  return event !== null && typeof event === "object" ? (event as { origin?: unknown }).origin : undefined;
+}
+
+/** Cross-replica invalidation over the optional events provider. Delivery is
+ *  best effort: a lost message only delays convergence to the settings TTL. */
+export function createConfigEvents(): ConfigEvents {
+  const origin = crypto.randomUUID();
+  let bus: EventBus | undefined;
+  return {
+    async listen(events, onChange): Promise<void> {
+      await events.subscribe(CONFIG_CHANGED_TOPIC, (event) => {
+        if (originOf(event) !== origin) onChange();
+      });
+      bus = events;
+    },
+    async publish(): Promise<void> {
+      if (!bus) return;
+      try {
+        await bus.publish(CONFIG_CHANGED_TOPIC, { origin });
+      } catch (err) {
+        console.warn("[auth-config] could not publish a settings change; other replicas follow within the TTL:", err instanceof Error ? err.message : err);
+      }
+    },
+  };
+}
+
+export const configEvents = createConfigEvents();
+
+export function publishConfigChanged(): Promise<void> {
+  return configEvents.publish();
+}

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

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "bun:test";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { validateEnv } from "../config/env.validation";
+import { PROVIDERS } from "../config/providers";
+import { postgresPool } from "./db";
+
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+
+describe("auth database pool", () => {
+  it("applies the pool limits from the environment", () => {
+    if (databaseProvider() !== "postgres") {
+      expect(postgresPool).toBeNull();
+      return;
+    }
+    const env = validateEnv(process.env);
+    expect(postgresPool?.options).toMatchObject({
+      max: env.DB_AUTH_POOL_MAX,
+      connectionTimeoutMillis: env.DB_CONNECT_TIMEOUT_MS,
+      idleTimeoutMillis: env.DB_IDLE_TIMEOUT_MS,
+    });
+  });
+});

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

@@ -1,7 +1,7 @@
 import { Database as SqliteDatabase } from "bun:sqlite";
 import type { SQL } from "bun";
 import { Pool } from "pg";
-import type { AuthConfigRow } from "@podosoft/podokit-auth";
+import type { AuthConfigRow, ConfigVersions } from "@podosoft/podokit-auth";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { validateEnv } from "../config/env.validation";
 import { PROVIDERS } from "../config/providers";
@@ -15,7 +15,12 @@ function databaseProvider(): DatabaseProviderName {
 const provider = databaseProvider();
 
 export const postgresPool = provider === "postgres"
-  ? new Pool({ connectionString: url })
+  ? new Pool({
+      connectionString: url,
+      max: env.DB_AUTH_POOL_MAX,
+      connectionTimeoutMillis: env.DB_CONNECT_TIMEOUT_MS,
+      idleTimeoutMillis: env.DB_IDLE_TIMEOUT_MS,
+    })
   : null;
 
 export const sqliteDatabase = provider === "sqlite"
@@ -51,6 +56,30 @@ export async function readAuthConfig(): Promise<AuthConfigRow[]> {
   return rows.map((row) => ({ ...row, enabled: row.enabled === true || row.enabled === 1 }));
 }
 
+type VersionRow = {
+  authConfigCount: number | string | bigint;
+  authConfigUpdatedAt: string | null;
+  appSettingCount: number | string | bigint;
+  appSettingUpdatedAt: string | null;
+};
+
+/** One cheap statement that changes whenever either settings table changes. The
+ *  count catches deletes; the text cast keeps PostgreSQL's microsecond precision. */
+export async function readConfigVersions(): Promise<ConfigVersions> {
+  const sql = queries();
+  const [row] = await sql<VersionRow[]>`
+    SELECT
+      (SELECT count(*) FROM "auth_config") AS "authConfigCount",
+      (SELECT CAST(max("updatedAt") AS TEXT) FROM "auth_config") AS "authConfigUpdatedAt",
+      (SELECT count(*) FROM "app_setting") AS "appSettingCount",
+      (SELECT CAST(max("updatedAt") AS TEXT) FROM "app_setting") AS "appSettingUpdatedAt"
+  `;
+  return {
+    authConfig: `${String(row?.authConfigCount ?? 0)}:${row?.authConfigUpdatedAt ?? ""}`,
+    appSettings: `${String(row?.appSettingCount ?? 0)}:${row?.appSettingUpdatedAt ?? ""}`,
+  };
+}
+
 export async function closeAuthDatabase(): Promise<void> {
   if (postgresPool) await postgresPool.end();
   sqliteDatabase?.close();

package/dist/templates/modules/auth/files/apps/api/src/auth/feature-gate.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { FLAG_DEFAULTS, flagsFrom } from "../settings/flag-defaults";
+import {
+  enforceFeatureGate,
+  PUBLIC_SIGNUP_DISABLED,
+  signupOpenFrom,
+  type FeatureFlags,
+  type FeatureGateSettings,
+} from "./feature-gate";
+
+function settings(flags: Partial<FeatureFlags>, signupOpen = true): FeatureGateSettings {
+  return {
+    flags: async () => ({ ...FLAG_DEFAULTS, ...flags }),
+    signupOpen: async () => signupOpen,
+  };
+}
+
+const failing: FeatureGateSettings = {
+  flags: async () => {
+    throw new Error('relation "app_setting" does not exist');
+  },
+  signupOpen: async () => {
+    throw new Error('relation "app_setting" does not exist');
+  },
+};
+
+describe("feature gate", () => {
+  test("rejects a disabled feature's endpoints with 404", async () => {
+    await expect(enforceFeatureGate("/sign-in/magic-link", settings({ magicLink: false })))
+      .rejects.toMatchObject({ statusCode: 404 });
+    await expect(enforceFeatureGate("/sign-in/magic-link", settings({ magicLink: true })))
+      .resolves.toBeUndefined();
+    await expect(enforceFeatureGate("/get-session", settings({ magicLink: false })))
+      .resolves.toBeUndefined();
+  });
+
+  test("closes public sign-up without blocking other paths", async () => {
+    await expect(enforceFeatureGate("/sign-up/email", settings({}, false)))
+      .rejects.toMatchObject({ body: { code: PUBLIC_SIGNUP_DISABLED } });
+    await expect(enforceFeatureGate("/sign-in/social", settings({}, false)))
+      .resolves.toBeUndefined();
+  });
+
+  test("fails open to defaults when the settings cannot be read", async () => {
+    await expect(enforceFeatureGate("/sign-up/email", failing)).resolves.toBeUndefined();
+    await expect(enforceFeatureGate("/sign-in/magic-link", failing)).resolves.toBeUndefined();
+    await expect(enforceFeatureGate("/phone-number/send-otp", failing))
+      .rejects.toMatchObject({ statusCode: 404 });
+  });
+
+  test("projects stored settings over the shipped defaults", () => {
+    const stored = new Map([["magicLink", "false"], ["phoneNumber", "true"], ["site.allowSignup", "false"]]);
+    expect(flagsFrom(stored)).toMatchObject({ magicLink: false, phoneNumber: true, twoFactor: true });
+    expect(flagsFrom(new Map())).toEqual(FLAG_DEFAULTS);
+    expect(signupOpenFrom(stored)).toBe(false);
+    expect(signupOpenFrom(new Map())).toBe(true);
+  });
+});