@podosoft/podokit 1.1.6 → 1.3.0

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

@@ -18,29 +18,35 @@ const FEATURE_PATHS: Array<{ flag: FeatureFlag; prefixes: string[] }> = [
   { flag: "oidcProvider", prefixes: ["/oauth2/", "/.well-known/openid-configuration", "/.well-known/oauth-authorization-server", "/.well-known/oauth-protected-resource"] },
 ];
 
-const CACHE_TTL_MS = 3_000;
+export type FeatureFlags = Record<FeatureFlag, boolean>;
 
-export type SignupOpenCheck = () => Promise<boolean>;
-export type AppSettingsReader = () => Promise<Array<{ key: string; value: string }>>;
+/** Live settings the gate reads per request, normally the shared settings snapshot. */
+export interface FeatureGateSettings {
+  flags: () => Promise<FeatureFlags>;
+  signupOpen: () => Promise<boolean>;
+}
+
+/** Public registration is the default until an administrator explicitly closes it. */
+export function signupOpenFrom(settings: ReadonlyMap<string, string>): boolean {
+  return settings.get("site.allowSignup") !== "false";
+}
 
-/** Public registration is the default until an administrator explicitly closes
- *  it. The short cache keeps every auth flow on the same live site-setting
- *  policy without rebuilding the Better Auth instance. */
-export function createSignupOpenCheck(readSettings: AppSettingsReader): SignupOpenCheck {
-  let signupOpen = true;
-  let fetchedAt = 0;
+/** A settings read failure keeps public sign-up open. */
+export async function readSignupOpen(signupOpen: () => Promise<boolean>): Promise<boolean> {
+  try {
+    return await signupOpen();
+  } catch {
+    return true;
+  }
+}
 
-  return async (): Promise<boolean> => {
-    if (Date.now() - fetchedAt < CACHE_TTL_MS) return signupOpen;
-    try {
-      const rows = await readSettings();
-      signupOpen = rows.find((row) => row.key === "site.allowSignup")?.value !== "false";
-    } catch {
-      signupOpen = true;
-    }
-    fetchedAt = Date.now();
-    return signupOpen;
-  };
+/** A settings read failure applies the shipped defaults. */
+export async function readFeatureFlags(flags: () => Promise<FeatureFlags>): Promise<FeatureFlags> {
+  try {
+    return await flags();
+  } catch {
+    return { ...FLAG_DEFAULTS };
+  }
 }
 
 /** Administrator-created users are intentional and remain available when the
@@ -60,45 +66,28 @@ export function assertUserCreationAllowed(signupOpen: boolean, requestPath?: str
 
 /** Server-side enforcement for the admin Settings toggles: requests to a disabled
  *  feature's endpoints are rejected with 404, so "off" is a real boundary rather
- *  than hidden UI. Flags are read from app_setting through a small TTL cache
- *  (a toggle takes effect within ~CACHE_TTL_MS); before the migration has run,
- *  the shipped defaults apply. */
-export function createFeatureGate(
-  readSettings: AppSettingsReader,
-  isSignupOpen: SignupOpenCheck = createSignupOpenCheck(readSettings),
-) {
-  let cache: Record<FeatureFlag, boolean> = { ...FLAG_DEFAULTS };
-  let fetchedAt = 0;
-
-  async function flags(): Promise<Record<FeatureFlag, boolean>> {
-    if (Date.now() - fetchedAt < CACHE_TTL_MS) return cache;
-    try {
-      const rows = await readSettings();
-      const next = { ...FLAG_DEFAULTS };
-      for (const row of rows) {
-        if (row.key in FLAG_DEFAULTS) next[row.key as FeatureFlag] = row.value === "true";
-      }
-      cache = next;
-    } catch {
-      cache = { ...FLAG_DEFAULTS };
-    }
-    fetchedAt = Date.now();
-    return cache;
+ *  than hidden UI. Throws the API error for a rejected path. */
+export async function enforceFeatureGate(path: string, settings: FeatureGateSettings): Promise<void> {
+  // Reject explicit sign-up endpoints early. OAuth starts remain available so
+  // existing social users can sign in; their new-user callback is enforced by
+  // the database hook that uses this same policy.
+  if (path === "/sign-up/email" || path.startsWith("/sign-up/")) {
+    assertUserCreationAllowed(await readSignupOpen(settings.signupOpen), path);
+    return;
   }
+  const feature = FEATURE_PATHS.find((f) =>
+    f.prefixes.some((p) => path === p || path.startsWith(p)),
+  );
+  if (!feature) return;
+  const enabled = (await readFeatureFlags(settings.flags))[feature.flag];
+  if (!enabled) throw new APIError("NOT_FOUND", { message: "This feature is disabled." });
+}
 
+/** Better Auth middleware over {@link enforceFeatureGate}. The settings come from
+ *  the shared snapshot (a toggle takes effect within its TTL); before the
+ *  migration has run, the shipped defaults apply. */
+export function createFeatureGate(settings: FeatureGateSettings): ReturnType<typeof createAuthMiddleware> {
   return createAuthMiddleware(async (ctx) => {
-    // Reject explicit sign-up endpoints early. OAuth starts remain available so
-    // existing social users can sign in; their new-user callback is enforced by
-    // the database hook that uses this same policy.
-    if (ctx.path === "/sign-up/email" || ctx.path.startsWith("/sign-up/")) {
-      assertUserCreationAllowed(await isSignupOpen(), ctx.path);
-      return;
-    }
-    const feature = FEATURE_PATHS.find((f) =>
-      f.prefixes.some((p) => ctx.path === p || ctx.path.startsWith(p)),
-    );
-    if (!feature) return;
-    const enabled = (await flags())[feature.flag];
-    if (!enabled) throw new APIError("NOT_FOUND", { message: "This feature is disabled." });
+    await enforceFeatureGate(ctx.path, settings);
   });
 }

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

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import type { QueryRunner } from "typeorm";
+import { InitAuthConfig1720500000000 } from "../migrations/1720500000000-InitAuthConfig";
+import { readAuthConfigRow, readAuthConfigRows, writeAuthConfigRow } from "./auth-config.rows";
+
+let open: SQL | undefined;
+
+afterEach(async () => {
+  await open?.close();
+  open = undefined;
+});
+
+async function sqliteDatabase(): Promise<SQL> {
+  const sql = new SQL(":memory:");
+  open = sql;
+  const runner = {
+    connection: { options: { type: "better-sqlite3" } },
+    query: (query: string): Promise<unknown> => sql.unsafe(query),
+  } as unknown as QueryRunner;
+  await new InitAuthConfig1720500000000().up(runner);
+  return sql;
+}
+
+describe("auth config rows on SQLite", () => {
+  it("reads the integer enabled column back as a boolean", async () => {
+    const sql = await sqliteDatabase();
+    await writeAuthConfigRow(sql, "sqlite", { key: "smtp", enabled: true, config: { host: "mail" }, secret: null });
+    await writeAuthConfigRow(sql, "sqlite", { key: "social.github", enabled: false, config: {}, secret: null });
+
+    expect(await readAuthConfigRow(sql, "smtp")).toEqual({
+      key: "smtp",
+      enabled: true,
+      config: JSON.stringify({ host: "mail" }),
+      secret: null,
+    });
+    const rows = await readAuthConfigRows(sql);
+    expect(rows.map((row) => [row.key, row.enabled])).toEqual([
+      ["smtp", true],
+      ["social.github", false],
+    ]);
+    expect(await readAuthConfigRow(sql, "server")).toBeNull();
+  });
+
+  it("keeps a boolean through a read and rewrite", async () => {
+    const sql = await sqliteDatabase();
+    await writeAuthConfigRow(sql, "sqlite", { key: "smtp", enabled: true, config: {}, secret: null });
+    const current = await readAuthConfigRow(sql, "smtp");
+    if (!current) throw new Error("expected the smtp row");
+    await writeAuthConfigRow(sql, "sqlite", { ...current, secret: "sealed" });
+    expect((await readAuthConfigRow(sql, "smtp"))?.enabled).toBe(true);
+  });
+});

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

@@ -0,0 +1,65 @@
+import type { SQL } from "bun";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { authConfigParam } from "./config-param";
+
+export interface AuthConfigRow {
+  key: string;
+  enabled: boolean;
+  config: unknown;
+  secret: string | null;
+}
+
+function configObject(value: unknown): Record<string, unknown> {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value === "string") {
+    try {
+      return configObject(JSON.parse(value) as unknown);
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+// SQLite stores booleans as 0 or 1.
+interface StoredAuthConfigRow extends Omit<AuthConfigRow, "enabled"> {
+  enabled: boolean | number;
+}
+
+function authConfigRow(row: StoredAuthConfigRow): AuthConfigRow {
+  return { ...row, enabled: row.enabled === true || row.enabled === 1 };
+}
+
+export async function readAuthConfigRows(sql: SQL): Promise<AuthConfigRow[]> {
+  const rows = await sql<StoredAuthConfigRow[]>`
+    SELECT "key", "enabled", "config", "secret" FROM "auth_config"
+  `;
+  return rows.map(authConfigRow);
+}
+
+export async function readAuthConfigRow(sql: SQL, key: string): Promise<AuthConfigRow | null> {
+  const rows = await sql<StoredAuthConfigRow[]>`
+    SELECT "key", "enabled", "config", "secret"
+    FROM "auth_config" WHERE "key" = ${key}
+  `;
+  return rows[0] ? authConfigRow(rows[0]) : null;
+}
+
+export async function writeAuthConfigRow(
+  sql: SQL,
+  provider: DatabaseProviderName,
+  row: AuthConfigRow,
+): Promise<void> {
+  const config = authConfigParam(provider, configObject(row.config));
+  await sql`
+    INSERT INTO "auth_config" ("key", "enabled", "config", "secret", "updatedAt")
+    VALUES (${row.key}, ${row.enabled}, ${config}, ${row.secret}, CURRENT_TIMESTAMP)
+    ON CONFLICT ("key") DO UPDATE SET
+      "enabled" = EXCLUDED."enabled",
+      "config" = EXCLUDED."config",
+      "secret" = EXCLUDED."secret",
+      "updatedAt" = CURRENT_TIMESTAMP
+  `;
+}

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

@@ -10,7 +10,15 @@ import {
   SUPPORTED_PROVIDER_IDS,
   SUPPORTED_SOCIAL_PROVIDERS,
 } from "@podosoft/podokit-auth";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { refreshAuthNow } from "../auth/auth-provider";
+import {
+  readAuthConfigRow,
+  readAuthConfigRows,
+  writeAuthConfigRow,
+  type AuthConfigRow,
+} from "./auth-config.rows";
+import { resetSessionExpirations } from "./session-expiry";
 
 export type SocialProviderView = {
   id: string;
@@ -71,13 +79,6 @@ export type AuthConfigUpdate = {
   };
 };
 
-interface AuthConfigRow {
-  key: string;
-  enabled: boolean;
-  config: unknown;
-  secret: string | null;
-}
-
 function object(value: unknown): Record<string, unknown> {
   if (value !== null && typeof value === "object" && !Array.isArray(value)) {
     return value as Record<string, unknown>;
@@ -102,33 +103,21 @@ function booleanField(source: Record<string, unknown>, key: string, fallback: bo
 }
 
 export class AuthConfigService {
-  constructor(private readonly sql: SQL) {}
+  constructor(
+    private readonly sql: SQL,
+    private readonly provider: DatabaseProviderName = "postgres",
+  ) {}
 
   private async rows(): Promise<AuthConfigRow[]> {
-    return this.sql<AuthConfigRow[]>`
-      SELECT "key", "enabled", "config", "secret" FROM "auth_config"
-    `;
+    return readAuthConfigRows(this.sql);
   }
 
   private async row(key: string): Promise<AuthConfigRow | null> {
-    const rows = await this.sql<AuthConfigRow[]>`
-      SELECT "key", "enabled", "config", "secret"
-      FROM "auth_config" WHERE "key" = ${key}
-    `;
-    return rows[0] ?? null;
+    return readAuthConfigRow(this.sql, key);
   }
 
   private async upsert(row: AuthConfigRow): Promise<void> {
-    const config = object(row.config);
-    await this.sql`
-      INSERT INTO "auth_config" ("key", "enabled", "config", "secret", "updatedAt")
-      VALUES (${row.key}, ${row.enabled}, ${config}, ${row.secret}, CURRENT_TIMESTAMP)
-      ON CONFLICT ("key") DO UPDATE SET
-        "enabled" = EXCLUDED."enabled",
-        "config" = EXCLUDED."config",
-        "secret" = EXCLUDED."secret",
-        "updatedAt" = CURRENT_TIMESTAMP
-    `;
+    await writeAuthConfigRow(this.sql, this.provider, row);
   }
 
   async describe(): Promise<AuthConfigView> {
@@ -211,7 +200,12 @@ export class AuthConfigService {
     if (update.server) await this.upsertServer(update.server);
     await refreshAuthNow();
     if (update.server?.sessionIdleTimeoutMinutes !== undefined) {
-      await this.resetSessionExpirations(update.server.sessionIdleTimeoutMinutes);
+      const minutes = update.server.sessionIdleTimeoutMinutes;
+      await resetSessionExpirations(
+        this.sql,
+        this.provider,
+        minutes === null ? DEFAULT_SESSION_LIFETIME_SECONDS : minutes * 60,
+      );
     }
     return this.describe();
   }
@@ -280,14 +274,4 @@ export class AuthConfigService {
     }
     await this.upsert({ ...current, config });
   }
-
-  private async resetSessionExpirations(minutes: number | null): Promise<void> {
-    const lifetimeSeconds = minutes === null ? DEFAULT_SESSION_LIFETIME_SECONDS : minutes * 60;
-    await this.sql`
-      UPDATE "session"
-      SET "expiresAt" = CURRENT_TIMESTAMP + (${lifetimeSeconds} * INTERVAL '1 second'),
-          "updatedAt" = CURRENT_TIMESTAMP
-      WHERE "expiresAt" > CURRENT_TIMESTAMP
-    `;
-  }
 }

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

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import { authConfigParam } from "./config-param";
+
+describe("auth config parameters", () => {
+  it("binds JSON text that SQLite stores and reads back", async () => {
+    const sql = new SQL("sqlite://:memory:");
+    await sql`CREATE TABLE "auth_config" ("key" text PRIMARY KEY, "config" text NOT NULL DEFAULT '{}')`;
+    const config = { allowDelete: true, hibp: true };
+
+    await sql`INSERT INTO "auth_config" ("key", "config") VALUES (${"server"}, ${authConfigParam("sqlite", config)})`;
+
+    const [row] = await sql<Array<{ config: unknown }>>`SELECT "config" FROM "auth_config"`;
+    expect(typeof row?.config).toBe("string");
+    expect(JSON.parse(String(row?.config))).toEqual(config);
+    await sql.close();
+  });
+
+  it("keeps an object for PostgreSQL jsonb", () => {
+    const config = { clientId: "id" };
+    expect(authConfigParam("postgres", config)).toBe(config);
+  });
+});

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

@@ -0,0 +1,10 @@
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+
+// PostgreSQL stores a jsonb object only when bound as an object (P-022), while
+// SQLite keeps the column as text and rejects object parameters.
+export function authConfigParam(
+  provider: DatabaseProviderName,
+  config: Record<string, unknown>,
+): Record<string, unknown> | string {
+  return provider === "sqlite" ? JSON.stringify(config) : config;
+}

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

@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import { resetSessionExpirations } from "./session-expiry";
+
+let open: SQL | undefined;
+
+afterEach(async () => {
+  await open?.close();
+  open = undefined;
+});
+
+describe("session expiry reset on SQLite", () => {
+  it("moves active sessions to the new lifetime and leaves expired ones", async () => {
+    const sql = new SQL(":memory:");
+    open = sql;
+    // Better Auth stores SQLite dates as ISO 8601 text.
+    await sql`CREATE TABLE "session" ("id" text PRIMARY KEY, "expiresAt" date NOT NULL, "updatedAt" date NOT NULL)`;
+    const now = new Date("2026-10-15T10:00:00.000Z");
+    const active = new Date(now.getTime() + 3_600_000).toISOString();
+    const expired = new Date(now.getTime() - 1_000).toISOString();
+    await sql`INSERT INTO "session" VALUES (${"active"}, ${active}, ${active}), (${"expired"}, ${expired}, ${expired})`;
+
+    await resetSessionExpirations(sql, "sqlite", 1_800, now);
+
+    const rows = await sql<Array<{ id: string; expiresAt: string; updatedAt: string }>>`
+      SELECT "id", "expiresAt", "updatedAt" FROM "session" ORDER BY "id"
+    `;
+    expect(rows).toEqual([
+      { id: "active", expiresAt: "2026-10-15T10:30:00.000Z", updatedAt: now.toISOString() },
+      { id: "expired", expiresAt: expired, updatedAt: expired },
+    ]);
+  });
+});

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

@@ -0,0 +1,29 @@
+import type { SQL } from "bun";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+
+/** Give every active session the configured lifetime from now. */
+export async function resetSessionExpirations(
+  sql: SQL,
+  provider: DatabaseProviderName,
+  lifetimeSeconds: number,
+  now: Date = new Date(),
+): Promise<void> {
+  if (provider === "sqlite") {
+    // Better Auth stores SQLite dates as ISO 8601 text, which sorts in time
+    // order. SQLite has no interval arithmetic.
+    const current = now.toISOString();
+    const expiresAt = new Date(now.getTime() + lifetimeSeconds * 1000).toISOString();
+    await sql`
+      UPDATE "session"
+      SET "expiresAt" = ${expiresAt}, "updatedAt" = ${current}
+      WHERE "expiresAt" > ${current}
+    `;
+    return;
+  }
+  await sql`
+    UPDATE "session"
+    SET "expiresAt" = CURRENT_TIMESTAMP + (${lifetimeSeconds} * INTERVAL '1 second'),
+        "updatedAt" = CURRENT_TIMESTAMP
+    WHERE "expiresAt" > CURRENT_TIMESTAMP
+  `;
+}

package/dist/templates/modules/auth/files/apps/api/src/settings/flag-defaults.ts

@@ -27,3 +27,13 @@ export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
 };
 
 export const FEATURE_FLAGS = Object.keys(FLAG_DEFAULTS) as FeatureFlag[];
+
+/** Stored values override the shipped defaults; a missing row keeps the default. */
+export function flagsFrom(settings: ReadonlyMap<string, string>): Record<FeatureFlag, boolean> {
+  const flags = { ...FLAG_DEFAULTS };
+  for (const flag of FEATURE_FLAGS) {
+    const stored = settings.get(flag);
+    if (stored !== undefined) flags[flag] = stored === "true";
+  }
+  return flags;
+}

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

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, setSystemTime, test } from "bun:test";
+import type { SQL } from "bun";
+import { createConfigStore, type AppSettingRow, type ConfigVersions } from "@podosoft/podokit-auth";
+import { SettingsService } from "./settings.service";
+
+type Row = AppSettingRow & { updatedAt: number };
+
+/** In-memory app_setting table with the same upsert semantics as the service's SQL. */
+function table() {
+  const rows = new Map<string, Row>();
+  let clock = 1;
+  const sql = (async (_strings: TemplateStringsArray, ...values: unknown[]) => {
+    const [key, value] = values as [string, string];
+    rows.set(key, { key, value, updatedAt: clock++ });
+    return [];
+  }) as unknown as SQL;
+  const store = () => createConfigStore({
+    list: async () => [],
+    listSettings: async () => [...rows.values()].map(({ key, value }) => ({ key, value })),
+    versions: async (): Promise<ConfigVersions> => ({
+      authConfig: "0:",
+      appSettings: `${rows.size}:${Math.max(0, ...[...rows.values()].map((row) => row.updatedAt))}`,
+    }),
+  });
+  return { rows, sql, store };
+}
+
+describe("SettingsService", () => {
+  let now = Date.UTC(2026, 0, 1);
+  beforeEach(() => {
+    now = Date.UTC(2026, 0, 1);
+    setSystemTime(new Date(now));
+  });
+  afterEach(() => {
+    setSystemTime();
+  });
+
+  test("applies a local write at once and reports the change", async () => {
+    const { sql, store } = table();
+    let changes = 0;
+    const settings = new SettingsService(sql, store(), async () => {
+      changes += 1;
+    });
+    expect(await settings.getBool("require2fa")).toBe(false);
+    const flags = await settings.setMany({ require2fa: true });
+    expect(flags.require2fa).toBe(true);
+    expect(await settings.getBool("require2fa")).toBe(true);
+    expect(changes).toBe(1);
+  });
+
+  test("follows another replica's write within the snapshot TTL", async () => {
+    const { sql, store } = table();
+    const replicaA = new SettingsService(sql, store());
+    const replicaB = new SettingsService(sql, store());
+    expect(await replicaB.getBool("require2fa")).toBe(false);
+
+    await replicaA.setMany({ require2fa: true });
+    expect(await replicaB.getBool("require2fa")).toBe(false);
+    setSystemTime(new Date(now + 3_100));
+    expect(await replicaB.getBool("require2fa")).toBe(true);
+    expect((await replicaB.flags()).require2fa).toBe(true);
+  });
+
+  test("falls back to the shipped defaults when app_setting is unavailable", async () => {
+    const settings = new SettingsService(table().sql, createConfigStore({
+      list: async () => [],
+      listSettings: async () => [],
+      versions: async () => {
+        throw new Error('relation "app_setting" does not exist');
+      },
+    }));
+    expect(await settings.flags()).toMatchObject({ twoFactor: true, phoneNumber: false, require2fa: false });
+  });
+
+  test("returns a copy of the flags", async () => {
+    const { sql, store } = table();
+    const settings = new SettingsService(sql, store());
+    (await settings.flags()).require2fa = true;
+    expect(await settings.getBool("require2fa")).toBe(false);
+  });
+});

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

@@ -1,53 +1,56 @@
 import type { SQL } from "bun";
-import { FLAG_DEFAULTS, FEATURE_FLAGS, type FeatureFlag } from "./flag-defaults";
+import type { ConfigStore } from "@podosoft/podokit-auth";
+import { FEATURE_FLAGS, flagsFrom, type FeatureFlag } from "./flag-defaults";
 
 export { FEATURE_FLAGS, type FeatureFlag };
 
-interface AppSettingRow {
-  key: string;
-  value: string;
-}
+export type SettingsSnapshot = Pick<ConfigStore, "selectSettings" | "invalidate">;
 
-/** DB-backed feature flags with migration defaults as the source of truth. */
+/** DB-backed feature flags with migration defaults as the source of truth. Reads
+ *  come from the shared settings snapshot, so every replica follows a change
+ *  within the snapshot TTL; a write here applies on this replica at once. */
 export class SettingsService {
-  private cache = new Map<string, string>();
-
-  constructor(private readonly sql: SQL) {}
+  private readonly current: () => Promise<Record<FeatureFlag, boolean>>;
+
+  constructor(
+    private readonly sql: SQL,
+    private readonly snapshot: SettingsSnapshot,
+    private readonly onChange: () => Promise<void> = async () => undefined,
+  ) {
+    this.current = snapshot.selectSettings(flagsFrom);
+  }
 
+  /** Reload the snapshot from the database. */
   async refresh(): Promise<void> {
-    try {
-      const rows = await this.sql<AppSettingRow[]>`
-        SELECT "key", "value" FROM "app_setting"
-      `;
-      this.cache = new Map(rows.map((row) => [row.key, row.value]));
-    } catch {
-      this.cache = new Map();
-    }
+    this.snapshot.invalidate();
+    await this.current();
   }
 
-  getBool(flag: FeatureFlag): boolean {
-    const stored = this.cache.get(flag);
-    return stored === undefined ? FLAG_DEFAULTS[flag] : stored === "true";
+  async getBool(flag: FeatureFlag): Promise<boolean> {
+    return (await this.current())[flag];
   }
 
-  flags(): Record<FeatureFlag, boolean> {
-    return Object.fromEntries(
-      FEATURE_FLAGS.map((flag) => [flag, this.getBool(flag)]),
-    ) as Record<FeatureFlag, boolean>;
+  async flags(): Promise<Record<FeatureFlag, boolean>> {
+    return { ...(await this.current()) };
   }
 
   async setMany(update: Partial<Record<FeatureFlag, boolean>>): Promise<Record<FeatureFlag, boolean>> {
-    for (const flag of FEATURE_FLAGS) {
-      const value = update[flag];
-      if (typeof value !== "boolean") continue;
-      await this.sql`
-        INSERT INTO "app_setting" ("key", "value", "updatedAt")
-        VALUES (${flag}, ${String(value)}, CURRENT_TIMESTAMP)
-        ON CONFLICT ("key") DO UPDATE
-        SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
-      `;
+    try {
+      for (const flag of FEATURE_FLAGS) {
+        const value = update[flag];
+        if (typeof value !== "boolean") continue;
+        await this.sql`
+          INSERT INTO "app_setting" ("key", "value", "updatedAt")
+          VALUES (${flag}, ${String(value)}, CURRENT_TIMESTAMP)
+          ON CONFLICT ("key") DO UPDATE
+          SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
+        `;
+      }
+    } finally {
+      // Also after a failure: earlier rows of the update may have been written.
+      await this.refresh();
     }
-    await this.refresh();
+    await this.onChange();
     return this.flags();
   }
 }

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

@@ -1,6 +1,8 @@
 # Bootstrap the initial administrator
 
 Use the generated database-backed command after the API build and migrations.
+With `NODE_ENV=production` it loads the bundled `dist/bootstrap-admin-runtime.js`;
+otherwise it runs the source entry. It supports PostgreSQL and SQLite.
 Do not create the first administrator through the public sign-up page.
 
 ## Set the persistent allowlist

package/dist/templates/modules/auth/module.manifest.json

@@ -7,8 +7,8 @@
     ".claude/skills/podokit-configure-auth/**"
   ],
   "dependencies": {
-    "@podosoft/podokit-auth": "^0.4.0",
-    "@podosoft/podokit-contracts": "^0.4.0",
+    "@podosoft/podokit-auth": "^0.5.0",
+    "@podosoft/podokit-contracts": "^0.5.0",
     "better-auth": "^1.7.7",
     "pg": "^8.12.0",
     "@better-auth/api-key": "^1.7.7",