@ultimat3/auth 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -48,7 +48,57 @@ 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
+  `x new` scaffolds `replicas: 2`. A counter column plus a window end would have been a FIXED
+  window — `maxAttempts` at the end of one window and `maxAttempts` again at the start of the next,
+  twice the declared allowance under the same declared numbers, on the credential path — so
+  failures are rows and the count is `at_ms > now - windowMs`. The insert and the count are two
+  statements, never one CTE: every CTE in a statement reads that statement's snapshot and cannot
+  see the row being written beside it, so the lockout would fire one attempt late. **Two statements
+  is also why the insert takes `pg_advisory_xact_lock` on the key** — `PgExecutor` accepts a
+  transaction handle, so two OUTER transactions each counted committed rows plus their own, both
+  read one short of `maxAttempts`, and both committed: three failures and an open account. The lock
+  parks the second transaction's insert until the first commits, so its count runs against a
+  snapshot that holds the first's row. Autocommit pays one no-op and no extra round trip; the
+  guarantee is READ COMMITTED, because a snapshot-isolated outer transaction pins its count at
+  transaction start and no lock can undo that. `auth.ts` records account → ip → org in that fixed
+  order, which is what keeps two concurrent sign-ins from taking two of these locks in opposite
+  ones. `greatest` on the lockout upsert EXTENDS and never shortens — two replicas do not share a
+  clock, and the one that lags must not be able to bring a live lockout forward. `PgExecutor` is
+  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
@@ -260,6 +310,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `session.ts` | two expiries, rotation, revocation, device list, the cookie |
 | `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` |
@@ -294,4 +346,9 @@ Gotchas:
   this package **owns**, unconditionally, and lists the borrowed two in `AUTH_BORROWED_ERROR_CODES`
   without a title. A `hasErrorCode()` guard would suppress the `X_ERROR_CODE_DUPLICATE` that is
   supposed to fire when two packages claim one code.
-- Tests run against `MemoryAdapter`; nothing in this package needs a database.
+- Tests run against `MemoryAdapter`; no ADAPTER test needs a database. The two exceptions are
+  `postgresAuthLimiter`'s, and they are exceptions in the shape the repo already has: the
+  scripted-executor twin (`rate-limit-postgres.test.ts`) proves the protocol with no server,
+  and `rate-limit-postgres.live.test.ts` is `describe.skip` without `TEST_DATABASE_URL` — the
+  same pairing `@ultimat3/http`'s rate-limit store and `@ultimat3/realtime`'s Postgres files
+  use. A limiter whose statements were never executed is a credential control nobody has run.

package/README.md

@@ -107,8 +107,83 @@ exemption here — the token arrived in a header.
 
 `maxKeys` is not compared — it bounds one process' table, not a limit. A custom limiter therefore
 does **not** own its own configuration: the policy stays the app's single statement of the limits,
-and the boot check is what keeps it true. **No shared limiter ships yet, `As of 2026-08`** —
-`createAuthLimiter` is the only implementation in the framework.
+and the boot check is what keeps it true.
+
+**A shared limiter ships, `As of 2026-08`** — `postgresAuthLimiter({ executor, clock, policy })`,
+two tables, a row per failure so the window still SLIDES across replicas. Until it landed,
+`scope: 'shared'` was a declaration nothing in the framework could satisfy while `x new` scaffolded
+`replicas: 2` — `maxAttempts × 2` guesses per account. `executor` is a `PgExecutor`, anything
+speaking `query(text, values)`; **never `Bun.sql`**, whose `.query` is `undefined`.
+
+```ts
+import {
+  type AuthAdapter,
+  type AuthRateLimitPolicy,
+  DEFAULT_AUTH_RATE_LIMIT,
+  defineAuth,
+  orgRateLimit,
+  type PgExecutor,
+  postgresAuthLimiter,
+} from '@ultimat3/auth';
+import { type Clock, systemClock } from '@ultimat3/core';
+import { db, type SqlFragment } from '@ultimat3/db';
+
+declare const adapter: AuthAdapter;
+const clock: Clock = systemClock;
+
+// The client this process already opened, wrapped in one line.
+const client = db();
+const executor: PgExecutor = {
+  query: <R>(text: string, values: readonly unknown[]): Promise<readonly R[]> =>
+    client.query<R>({ text, values } satisfies SqlFragment),
+};
+
+const rateLimit: AuthRateLimitPolicy = { ...DEFAULT_AUTH_RATE_LIMIT, scope: 'shared' };
+
+defineAuth({
+  adapter,
+  clock,
+  rateLimit,
+  limiter: postgresAuthLimiter({ executor, clock, policy: rateLimit }),
+  orgLimiter: postgresAuthLimiter({ executor, clock, policy: orgRateLimit(rateLimit) }),
+});
+```
+
+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.
+
+**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": "7.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": "7.0.0",
-    "@ultimat3/db": "7.0.0",
-    "@ultimat3/schema": "7.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,
@@ -255,6 +259,22 @@ export {
   orgKey,
   orgRateLimit,
 } from './rate-limit';
+export type {
+  PgExecutor,
+  PostgresAuthLimiter,
+  PostgresAuthLimiterOptions,
+} from './rate-limit-postgres';
+export {
+  postgresAuthLimiter,
+  SQL_AUTH_FORGET_KEY,
+  SQL_AUTH_KEY_LOCK,
+  SQL_AUTH_LIMIT_TABLES,
+  SQL_AUTH_LOCK,
+  SQL_AUTH_LOCKED_UNTIL,
+  SQL_AUTH_PURGE,
+  SQL_AUTH_RECORD_FAILURE,
+  SQL_AUTH_RESET,
+} from './rate-limit-postgres';
 export type { DisabledUser } from './revocation';
 export {
   disableUser,

package/src/jwks.ts

@@ -7,7 +7,7 @@
 // no credential, so a signature check has to exist before those doors are opened.
 
 import type { Clock } from '@ultimat3/core';
-import { systemClock } from '@ultimat3/core';
+import { renderThrowable, systemClock } from '@ultimat3/core';
 import { oauthExchangeFailed, oauthTokenInvalid } from './errors';
 import { decodeJwtSegment, isRecord } from './json';
 import type { OAuthProvider } from './oauth';
@@ -115,8 +115,9 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
       throw oauthExchangeFailed({
         provider: options.provider,
         stage: 'jwks',
-        detail:
-          error instanceof Error ? error.message : 'the request failed before a response arrived',
+        // `renderThrowable`: this catch is the last frame that can still answer with a code, and
+        // the `kid` that got here came out of an attacker-supplied JWT header.
+        detail: renderThrowable(error),
         fix: `curl -sS -m 5 ${options.jwksUri}`,
       });
     }

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/oauth-discovery.ts

@@ -3,6 +3,7 @@
 // boot, no dependency — an enterprise IdP is then three lines instead of a hand-copied table of
 // four endpoints that nobody re-checks when the vendor moves one.
 
+import { renderThrowable } from '@ultimat3/core';
 import { oauthExchangeFailed } from './errors';
 import { isRecord } from './json';
 import type { OAuthProvider } from './oauth';
@@ -61,8 +62,9 @@ export async function discoverOAuthProvider(
     throw oauthExchangeFailed({
       provider: input.id,
       stage: 'discovery',
-      detail:
-        error instanceof Error ? error.message : 'the request failed before a response arrived',
+      // `renderThrowable`: an injected `fetch` may reject with anything, `instanceof` throws on a
+      // value that traps `getPrototypeOf`, and a bare `TypeError` here is an uncoded crash.
+      detail: renderThrowable(error),
       fix: `curl -sS -m 5 ${url}`,
     });
   }

package/src/oauth-exchange.ts

@@ -4,7 +4,7 @@
 // token is verified here, so no caller downstream can forget to.
 
 import type { Clock } from '@ultimat3/core';
-import { EnvMissingError, renderCauseValue, systemClock } from '@ultimat3/core';
+import { EnvMissingError, renderCauseValue, renderThrowable, systemClock } from '@ultimat3/core';
 import { oauthExchangeFailed, restartAt } from './errors';
 import { type IdTokenClaims, verifyIdToken } from './id-token';
 import { isRecord } from './json';
@@ -143,7 +143,10 @@ async function postForm(
       signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
     });
   } catch (error) {
-    const reason = error instanceof Error ? error.message : 'the request failed before a response';
+    // `renderThrowable`, never `error.message` behind an `instanceof`: the rejection comes from
+    // an injected `fetch`, and `instanceof` itself throws on a value whose `getPrototypeOf` trap
+    // does — losing the one refusal that tells a caller the code is already spent.
+    const reason = renderThrowable(error);
     throw oauthExchangeFailed({
       provider,
       stage: 'token',

package/src/oauth-profile.ts

@@ -3,7 +3,7 @@
 // when there is not. `emailVerified` is carried honestly rather than assumed — it is what
 // decides whether this login may attach itself to an existing account by address.
 
-import { logger } from '@ultimat3/core';
+import { logger, renderThrowable } from '@ultimat3/core';
 import { oauthExchangeFailed, restartAt } from './errors';
 import { idTokenEmailVerified, isVerifiedFlag } from './id-token';
 import { isRecord } from './json';
@@ -61,7 +61,11 @@ async function getJson(
       signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
     });
   } catch (error) {
-    const reason = error instanceof Error ? error.message : 'the request failed before a response';
+    // `renderThrowable`, never `error.message` behind an `instanceof`: `fetch` is INJECTED here,
+    // so the rejection is whatever a driver or a proxy threw — and `instanceof` runs the value's
+    // own `getPrototypeOf` trap, which would replace this coded refusal with a bare `TypeError`
+    // raised from inside the catch that exists to raise it. Same rule as `@ultimat3/cache`.
+    const reason = renderThrowable(error);
     throw oauthExchangeFailed({
       provider,
       stage: 'userinfo',

package/src/rate-limit-postgres.ts

@@ -0,0 +1,234 @@
+// The shared credential limiter: two Postgres tables, so N replicas count one spray once and a
+// lockout one pod established is visible to the rest. Without it `rateLimit.scope: 'shared'` is a
+// declaration nothing can satisfy, while `x new` scaffolds `replicas: 2` — which is
+// `maxAttempts × 2` guesses per account.
+import type { Clock } from '@ultimat3/core';
+import { accountLocked } from './errors';
+import type { AuthLimiter, AuthRateLimitPolicy } from './rate-limit';
+
+/**
+ * The one thing this limiter needs from the DB layer, declared structurally rather than imported.
+ * `@ultimat3/action`'s `idempotency-postgres.ts` and `@ultimat3/http`'s rate-limit store declare
+ * the same shape for the same reason: the connection belongs to the HOST, not to any of them, so
+ * a limiter takes the pool the boot already opened instead of opening a second one against a URL
+ * that was resolved once.
+ *
+ * **`Bun.sql` does not satisfy it** — `Bun.sql.query` is `undefined`; it is a tagged template
+ * whose positional form is `unsafe`. `@ultimat3/db`'s `DbClient.query({ text, values })` does,
+ * wrapped in one line, and so does a transaction handle.
+ */
+export interface PgExecutor {
+  query<R>(sql: string, params: readonly unknown[]): Promise<readonly R[]>;
+}
+
+/**
+ * Applied by the boot, never by an app migration — the rule `SQL_IDEMPOTENCY_TABLE` follows, so
+ * `x dev`, the container's `web` role and `ROLE=migrate` all install it.
+ *
+ * A row per FAILURE rather than a counter per key, because the window this package enforces is a
+ * SLIDING one: a counter plus a window end is a fixed window, which admits `maxAttempts` at the
+ * end of one window and `maxAttempts` again at the start of the next — twice the declared
+ * allowance, under the same declared numbers, on the credential path.
+ */
+export const SQL_AUTH_LIMIT_TABLES = `
+create table if not exists x_auth_failures (
+  key   text   not null,
+  at_ms bigint not null
+);
+
+create index if not exists x_auth_failures_key_idx on x_auth_failures (key, at_ms);
+
+create table if not exists x_auth_lockouts (
+  key             text   primary key,
+  locked_until_ms bigint not null
+);
+
+create index if not exists x_auth_lockouts_until_idx on x_auth_lockouts (locked_until_ms);
+`;
+
+/**
+ * The per-key serializer, spelled from documented functions only: `md5` and a hex bit-string cast,
+ * never `hashtext`, which is an internal with no compatibility promise.
+ */
+export const SQL_AUTH_KEY_LOCK = "pg_advisory_xact_lock(('x' || md5($1))::bit(64)::bigint)";
+
+/**
+ * `$1` key, `$2` nowMs — and a **transaction-scoped advisory lock on the key**, taken in the same
+ * statement, before the row lands.
+ *
+ * `PgExecutor` accepts a transaction handle (see its doc comment), and the insert and the count
+ * below are two statements. Without this lock two OUTER transactions recording a failure for one
+ * account each counted only what had COMMITTED plus their own row: with `maxAttempts: 3` and one
+ * failure already committed, both read two, neither locked, and both committed — three failures
+ * and an open account. The lock makes the second transaction wait at the insert until the first
+ * commits, so its count is taken against a snapshot that already holds the first's row.
+ *
+ * Autocommit is unaffected: the lock is taken and released inside the statement's own implicit
+ * transaction, which is one extra no-op per failure and no extra round trip. The guarantee is
+ * READ COMMITTED, which is what `withTransaction` opens with no `isolation:` — a caller that opts
+ * into `'repeatable read'` or `'serializable'` pins the count's snapshot at transaction start, and
+ * no lock can make a statement see a commit its own snapshot precedes.
+ *
+ * `recordFailure` always locks account → ip → org (`auth.ts`), one fixed order, so two concurrent
+ * sign-ins cannot take two of these locks in opposite orders and deadlock.
+ */
+export const SQL_AUTH_RECORD_FAILURE = `
+with locked as (select ${SQL_AUTH_KEY_LOCK})
+insert into x_auth_failures (key, at_ms)
+select $1, $2::bigint from locked
+`;
+
+/**
+ * `$1` key, `$2` nowMs, `$3` windowMs, `$4` lockoutMs, `$5` maxAttempts.
+ *
+ * A SECOND statement, deliberately, and not a CTE beside the insert above: every CTE in one
+ * statement reads that statement's snapshot, so a `count(*)` sharing it cannot see the failure
+ * being inserted beside it and the lock would fire one attempt late. Run afterwards, the count
+ * sees this caller's own row and every other replica's that has committed — and, because the
+ * insert holds `SQL_AUTH_KEY_LOCK`, every row a concurrent transaction on this key committed too.
+ *
+ * `greatest` on conflict EXTENDS a live lockout and never shortens one — a spray arriving during
+ * a lockout must not be able to reset it to a nearer deadline.
+ */
+export const SQL_AUTH_LOCK = `
+insert into x_auth_lockouts (key, locked_until_ms)
+select $1, $2::bigint + $4::bigint
+  from x_auth_failures
+ where key = $1 and at_ms > $2::bigint - $3::bigint
+having count(*) >= $5::bigint
+on conflict (key) do update
+   set locked_until_ms = greatest(x_auth_lockouts.locked_until_ms, excluded.locked_until_ms)
+returning locked_until_ms
+`;
+
+/** `$2` is the caller's clock: an expired lockout answers exactly as a missing one. */
+export const SQL_AUTH_LOCKED_UNTIL = `
+select locked_until_ms from x_auth_lockouts where key = $1 and locked_until_ms > $2::bigint
+`;
+
+/** A success clears the window AND the lockout: one round trip, because both must go together. */
+export const SQL_AUTH_FORGET_KEY = `
+with cleared as (delete from x_auth_failures where key = $1 returning key)
+delete from x_auth_lockouts where key = $1
+`;
+
+export const SQL_AUTH_RESET = `
+with cleared as (delete from x_auth_failures returning key)
+delete from x_auth_lockouts
+`;
+
+/**
+ * `$1` nowMs, `$2` windowMs — the CALLER's clock, never `now()`. Every instant in these tables is
+ * written from the caller's clock, so a purge measuring against the SERVER's would delete rows by
+ * the offset between the two: failures that are still inside the window, and lockouts that are
+ * still live. The second one hands a sprayer its account back.
+ */
+export const SQL_AUTH_PURGE = `
+with dropped_failures as (
+  delete from x_auth_failures where at_ms <= $1::bigint - $2::bigint returning key
+), dropped_lockouts as (
+  delete from x_auth_lockouts where locked_until_ms <= $1::bigint returning key
+)
+select (select count(*) from dropped_failures) + (select count(*) from dropped_lockouts) as removed
+`;
+
+export interface PostgresAuthLimiterOptions {
+  readonly executor: PgExecutor;
+  /** No `Date.now()` in this package: every instant written and compared comes from here. */
+  readonly clock: Clock;
+  /**
+   * The limits to enforce. `defineAuth` compares what this limiter REPORTS against what the app
+   * declared, so the two must be the same object — `postgresAuthLimiter({ policy: auth.rateLimit })`
+   * for the account and IP buckets, and `orgRateLimit(policy)` for the tenant one.
+   */
+  readonly policy: AuthRateLimitPolicy;
+}
+
+export interface PostgresAuthLimiter extends AuthLimiter {
+  /**
+   * Drop every failure past the window and every expired lockout, and answer how many rows went.
+   * Neither table bounds itself — `ipKey` mints one key per source address, so a spray from an
+   * IPv6 /64 is a row per attempt — and Postgres forgets nothing on its own. An app runs this
+   * from a `task`; a row this deletes answers exactly as a missing one, so it changes no decision.
+   */
+  purgeExpired(): Promise<number>;
+}
+
+interface LockRow {
+  /** `bigint`, which every Postgres client hands back as a string. */
+  readonly locked_until_ms: number | string;
+}
+
+/**
+ * **Install it at `defineAuth`, beside the declaration it satisfies.** Two limiters, one table:
+ * the keys are prefixed (`account:`, `ip:`, `org:`) and every limit travels as a parameter, so
+ * the tenant bucket's wider allowance cannot leak into the account bucket's.
+ *
+ * ```ts
+ * const client = db();
+ * const executor = { query: (text, values) => client.query({ text, values }) };
+ * const rateLimit = { ...DEFAULT_AUTH_RATE_LIMIT, scope: 'shared' } as const;
+ * defineAuth({
+ *   rateLimit,
+ *   limiter: postgresAuthLimiter({ executor, clock, policy: rateLimit }),
+ *   orgLimiter: postgresAuthLimiter({ executor, clock, policy: orgRateLimit(rateLimit) }),
+ * });
+ * ```
+ */
+export function postgresAuthLimiter(options: PostgresAuthLimiterOptions): PostgresAuthLimiter {
+  const exec = options.executor;
+  const clock = options.clock;
+  const policy = options.policy;
+  const nowMs = (): number => clock.now().getTime();
+
+  const lockedUntilMs = async (key: string): Promise<number | null> => {
+    const rows = await exec.query<LockRow>(SQL_AUTH_LOCKED_UNTIL, [key, nowMs()]);
+    const row = rows[0];
+    return row === undefined ? null : Number(row.locked_until_ms);
+  };
+
+  return {
+    // `maxKeys` is dropped, not passed through: it bounds ONE process' table, and reporting a
+    // bound this limiter does not enforce is the thing `assertAuthLimiterPolicy` exists to catch.
+    policy: { ...policy, maxKeys: undefined, scope: 'shared' },
+
+    async assertAllowed(key): Promise<void> {
+      const until = await lockedUntilMs(key);
+      if (until === null) return;
+      throw accountLocked(key, Math.ceil((until - nowMs()) / 1000));
+    },
+
+    async recordFailure(key): Promise<void> {
+      const at = nowMs();
+      await exec.query(SQL_AUTH_RECORD_FAILURE, [key, at]);
+      await exec.query(SQL_AUTH_LOCK, [
+        key,
+        at,
+        policy.windowMs,
+        policy.lockoutMs,
+        policy.maxAttempts,
+      ]);
+    },
+
+    async recordSuccess(key): Promise<void> {
+      await exec.query(SQL_AUTH_FORGET_KEY, [key]);
+    },
+
+    async lockedUntil(key): Promise<Date | null> {
+      const until = await lockedUntilMs(key);
+      return until === null ? null : new Date(until);
+    },
+
+    async reset(): Promise<void> {
+      await exec.query(SQL_AUTH_RESET, []);
+    },
+
+    async purgeExpired(): Promise<number> {
+      const rows = await exec.query<{ readonly removed: number | string }>(SQL_AUTH_PURGE, [
+        nowMs(),
+        policy.windowMs,
+      ]);
+      return Number(rows[0]?.removed ?? 0);
+    },
+  };
+}

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. */