@ultimat3/auth 8.0.0 → 9.0.0

package/CLAUDE.md

@@ -48,7 +48,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `maxKeys` is **not** compared: it bounds one process' table, so a shared limiter has no opinion
   on it. The point is that `Auth.rateLimit` is what an operator reads as "what this deployment
   enforces", so an injected limiter may not quietly enforce something else. Nothing here reads the
-  environment to guess a replica count. `defineAuth({ limiter })` is the one install point.
+  environment to guess a replica count.
 - **`postgresAuthLimiter` is the shared limiter, and a row per FAILURE is what makes it correct**
   (`As of 2026-08`). `assertAuthLimiterPolicy` refused a per-process limiter under
   `scope: 'shared'` and there was nothing else to pass, so the declaration was unsatisfiable while
@@ -71,6 +71,34 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   declared structurally
   even though this package already depends on `@ultimat3/db`: the connection is the HOST's, so the
   limiter takes the pool the boot opened rather than opening a second one.
+- **`configureAuthLimiters` is the HOST's install point and it takes a FACTORY, not a limiter**
+  (`As of 2026-08`). `defineAuth({ limiter })` is still the app's, and it still wins; what was
+  missing is that `postgresAuthLimiter` shipped with **nowhere a host could install it from**.
+  `defineAuth` is the APP's call and the app does not know which pool this process opened —
+  `@ultimat3/cli`'s `startServices` resolves that long before `loadApp` imports a single app
+  module — so a scaffolded app got a per-POD lockout while `x new` scaffolds `replicas: 2` and
+  `docker/helm` runs three: `maxAttempts × N` guesses per account, and a lockout one replica
+  established invisible to the rest.
+
+  A **factory** because the boot cannot know the app's numbers. `assertAuthLimiterPolicy` compares
+  what a limiter enforces against what the app declared, so a limiter built at boot on
+  `DEFAULT_AUTH_RATE_LIMIT` is `X_AUTH_LIMITER_POLICY_MISMATCH` for every app that tuned one. The
+  factory is called with the RESOLVED policy, once per bucket, so the two halves cannot disagree —
+  and the comparison still runs on what comes back, so a factory that ignores its argument is
+  refused exactly as an injected limiter is. Precedence: `config.limiter` → the installed factory →
+  `createAuthLimiter`. `installedAuthLimiter` is deliberately NOT in `src/index.ts`, for the reason
+  `registerJob` is not in `@ultimat3/jobs`': a second caller building limiters out of band is a
+  second answer to where failures are counted.
+
+  `purgeAuthLimits()` is the other half, and it exists because `PostgresAuthLimiter.purgeExpired()`
+  had **no caller anywhere** — every failure row and every dead lockout was kept forever. It sweeps
+  only the **widest** window among the limiters the factory built: they all write the same two
+  tables, so a sweep measured on a narrower window deletes failures a wider limiter is still
+  counting, which is a sprayer buying attempts back from the cleanup job. No `nowMs` argument —
+  a limiter built through the seam holds the clock its host handed it, and that is the clock every
+  `at_ms` in those tables was written from. `AuthLimiter.purgeExpired` is OPTIONAL so
+  `createAuthLimiter` can keep bounding itself; a limiter with no table declares nothing.
+
 - **`normaliseEmail` is the ONE normalisation, it lives ABOVE the `AuthAdapter` seam, and no
   adapter may fold case** (`As of 2026-08`). `MemoryAdapter` lowercased and trimmed on both
   `findUserByEmail` and `createUser`; `BuiltinAdapter` issues `where email = $1` against a plain
@@ -283,6 +311,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `adapter.ts` | the seam; `builtin-adapter.ts` (Postgres) + `memory-adapter.ts` |
 | `rate-limit.ts` | per-ip, per-account and per-org buckets, lockout, scope check, `loginFailed()` |
 | `rate-limit-postgres.ts` | the SHARED limiter: two tables, a row per failure, over a structural `PgExecutor` |
+| `limiter-install.ts` | the host's one install point for that limiter — the factory, what it built, and the purge over it |
 | `oauth.ts` | `OAuthProvider`, PKCE, `beginOAuth`, the callback gate. No I/O, no env |
 | `oauth-builtins.ts` | the three shipped IdPs, as data. Imports only the type, so no cycle |
 | `oauth-registry.ts` | the registry: `registerOAuthProvider`, `providerFor`, `oauthProviderIds` |

package/README.md

@@ -152,8 +152,38 @@ defineAuth({
 Both limiters share one table: the keys are prefixed (`account:`, `ip:`, `org:`) and every limit
 travels as a statement parameter, so the tenant bucket's wider allowance cannot leak into the
 account bucket's. It reports `maxKeys: undefined` — there is no in-process table to bound — and
-neither table forgets on its own: `limiter.purgeExpired()` from a `task` drops failures past the
-window and lockouts that have expired, both measured against the injected clock.
+neither table forgets on its own.
+
+**An app does not have to write any of that, `As of 2026-08-22`.** The boot fills a seam and every
+`defineAuth` in the process picks it up:
+
+```ts
+import { configureAuthLimiters, type PgExecutor, postgresAuthLimiter } from '@ultimat3/auth';
+import type { Clock } from '@ultimat3/core';
+
+declare const bootExecutor: PgExecutor;
+declare const bootClock: Clock;
+
+// In the HOST, before the app's modules import.
+configureAuthLimiters((policy) =>
+  postgresAuthLimiter({ executor: bootExecutor, clock: bootClock, policy }),
+);
+```
+
+A **factory** and not a limiter, because the host runs before the app: `defineAuth` compares what a
+limiter enforces against what the app declared, so a limiter built at boot on the framework
+defaults would be `X_AUTH_LIMITER_POLICY_MISMATCH` for every app that tuned its numbers. The
+factory is called once per bucket, with the resolved policy, so the two halves cannot disagree.
+Precedence is `defineAuth({ limiter })` → the installed factory → `createAuthLimiter`, and
+`resetAuthLimiters()` puts the per-process default back. `@ultimat3/cli`'s `startServices` calls it
+on every boot, so a scaffolded app gets a fleet-wide lockout with nothing to remember.
+
+Neither table forgets on its own, and `purgeAuthLimits()` is the framework's reader for that:
+it drops failures past the window and lockouts that have expired, measured against the clock the
+host handed the limiter, and it sweeps only the WIDEST window installed — a sweep on a narrower
+one deletes failures another limiter is still counting, which hands a sprayer its attempts back.
+`@ultimat3/jobs`' `purge()` job is what calls it hourly; `x dev` and every role container declare
+that sweep at boot.
 
 ## Providers are a registry, not a union
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "8.0.0",
+  "version": "9.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -31,8 +31,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "8.0.0",
-    "@ultimat3/db": "8.0.0",
-    "@ultimat3/schema": "8.0.0"
+    "@ultimat3/core": "9.0.0",
+    "@ultimat3/db": "9.0.0",
+    "@ultimat3/schema": "9.0.0"
   }
 }

package/src/auth.ts

@@ -8,6 +8,7 @@ import { t } from '@ultimat3/schema';
 import type { AuthAdapter, AuthSession, AuthUser } from './adapter';
 import { normaliseEmail } from './email';
 import { mfaRequired, mfaRequiredUnenforceable, sessionUnknown } from './errors';
+import { installedAuthLimiter } from './limiter-install';
 import type { OAuthProviderId } from './oauth';
 import { oauthProviderIds } from './oauth-registry';
 import {
@@ -171,16 +172,28 @@ export function defineAuth(config: AuthConfigInput): Auth {
   const session: SessionPolicy = { ...DEFAULT_SESSION_POLICY, ...config.session };
   const password: PasswordPolicy = { ...DEFAULT_PASSWORD_POLICY, ...config.password };
   const rateLimit: AuthRateLimitPolicy = { ...DEFAULT_AUTH_RATE_LIMIT, ...config.rateLimit };
-  const limiter = config.limiter ?? createAuthLimiter(clock, rateLimit);
+  // Three answers in precedence order, and the middle one is why the seam exists: what this call
+  // passed, then what the HOST installed (`configureAuthLimiters`, filled by the boot that owns
+  // the database connection), then one process' worth of state. Without the middle arm a
+  // scaffolded app had to remember to build a shared limiter itself, which is the opposite of
+  // what this framework promises — and `x new` scaffolds two replicas.
+  const limiter =
+    config.limiter ?? installedAuthLimiter(rateLimit) ?? createAuthLimiter(clock, rateLimit);
   assertAuthLimiterPolicy(rateLimit, limiter);
   // The tenant bucket is a noisy-neighbour cap, not a credential-guessing allowance, so an app
   // that declares `scope: 'shared'` for its LOCKOUT is not also required to ship a shared limiter
   // for this one — per replica it approximates to `orgMaxAttempts × replicas`, which is a
-  // throughput ceiling and discloses nothing. An INJECTED org limiter is still compared, because
-  // then the app has made a claim about what it enforces and `Auth.orgRateLimit` reports it.
+  // throughput ceiling and discloses nothing. Only the LOCAL fallback is exempt, and exempting it
+  // is what buys that: `createAuthLimiter` always reports `'process'`, which is the one arm the
+  // scope check would refuse. A limiter somebody else supplied — injected by the app or built by
+  // the host's factory — is compared exactly as the general bucket's is, because a factory that
+  // ignores the policy it was handed otherwise enforces numbers the app never declared while
+  // `Auth.orgRateLimit` reports the app's. That asymmetry was the whole defect: the same factory
+  // is refused for one bucket and trusted for the other.
   const orgLimits = orgRateLimit(rateLimit);
-  const orgLimiter = config.orgLimiter ?? createAuthLimiter(clock, orgLimits);
-  if (config.orgLimiter !== undefined) assertAuthLimiterPolicy(orgLimits, config.orgLimiter);
+  const suppliedOrgLimiter = config.orgLimiter ?? installedAuthLimiter(orgLimits);
+  const orgLimiter = suppliedOrgLimiter ?? createAuthLimiter(clock, orgLimits);
+  if (suppliedOrgLimiter !== undefined) assertAuthLimiterPolicy(orgLimits, suppliedOrgLimiter);
   // Read through a widened local on purpose: the field's type is the literal `false`, so this
   // branch is unreachable from TypeScript and reachable from every JS caller and every config
   // parsed out of JSON — the same split `invariantColumns()` keeps its Proxy behind a compile

package/src/index.ts

@@ -120,6 +120,10 @@ export {
   kdfGate,
   resetKdfGate,
 } from './kdf-gate';
+export type { AuthLimiterFactory } from './limiter-install';
+// `installedAuthLimiter` is deliberately absent: `defineAuth` is the one reader, and a second
+// caller building limiters out of band would be a second answer to where failures are counted.
+export { configureAuthLimiters, purgeAuthLimits, resetAuthLimiters } from './limiter-install';
 export { MemoryAdapter } from './memory-adapter';
 export type {
   EnrolTotpInput,

package/src/limiter-install.ts

@@ -0,0 +1,90 @@
+// Single responsibility: the ONE ambient install point for where failed credential attempts are
+// counted, plus the purge over whatever it built.
+//
+// WHY a seam and not a `defineAuth` argument: `defineAuth` is the APP's call, and the app is not
+// the thing that knows which database this process opened. A host boot resolves the pool long
+// before it imports app modules (`@ultimat3/cli`'s `startServices` runs before `loadApp`), so
+// until this existed `postgresAuthLimiter` shipped with nowhere to be installed from — account
+// lockouts stayed per-pod while the shipped chart runs three `web` replicas, and an attacker got
+// N x the lockout budget by spreading a spray across them.
+//
+// WHY a FACTORY and not a limiter: `defineAuth` compares what a limiter reports against what the
+// app declared (`assertAuthLimiterPolicy`), and the boot cannot know the app's `maxAttempts`,
+// `windowMs` or `lockoutMs` — it has not imported the app yet. Handing over a built limiter would
+// make every app that tunes its own numbers fail at boot with `X_AUTH_LIMITER_POLICY_MISMATCH`.
+// The factory is called WITH the resolved policy, so the two halves cannot disagree.
+
+import type { AuthLimiter, AuthRateLimitPolicy } from './rate-limit';
+
+/**
+ * Build a limiter enforcing exactly `policy`. Called once per bucket — the account/IP bucket and
+ * the tenant bucket are separate instances over one store, because they enforce different
+ * `maxAttempts` and their keys are prefix-disjoint (`account:` / `ip:` / `org:`).
+ */
+export type AuthLimiterFactory = (policy: AuthRateLimitPolicy) => AuthLimiter;
+
+let factory: AuthLimiterFactory | undefined;
+/** Every limiter this process built through the factory above, so a purge can reach them. */
+let built: AuthLimiter[] = [];
+
+/**
+ * The ONE install point, the same shape as `configureKdfGate` beside it: a host that owns the
+ * database connection says where failed attempts are counted, and every `defineAuth` in the
+ * process picks it up without the app declaring anything.
+ *
+ * A second install replaces the first and forgets what the first built — a limiter over a pool
+ * the previous boot has closed is not something a purge should still be sweeping through.
+ */
+export function configureAuthLimiters(next: AuthLimiterFactory): void {
+  factory = next;
+  built = [];
+}
+
+/** Back to `createAuthLimiter`, the per-process default. A host that installs one calls this on stop. */
+export function resetAuthLimiters(): void {
+  factory = undefined;
+  built = [];
+}
+
+/**
+ * `defineAuth`'s reader, and deliberately NOT exported from `src/index.ts`: a second caller
+ * building limiters out of band would be a second answer to "where are failures counted", which
+ * is the ambiguity axiom 1 refuses. `undefined` means no host installed one, and the caller falls
+ * back to the in-memory limiter.
+ */
+export function installedAuthLimiter(policy: AuthRateLimitPolicy): AuthLimiter | undefined {
+  if (factory === undefined) return undefined;
+  const limiter = factory(policy);
+  built.push(limiter);
+  return limiter;
+}
+
+/** A limiter that keeps rows somebody else has to delete. The memory limiter sweeps itself. */
+type PurgingAuthLimiter = AuthLimiter & { purgeExpired(): Promise<number> };
+
+const canPurge = (limiter: AuthLimiter): limiter is PurgingAuthLimiter =>
+  typeof limiter.purgeExpired === 'function';
+
+/**
+ * Drop every failure past the window and every expired lockout the installed limiters left
+ * behind, and answer how many rows went. `0` when nothing was installed, or when what was
+ * installed keeps no rows.
+ *
+ * The WIDEST window wins, and only that limiter is swept. Every limiter here writes to the same
+ * two tables, so sweeping the narrow one would delete failures the wide one is still counting —
+ * which is a sprayer buying attempts back from the cleanup job. The same defect the http store's
+ * `purgeExpired(nowMs)` exists to prevent, one level up.
+ *
+ * No `nowMs` argument, unlike `postgresRateLimitStore.purgeExpired`: a limiter built through this
+ * seam already holds the clock its host handed it, and that is the clock every `at_ms` in those
+ * tables was written from. A second clock at the call site is exactly the mismatch that reads a
+ * frozen test clock as a 20,000,000-second refill.
+ */
+export async function purgeAuthLimits(): Promise<number> {
+  let widest: PurgingAuthLimiter | undefined;
+  for (const limiter of built) {
+    if (!canPurge(limiter)) continue;
+    if (widest === undefined || limiter.policy.windowMs > widest.policy.windowMs) widest = limiter;
+  }
+  return widest === undefined ? 0 : await widest.purgeExpired();
+}

package/src/rate-limit.ts

@@ -85,6 +85,13 @@ export interface AuthLimiter {
   recordSuccess(key: string): Promise<void>;
   lockedUntil(key: string): Promise<Date | null>;
   reset(): Promise<void>;
+  /**
+   * Drop every expired row this limiter is keeping, and answer how many went. Optional because a
+   * limiter that bounds itself has nothing to sweep — `createAuthLimiter` evicts on write, so it
+   * omits this and `purgeAuthLimits()` skips it. A limiter backed by a table declares it, and
+   * that is what makes the framework's purge job able to reach one without knowing it is Postgres.
+   */
+  purgeExpired?(): Promise<number>;
 }
 
 /** What `createAuthLimiter` returns: the interface, plus the bound it keeps, observable. */