@ultimat3/auth 7.0.0 → 8.0.0

package/CLAUDE.md

@@ -49,6 +49,28 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   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.
+- **`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.
 - **`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 +282,7 @@ 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` |
 | `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 +317,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,53 @@ 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: `limiter.purgeExpired()` from a `task` drops failures past the
+window and lockouts that have expired, both measured against the injected clock.
 
 ## Providers are a registry, not a union
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "7.0.0",
+  "version": "8.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": "8.0.0",
+    "@ultimat3/db": "8.0.0",
+    "@ultimat3/schema": "8.0.0"
   }
 }

package/src/index.ts

@@ -255,6 +255,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/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);
+    },
+  };
+}