@podosoft/podokit 1.1.6 → 1.2.0

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

@@ -1,6 +1,7 @@
 import type { SQL } from "bun";
+import { AppException } from "@podosoft/podokit-contracts";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import type { AuthSession } from "../auth/auth.service";
-import { auditEnabled } from "./audit-enabled";
 import { setAuditRecorder, type AuditEntry } from "./audit-events";
 
 export interface AuditLogView extends AuditEntry {
@@ -13,6 +14,56 @@ type AuditLogRow = Omit<AuditLogView, "createdAt" | "metadata"> & {
   metadata: unknown;
 };
 
+// A type alias, not an interface: Bun's insert helper needs an indexable row.
+type AuditRow = {
+  id: string;
+  action: string;
+  actorId: string | null;
+  actorName: string | null;
+  actorEmail: string | null;
+  targetType: string | null;
+  targetId: string | null;
+  targetLabel: string | null;
+  ip: string | null;
+  metadata: Record<string, unknown> | string | null;
+  createdAt: string;
+};
+
+const COLUMNS = [
+  "id", "action", "actorId", "actorName", "actorEmail",
+  "targetType", "targetId", "targetLabel", "ip", "metadata", "createdAt",
+] as const satisfies readonly (keyof AuditRow)[];
+
+export const DEFAULT_AUDIT_PAGE_SIZE = 50;
+export const MAX_AUDIT_PAGE_SIZE = 100;
+const MAX_LISTED_ACTIONS = 500;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export interface AuditLogQuery {
+  /** Opaque position from a previous page's `nextCursor`. */
+  cursor?: string;
+  limit?: number;
+  /** Newest first by default. */
+  order?: "asc" | "desc";
+  /** Exact action code. */
+  action?: string;
+  /** Exact actor email. */
+  actor?: string;
+  /** Exact target label (the email or title the list shows). */
+  target?: string;
+}
+
+export interface AuditLogPage {
+  entries: AuditLogView[];
+  /** Cursor for the following page; null on the last page. */
+  nextCursor: string | null;
+}
+
+interface AuditPosition {
+  createdAt: string;
+  id: string;
+}
+
 export interface AuditTarget {
   type?: string;
   id?: string;
@@ -20,58 +71,329 @@ export interface AuditTarget {
   metadata?: Record<string, unknown>;
 }
 
+export interface AuditQueueOptions {
+  /** Deferred entries held in memory; once full, new deferred entries are dropped. */
+  maxQueued: number;
+  /** Rows per INSERT. A full batch is written without waiting for the timer. */
+  batchSize: number;
+  flushIntervalMs: number;
+}
+
+export const DEFAULT_AUDIT_QUEUE: AuditQueueOptions = {
+  maxQueued: 1_000,
+  batchSize: 100,
+  flushIntervalMs: 250,
+};
+
+export interface AuditLogger {
+  warn(details: Record<string, unknown>, message: string): void;
+}
+
+export interface AuditRetentionOptions {
+  /** Entries older than this many days are deleted. 0 keeps them forever. */
+  days: number;
+  /** Rows per DELETE statement, so a backlog never becomes one long delete. */
+  batchSize: number;
+  /** Pause between prune runs. */
+  intervalMs: number;
+}
+
+export const DEFAULT_AUDIT_RETENTION: AuditRetentionOptions = {
+  days: 0,
+  batchSize: 1_000,
+  intervalMs: 60 * 60 * 1_000,
+};
+
+const DAY_MS = 24 * 60 * 60 * 1_000;
+
+/** Reads AUDIT_LOG_RETENTION_DAYS: unset, empty, or 0 keeps entries forever. */
+export function parseRetentionDays(value: string | undefined): number {
+  const text = value?.trim() ?? "";
+  if (text === "") return 0;
+  const days = Number(text);
+  if (!Number.isSafeInteger(days) || days < 0) {
+    throw new Error("AUDIT_LOG_RETENTION_DAYS must be a whole number of days; 0 keeps entries forever");
+  }
+  return days;
+}
+
+export interface AuditServiceOptions {
+  dialect: DatabaseProviderName;
+  /** The admin on/off toggle, read before every write. */
+  enabled: () => Promise<boolean>;
+  logger?: AuditLogger;
+  queue?: Partial<AuditQueueOptions>;
+  retention?: Partial<AuditRetentionOptions>;
+}
+
+export interface RecordRequestOptions {
+  /** Queue the entry instead of awaiting the write. See `recordLater()`. */
+  defer?: boolean;
+}
+
 export class AuditService {
   private unregister?: () => void;
+  private readonly dialect: DatabaseProviderName;
+  private readonly enabled: () => Promise<boolean>;
+  private readonly logger?: AuditLogger;
+  private readonly queueOptions: AuditQueueOptions;
+  private queue: AuditRow[] = [];
+  private dropped = 0;
+  private failing = false;
+  private flushTimer?: ReturnType<typeof setTimeout>;
+  private flushing?: Promise<void>;
+  private readonly retention: AuditRetentionOptions;
+  private pruneTimer?: ReturnType<typeof setTimeout>;
+  private pruning?: Promise<void>;
+  private closed = false;
 
-  constructor(private readonly sql: SQL) {}
+  constructor(private readonly sql: SQL, options: AuditServiceOptions) {
+    this.dialect = options.dialect;
+    this.enabled = options.enabled;
+    this.logger = options.logger;
+    this.queueOptions = { ...DEFAULT_AUDIT_QUEUE, ...options.queue };
+    this.retention = { ...DEFAULT_AUDIT_RETENTION, ...options.retention };
+  }
 
+  /** Registers the recorder and, when a retention period is set, starts pruning. */
   connect(): void {
-    this.unregister ??= setAuditRecorder((entry) => this.record(entry));
+    this.closed = false;
+    this.unregister ??= setAuditRecorder({
+      record: (entry) => this.record(entry),
+      recordLater: (entry) => this.recordLater(entry),
+    });
+    if (this.retention.days > 0 && !this.pruneTimer && !this.pruning) this.schedulePrune(0);
   }
 
-  close(): void {
+  /** Stops pruning and the registry, then writes the queue. */
+  async close(): Promise<void> {
+    this.closed = true;
     this.unregister?.();
     this.unregister = undefined;
+    if (this.pruneTimer) clearTimeout(this.pruneTimer);
+    this.pruneTimer = undefined;
+    await this.pruning;
+    await this.flush();
   }
 
-  async record(entry: AuditEntry): Promise<void> {
-    try {
-      const metadata = entry.metadata === undefined || entry.metadata === null
-        ? null
-        : JSON.stringify(entry.metadata);
-      await this.sql`
-        INSERT INTO "audit_logs" (
-          "id", "action", "actorId", "actorName", "actorEmail",
-          "targetType", "targetId", "targetLabel", "ip", "metadata", "createdAt"
-        ) VALUES (
-          ${crypto.randomUUID()}, ${entry.action}, ${entry.actorId ?? null}, ${entry.actorName ?? null},
-          ${entry.actorEmail ?? null}, ${entry.targetType ?? null},
-          ${entry.targetId ?? null}, ${entry.targetLabel ?? null}, ${entry.ip ?? null},
-          CAST(${metadata} AS JSON), ${new Date().toISOString()}
+  /**
+   * Deletes entries older than the retention period, at most `batchSize` rows per
+   * statement, until none are left. Returns the number deleted.
+   */
+  async prune(now: number = Date.now()): Promise<number> {
+    if (this.retention.days <= 0) return 0;
+    // An ISO string compares correctly with SQLite's text timestamps and casts
+    // to timestamptz on PostgreSQL, so one statement serves both.
+    const cutoff = new Date(now - this.retention.days * DAY_MS).toISOString();
+    let deleted = 0;
+    while (!this.closed) {
+      // Counted from RETURNING: Bun's SQLite adapter can report zero changes for
+      // a DELETE whose subquery starts on its own line.
+      const removed = await this.sql<Array<{ id: string }>>`
+        DELETE FROM "audit_logs" WHERE "id" IN (
+          SELECT "id" FROM "audit_logs"
+          WHERE "createdAt" < ${cutoff}
+          ORDER BY "createdAt"
+          LIMIT ${this.retention.batchSize}
         )
+        RETURNING "id"
       `;
-    } catch {
+      deleted += removed.length;
+      if (removed.length < this.retention.batchSize) break;
+    }
+    if (deleted > 0) {
+      await this.record({ action: "audit.pruned", metadata: { count: deleted, before: cutoff } });
+    }
+    return deleted;
+  }
+
+  private schedulePrune(delayMs: number): void {
+    this.pruneTimer = setTimeout(() => {
+      this.pruneTimer = undefined;
+      this.pruning = this.prune()
+        .then(() => undefined, (error: unknown) => {
+          this.logger?.warn({ error: message(error) }, "Audit retention prune failed");
+        })
+        .finally(() => {
+          this.pruning = undefined;
+          if (!this.closed) this.schedulePrune(this.retention.intervalMs);
+        });
+    }, delayMs);
+    this.pruneTimer.unref?.();
+  }
+
+  /** Writes the entry before resolving. Use for security events. */
+  async record(entry: AuditEntry): Promise<void> {
+    try {
+      await this.persist([this.row(entry)]);
+    } catch (error) {
       // Audit persistence must never break the operation it describes.
+      this.logger?.warn({ action: entry.action, error: message(error) }, "Audit write failed");
+    }
+  }
+
+  /**
+   * Queues the entry and returns at once. Queued entries are written together
+   * every `flushIntervalMs`, as soon as a batch fills, and on `close()`. Entries
+   * still queued when the process dies are lost, so keep security events on
+   * `record()`.
+   */
+  recordLater(entry: AuditEntry): void {
+    try {
+      if (this.queue.length >= this.queueOptions.maxQueued) {
+        // Waiting here would turn a slow database into slow requests, which is
+        // what deferral avoids. The loss is recorded once the database recovers.
+        if (this.dropped === 0) {
+          this.logger?.warn(
+            { maxQueued: this.queueOptions.maxQueued },
+            "Audit queue is full; dropping deferred entries",
+          );
+        }
+        this.dropped += 1;
+        return;
+      }
+      this.queue.push(this.row(entry));
+      if (this.queue.length >= this.queueOptions.batchSize) void this.flush();
+      else this.scheduleFlush();
+    } catch (error) {
+      this.logger?.warn({ action: entry.action, error: message(error) }, "Audit entry could not be queued");
+    }
+  }
+
+  /** Writes every queued entry, one INSERT per batch. */
+  flush(): Promise<void> {
+    this.flushing ??= this.drain().finally(() => {
+      this.flushing = undefined;
+      if (this.queue.length > 0) this.scheduleFlush();
+    });
+    return this.flushing;
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = undefined;
+      void this.flush();
+    }, this.queueOptions.flushIntervalMs);
+    this.flushTimer.unref?.();
+  }
+
+  private async drain(): Promise<void> {
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = undefined;
+    while (this.queue.length > 0 || this.dropped > 0) {
+      const batch = this.queue.splice(0, this.queueOptions.batchSize);
+      const dropped = this.dropped;
+      this.dropped = 0;
+      if (dropped > 0) batch.push(this.row({ action: "audit.dropped", metadata: { count: dropped } }));
+      try {
+        await this.persist(batch);
+        this.failing = false;
+      } catch (error) {
+        this.dropped += dropped + batch.length - (dropped > 0 ? 1 : 0);
+        if (!this.failing) {
+          this.logger?.warn({ entries: this.dropped, error: message(error) }, "Audit batch write failed");
+        }
+        this.failing = true;
+        return;
+      }
     }
   }
 
-  async recent(limit = 50): Promise<AuditLogView[]> {
-    const rows = await this.sql<AuditLogRow[]>`
+  /** The one write path: checks the admin toggle, then inserts the rows. */
+  private async persist(rows: AuditRow[]): Promise<void> {
+    if (rows.length === 0 || !(await this.enabled())) return;
+    await this.sql`INSERT INTO "audit_logs" ${this.sql(rows, ...COLUMNS)}`;
+  }
+
+  private row(entry: AuditEntry): AuditRow {
+    const metadata = entry.metadata ?? null;
+    return {
+      id: crypto.randomUUID(),
+      action: entry.action,
+      actorId: entry.actorId ?? null,
+      actorName: entry.actorName ?? null,
+      actorEmail: entry.actorEmail ?? null,
+      targetType: entry.targetType ?? null,
+      targetId: entry.targetId ?? null,
+      targetLabel: entry.targetLabel ?? null,
+      ip: entry.ip ?? null,
+      // Bun encodes a bound value as JSON for a jsonb column, so a pre-serialized
+      // string would be stored as a JSON string. SQLite keeps the text column.
+      metadata: metadata === null || this.dialect === "postgres" ? metadata : JSON.stringify(metadata),
+      createdAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * One page of entries in ("createdAt", "id") order. Keyset paging keeps every
+   * page as cheap as the first, however deep the caller reads.
+   */
+  async list(query: AuditLogQuery = {}): Promise<AuditLogPage> {
+    const sql = this.sql;
+    const requested = Number.isFinite(query.limit) ? Math.trunc(query.limit ?? 0) : DEFAULT_AUDIT_PAGE_SIZE;
+    const limit = Math.min(Math.max(requested, 1), MAX_AUDIT_PAGE_SIZE);
+    const after = query.cursor ? this.decodeCursor(query.cursor) : null;
+    const descending = query.order !== "asc";
+    const rows = await sql<AuditLogRow[]>`
       SELECT "id", "action", "actorId", "actorName", "actorEmail",
              "targetType", "targetId", "targetLabel", "ip", "metadata", "createdAt"
       FROM "audit_logs"
-      ORDER BY "createdAt" DESC
-      LIMIT ${limit}
+      WHERE 1 = 1
+        ${query.action ? sql`AND "action" = ${query.action}` : sql``}
+        ${query.actor ? sql`AND "actorEmail" = ${query.actor}` : sql``}
+        ${query.target ? sql`AND "targetLabel" = ${query.target}` : sql``}
+        ${after
+          ? descending
+            ? sql`AND ("createdAt", "id") < (${after.createdAt}, ${after.id})`
+            : sql`AND ("createdAt", "id") > (${after.createdAt}, ${after.id})`
+          : sql``}
+      ${descending
+        ? sql`ORDER BY "createdAt" DESC, "id" DESC`
+        : sql`ORDER BY "createdAt" ASC, "id" ASC`}
+      LIMIT ${limit + 1}
+    `;
+    const page = rows.slice(0, limit);
+    const last = page.at(-1);
+    return {
+      entries: page.map(view),
+      nextCursor: rows.length > limit && last ? encodeCursor(last) : null,
+    };
+  }
+
+  /** Distinct action codes, for filter menus. */
+  async actions(): Promise<string[]> {
+    // A loose index scan: each step seeks the next larger code in the action
+    // index, so the cost follows the number of codes rather than rows.
+    const rows = await this.sql<Array<{ action: string | null }>>`
+      WITH RECURSIVE "codes"("action") AS (
+        SELECT MIN("action") FROM "audit_logs"
+        UNION ALL
+        SELECT (SELECT MIN("action") FROM "audit_logs" WHERE "action" > "codes"."action")
+        FROM "codes"
+        WHERE "codes"."action" IS NOT NULL
+      )
+      SELECT "action" FROM "codes" WHERE "action" IS NOT NULL LIMIT ${MAX_LISTED_ACTIONS}
     `;
-    return rows.map((row) => ({
-      ...row,
-      metadata: typeof row.metadata === "string"
-        ? JSON.parse(row.metadata) as Record<string, unknown>
-        : row.metadata as Record<string, unknown> | null,
-      createdAt: row.createdAt instanceof Date
-        ? row.createdAt.toISOString()
-        : new Date(row.createdAt).toISOString(),
-    }));
+    return rows.flatMap((row) => row.action === null ? [] : [row.action]);
+  }
+
+  private decodeCursor(cursor: string): AuditPosition {
+    try {
+      const value: unknown = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+      if (Array.isArray(value) && value.length === 2) {
+        const [createdAt, id] = value as unknown[];
+        if (
+          typeof createdAt === "string" && !Number.isNaN(Date.parse(createdAt)) &&
+          typeof id === "string" && id.length > 0 && (this.dialect !== "postgres" || UUID.test(id))
+        ) {
+          return { createdAt, id };
+        }
+      }
+    } catch {
+      // Malformed base64 or JSON is reported below like any other bad cursor.
+    }
+    throw new AppException("INVALID_CURSOR", "The audit log cursor is invalid", 400);
   }
 
   async recordRequest(
@@ -79,9 +401,9 @@ export class AuditService {
     request: Request,
     session: AuthSession,
     target: AuditTarget = {},
+    options: RecordRequestOptions = {},
   ): Promise<void> {
-    if (!(await auditEnabled())) return;
-    await this.record({
+    const entry: AuditEntry = {
       action,
       actorId: session.user.id,
       actorName: typeof session.user.name === "string" ? session.user.name : null,
@@ -91,6 +413,31 @@ export class AuditService {
       targetLabel: target.label ?? null,
       metadata: target.metadata ?? null,
       ip: request.headers.get("x-forwarded-for") ?? null,
-    });
+    };
+    if (options.defer) this.recordLater(entry);
+    else await this.record(entry);
   }
 }
+
+function view(row: AuditLogRow): AuditLogView {
+  return {
+    ...row,
+    metadata: typeof row.metadata === "string"
+      ? JSON.parse(row.metadata) as Record<string, unknown>
+      : row.metadata as Record<string, unknown> | null,
+    createdAt: row.createdAt instanceof Date
+      ? row.createdAt.toISOString()
+      : new Date(row.createdAt).toISOString(),
+  };
+}
+
+// Keeps the stored timestamp text as is: SQLite compares it as a string, so a
+// reformatted value could skip or repeat rows.
+function encodeCursor(row: AuditLogRow): string {
+  const createdAt = row.createdAt instanceof Date ? row.createdAt.toISOString() : row.createdAt;
+  return Buffer.from(JSON.stringify([createdAt, row.id])).toString("base64url");
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/dist/templates/modules/audit-log/files/apps/api/src/migrations/1792000000000-IndexAuditLogFilters.ts

@@ -0,0 +1,35 @@
+import type { MigrationInterface, QueryRunner } from "typeorm";
+
+// Indexes for the keyset list: ("createdAt", "id") serves the unfiltered pages and
+// the retention prune, and each filter gets its column followed by "createdAt".
+// IF NOT EXISTS lets an operator build them beforehand with CREATE INDEX
+// CONCURRENTLY on a large PostgreSQL table; migrations run in one transaction.
+const INDEXES: Array<[name: string, columns: string]> = [
+  ["IDX_audit_logs_createdAt_id", `"createdAt", "id"`],
+  ["IDX_audit_logs_action_createdAt", `"action", "createdAt"`],
+  ["IDX_audit_logs_actorEmail_createdAt", `"actorEmail", "createdAt"`],
+  ["IDX_audit_logs_targetLabel_createdAt", `"targetLabel", "createdAt"`],
+];
+
+const REPLACED: Array<[name: string, columns: string]> = [
+  ["IDX_audit_logs_action", `"action"`],
+  ["IDX_audit_logs_createdAt", `"createdAt"`],
+];
+
+export class IndexAuditLogFilters1792000000000 implements MigrationInterface {
+  name = "IndexAuditLogFilters1792000000000";
+
+  async up(queryRunner: QueryRunner): Promise<void> {
+    for (const [name, columns] of INDEXES) {
+      await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`);
+    }
+    for (const [name] of REPLACED) await queryRunner.query(`DROP INDEX IF EXISTS "${name}"`);
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    for (const [name, columns] of REPLACED) {
+      await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`);
+    }
+    for (const [name] of INDEXES) await queryRunner.query(`DROP INDEX IF EXISTS "${name}"`);
+  }
+}

package/dist/templates/modules/audit-log/module.manifest.json

@@ -6,7 +6,10 @@
   "env": [
     "# audit-log: managed on the admin Settings page, stored in the DB,",
     "# and applied without restart. This environment value is the fallback.",
-    "AUDIT_LOG_ENABLED=true"
+    "AUDIT_LOG_ENABLED=true",
+    "# audit-log: delete entries older than this many days. Unset or 0 keeps them",
+    "# forever; set it only when your retention policy requires deleting them.",
+    "AUDIT_LOG_RETENTION_DAYS=0"
   ],
   "inject": [
     {
@@ -32,10 +35,10 @@
   ],
   "instructions": [
     "Run migrations to create the audit_logs table: {{apiRun}} migration:run{{apiWorkspaceArg}}",
-    "Auth/admin actions are recorded by a Better Auth hook. Record semantic application events with AuditService.recordRequest() or recordAudit().",
-    "List recent entries (admin session required): curl -b cookies.txt localhost:5002/audit-logs"
+    "Auth/admin actions are recorded by a Better Auth hook. Record semantic application events with AuditService.recordRequest() or recordAudit(); use recordAuditLater() only for high-volume, non-security events.",
+    "List entries newest first (admin session required): curl -i -b cookies.txt 'localhost:5002/audit-logs?limit=50' and pass the X-Next-Cursor header back as ?cursor= for the next page"
   ],
   "dependencies": {
-    "@podosoft/podokit-auth": "^0.4.0"
+    "@podosoft/podokit-auth": "^0.5.0"
   }
 }

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

@@ -1,6 +1,21 @@
-import { createConfigStore } from "@podosoft/podokit-auth";
-import { readAuthConfig } from "./db";
+import { createConfigStore, type ConfigStore } from "@podosoft/podokit-auth";
+import { flagsFrom } from "../settings/flag-defaults";
+import { readAppSettings, readAuthConfig, readConfigVersions } from "./db";
+import { signupOpenFrom } from "./feature-gate";
 
-// One process-wide store keeps the auth runtime and capabilities endpoint on the
-// same cache snapshot. Admin writes invalidate this store before rebuilding auth.
-export const authConfigStore = createConfigStore({ list: readAuthConfig });
+/** A store over this app's auth_config and app_setting tables. */
+export function createAuthConfigStore(): ConfigStore {
+  return createConfigStore({
+    list: readAuthConfig,
+    listSettings: readAppSettings,
+    versions: readConfigVersions,
+  });
+}
+
+// One process-wide snapshot serves the auth runtime, feature gate, settings
+// service, mailer, capabilities endpoint, and audit toggle. Local writes
+// invalidate it; other replicas see a change at their next version probe.
+export const authConfigStore = createAuthConfigStore();
+
+export const featureFlags = authConfigStore.selectSettings(flagsFrom);
+export const isSignupOpen = authConfigStore.selectSettings(signupOpenFrom);

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

@@ -1,5 +1,7 @@
+import type { AuthConfig } from "@podosoft/podokit-auth";
 import { auth as bootstrapAuth, buildAuth } from "./auth";
 import { authConfigStore } from "./auth-config-store";
+import { publishConfigChanged } from "./config-events";
 
 // Runtime auth instance that rebuilds when the DB config changes, so admin edits
 // (OAuth credentials, SMTP, server-enforced toggles) apply WITHOUT a restart.
@@ -8,52 +10,46 @@ import { authConfigStore } from "./auth-config-store";
 // that refreshes the DB-backed configuration and dispatches to the current Better
 // Auth instance. Session tokens remain valid because BETTER_AUTH_SECRET is stable.
 
-const TTL_MS = 3_000;
-
 let current = bootstrapAuth;
 let currentVersion = "env"; // matches envAuthConfig() bootstrap
-let checkedAt = 0;
-let inflight: Promise<void> | null = null;
+let failedVersion: string | null = null;
 
 export function getAuth(): typeof bootstrapAuth {
   return current;
 }
 
-/** Rebuild the instance if the DB config version changed. Cheap and throttled to
- *  TTL; single-flight so concurrent requests trigger at most one rebuild; keeps the
- *  last-good instance if loading/building fails, so auth never goes down. */
+/** Rebuild the instance if the DB config version changed. The config store
+ *  throttles its version probe to its TTL and shares one refresh between
+ *  concurrent callers, so this is cheap per request. Keeps the last-good instance
+ *  if loading or building fails, so auth never goes down. */
 export async function refreshIfStale(): Promise<void> {
-  if (checkedAt !== 0 && Date.now() - checkedAt < TTL_MS) return;
-  checkedAt = Date.now();
-  let latest: string;
+  let config: AuthConfig;
   try {
-    latest = await authConfigStore.currentVersion();
+    config = await authConfigStore.load();
   } catch {
     return; // DB blip — keep serving the last-good instance
   }
-  if (latest === currentVersion) return;
-  if (inflight) return inflight;
-  inflight = (async () => {
-    try {
-      const config = await authConfigStore.load();
-      current = buildAuth(config);
-      currentVersion = config.version;
-    } catch (err) {
-      console.error("[auth-config] rebuild failed; keeping last-good auth instance:", err instanceof Error ? err.message : err);
-    } finally {
-      inflight = null;
-    }
-  })();
-  return inflight;
+  // A config that failed to build is retried only after it changes.
+  if (config.version === currentVersion || config.version === failedVersion) return;
+  try {
+    current = buildAuth(config);
+    currentVersion = config.version;
+    failedVersion = null;
+  } catch (err) {
+    failedVersion = config.version;
+    console.error("[auth-config] rebuild failed; keeping last-good auth instance:", err instanceof Error ? err.message : err);
+  }
 }
 
-/** Apply a successful in-process admin write before the response is returned. */
+/** Apply a successful in-process admin write before the response is returned,
+ *  and tell other replicas when an events provider is installed. */
 export async function refreshAuthNow(): Promise<void> {
   authConfigStore.invalidate();
-  checkedAt = 0;
-  // Force a rebuild even if two writes receive the same millisecond timestamp.
+  // Force a rebuild even if the write left the version token unchanged.
   currentVersion = `stale:${Date.now()}`;
+  failedVersion = null;
   await refreshIfStale();
+  await publishConfigChanged();
 }
 
 // Stable handler reference the adapter captures once; redispatches per request.
@@ -72,6 +68,5 @@ export const authRuntime: typeof bootstrapAuth = new Proxy(bootstrapAuth, {
 
 /** Optional boot preload so the first request doesn't pay the initial DB read. */
 export async function primeAuth(): Promise<void> {
-  checkedAt = 0;
   await refreshIfStale();
 }