@ultimat3/auth 10.0.0 → 11.1.0

package/CLAUDE.md

@@ -98,6 +98,13 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   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.
+  **What the seam RETAINS is one limiter per window, `As of 2026-08-23`** — a `Map` keyed by
+  `windowMs`, because the widest window is the only thing a purge reads. It was a list appended to
+  on every `installedAuthLimiter` call, two per `defineAuth`, trimmed by nothing: a process that
+  redefines auth (`x dev`'s reload, a test file, a host building one `Auth` per app) held every
+  limiter it ever built and the store behind each. `installedLimiterCount()` is the only
+  observation of that growth — a purge sweeps exactly one limiter however many are held — and it
+  is not exported from `src/index.ts`.
 
 - **`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
@@ -268,6 +275,17 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   what `x new` scaffolds and what every test runs against, so the duplicate path was only ever
   exercised against the permissive half of the seam: two `register()` calls at one address made two
   rows, and the second was unreachable forever. `adapter-parity.test.ts` pins both halves.
+  **A NULL is not a value to either index, `As of 2026-08-23`**: a Postgres unique index is NULLS
+  DISTINCT, so `external_id` constrains only the rows that carry one — the check was
+  `!== undefined`, and `oauth-login.ts` binds `grants.externalId ?? null` for every first-time
+  OAuth user, so the SECOND such signup on a `MemoryAdapter` app failed with `X_AUTH_WRITE_FAILED`
+  against a constraint production does not have.
+- **`MemoryAdapter` takes a `Clock`, and every instant it stamps comes from it** —
+  `new MemoryAdapter(clock)`, defaulting to `systemClock`, so the no-argument construction every
+  test already writes is unchanged. `takeVerification` stamped `consumedAt` with the record's
+  own `createdAt` — the moment the link was ISSUED — where `BuiltinAdapter` writes
+  `consumed_at = now()`, the moment it was REDEEMED: a redemption an hour later and one a second
+  later recorded the identical instant, and a frozen test clock could not move either.
 - The new `AuthAdapter` members are OPTIONAL (`findUserByExternalId`, `listUsersByOrg`,
   `deleteSessionsForUser`, `deleteSessionsForOrg`, `deleteSessionsCreatedBefore`). A required
   member is a breaking change to every third-party adapter; the callers throw

package/README.md

@@ -445,7 +445,7 @@ an adapter implementation, not a dependency of this package.
 | Driver | Use |
 |---|---|
 | `BuiltinAdapter` | Postgres via `@ultimat3/db`; takes an injected `DbClient` |
-| `MemoryAdapter` | `x new` before a database exists, and every test in this package |
+| `MemoryAdapter` | `x new` before a database exists, and every test in this package. `new MemoryAdapter(clock)` — `systemClock` by default — stamps every instant it writes |
 | your own | implement `AuthAdapter`; DDL in `tables.ts` shows what the columns mean |
 
 **An adapter stores and matches the address it is handed — it never folds case.** `x_users.email`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "10.0.0",
+  "version": "11.1.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": "10.0.0",
-    "@ultimat3/db": "10.0.0",
-    "@ultimat3/schema": "10.0.0"
+    "@ultimat3/core": "11.1.0",
+    "@ultimat3/db": "11.1.0",
+    "@ultimat3/schema": "11.1.0"
   }
 }

package/src/limiter-install.ts

@@ -24,8 +24,20 @@ import type { AuthLimiter, AuthRateLimitPolicy } from './rate-limit';
 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 limiters a purge can still reach, ONE per distinct window.
+ *
+ * A list appended to per call is a leak with no ceiling: `installedAuthLimiter` runs twice per
+ * `defineAuth` — the account/IP bucket and the tenant bucket — and nothing trimmed it, so a
+ * process that redefines auth (`x dev`'s reload, a test file, a host building one `Auth` per app)
+ * held every limiter it ever built, and the store behind each, for its whole life.
+ *
+ * Keyed by `windowMs` because that is the only thing `purgeAuthLimits` reads: every limiter here
+ * writes the same two tables, so one per window is all a sweep can distinguish. The FIRST of a
+ * window is kept, which is the limiter the old list already swept — a second install clears the
+ * map, so nothing here outlives the pool it was built on either way.
+ */
+let built = new Map<number, AuthLimiter>();
 
 /**
  * The ONE install point, the same shape as `configureKdfGate` beside it: a host that owns the
@@ -37,13 +49,13 @@ let built: AuthLimiter[] = [];
  */
 export function configureAuthLimiters(next: AuthLimiterFactory): void {
   factory = next;
-  built = [];
+  built = new Map();
 }
 
 /** Back to `createAuthLimiter`, the per-process default. A host that installs one calls this on stop. */
 export function resetAuthLimiters(): void {
   factory = undefined;
-  built = [];
+  built = new Map();
 }
 
 /**
@@ -55,10 +67,20 @@ export function resetAuthLimiters(): void {
 export function installedAuthLimiter(policy: AuthRateLimitPolicy): AuthLimiter | undefined {
   if (factory === undefined) return undefined;
   const limiter = factory(policy);
-  built.push(limiter);
+  if (!built.has(policy.windowMs)) built.set(policy.windowMs, limiter);
   return limiter;
 }
 
+/**
+ * How many limiters a purge can still reach. Deliberately NOT exported from `src/index.ts`: it
+ * exists because unbounded retention has no other observation — `purgeAuthLimits` sweeps exactly
+ * one limiter however many were held, so no assertion about behaviour could see the growth. The
+ * same shape as `@ultimat3/realtime`'s `droppedChannelFrames`.
+ */
+export function installedLimiterCount(): number {
+  return built.size;
+}
+
 /** A limiter that keeps rows somebody else has to delete. The memory limiter sweeps itself. */
 type PurgingAuthLimiter = AuthLimiter & { purgeExpired(): Promise<number> };
 
@@ -82,7 +104,7 @@ const canPurge = (limiter: AuthLimiter): limiter is PurgingAuthLimiter =>
  */
 export async function purgeAuthLimits(): Promise<number> {
   let widest: PurgingAuthLimiter | undefined;
-  for (const limiter of built) {
+  for (const limiter of built.values()) {
     if (!canPurge(limiter)) continue;
     if (widest === undefined || limiter.policy.windowMs > widest.policy.windowMs) widest = limiter;
   }

package/src/memory-adapter.ts

@@ -2,6 +2,7 @@
 // database exists and the one every test in this package runs against — the same interface
 // Postgres and Better Auth implement, so a flow that works here works there or the seam is wrong.
 
+import { type Clock, systemClock } from '@ultimat3/core';
 import type {
   AuthAccount,
   AuthAdapter,
@@ -21,12 +22,22 @@ const verificationKey = (purpose: string, identifier: string): string => `${purp
 
 export class MemoryAdapter implements AuthAdapter {
   readonly name = 'memory';
+  readonly #clock: Clock;
   readonly #users = new Map<string, AuthUser>();
   readonly #sessions = new Map<string, AuthSession>();
   readonly #accounts = new Map<string, AuthAccount>();
   readonly #verifications = new Map<string, AuthVerification>();
   readonly #apiKeys = new Map<string, AuthApiKeyRecord>();
 
+  /**
+   * The clock every instant this adapter stamps comes from — one argument, because a stamp is a
+   * fact about WHEN a call happened and a test that cannot move it can only assert a range.
+   * Defaults to `systemClock`, so `new MemoryAdapter()` is what it always was.
+   */
+  constructor(clock: Clock = systemClock) {
+    this.#clock = clock;
+  }
+
   /**
    * Exact match, because `BuiltinAdapter` issues `where email = $1` against a plain `text ...
    * unique` column and nothing folds case there. Normalising here instead made this the ONE
@@ -59,7 +70,17 @@ export class MemoryAdapter implements AuthAdapter {
       if (existing.email === input.email) {
         throw authUniqueViolation('createUser', 'x_users', 'email');
       }
-      if (input.externalId !== undefined && existing.externalId === input.externalId) {
+      // `!= null` in one predicate, spelled out: a Postgres unique index is NULLS DISTINCT, so
+      // `external_id text unique` constrains only the rows that CARRY a value and admits
+      // unlimited NULLs. `!== undefined` alone made a second account with no external id collide
+      // with the first — and `oauth-login.ts` hands over `grants.externalId ?? null` for every
+      // first-time OAuth user, so the second such signup failed against a constraint production
+      // does not have.
+      if (
+        input.externalId !== undefined &&
+        input.externalId !== null &&
+        existing.externalId === input.externalId
+      ) {
         throw authUniqueViolation('createUser', 'x_users', 'external_id');
       }
     }
@@ -216,7 +237,10 @@ export class MemoryAdapter implements AuthAdapter {
     // Before the write, never after: a wrong guess that consumed the row would be an
     // unauthenticated way to kill the victim's live link, which is the Postgres adapter's rule too.
     if (!timingSafeEqual(tokenHash, record.tokenHash)) return null;
-    const consumed: AuthVerification = { ...record, consumedAt: new Date(record.createdAt) };
+    // The moment it was REDEEMED, which is what `consumed_at = now()` writes on the Postgres
+    // side. This was `new Date(record.createdAt)` — the moment it was ISSUED — so every window
+    // measured from the stamp read a redemption as having happened at issue time.
+    const consumed: AuthVerification = { ...record, consumedAt: this.#clock.now() };
     this.#verifications.set(key, consumed);
     return consumed;
   }