@ultimat3/auth 16.0.0 → 18.0.0

package/CLAUDE.md

@@ -16,6 +16,60 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 
 ## Non-negotiables
 
+- **A policy NUMBER is screened at `defineAuth`, `As of 2026-08-26`** (`policy-numbers.ts`,
+  `X_CONFIG_INVALID`). `session.absoluteTtlMs`, `session.idleTtlMs`, `session.idleSlideMs`,
+  `password.minLength`, the two argon2 costs and every `rateLimit` number. Measured with `NaN` —
+  what `Number(process.env.SESSION_TTL_MS)` answers when the variable is unset, and not nullish, so
+  the spread over the defaults keeps it: `now >= NaN` is false, so a session idle since 2000
+  reported `absoluteExpired: false` AND `idleExpired: false`; `password.length < NaN` is false and
+  the two-distinct-characters rule is guarded by `length > 0`, so the EMPTY password was accepted.
+  A rule whose comparison is false for every input is not a loose rule, it is no rule.
+
+- **Every RUNTIME number this package bounds anything with is screened too, `As of 2026-08-26`** —
+  `assertFiniteAuthCount` in `policy-numbers.ts`, one file for both halves. `jwks.ttlMs`
+  (`now >= fetchedAt + NaN` is false, so a provider's key rotation is never refetched and every
+  login against the new `kid` fails until the process restarts), the three OAuth legs' `timeoutMs`
+  (`AbortSignal.timeout(NaN)` THROWS, and it is screened OUTSIDE each leg's `try` — inside it, the
+  catch rendered an app config typo as the identity provider being unreachable), the limiter's
+  `maxKeys` (`Math.max(1, Math.floor(NaN))` is `NaN`, so the sweep bounding a table half of whose
+  keys are attacker-chosen never ran) and `mfa.drift`. **`drift` is the one that hangs**: it is a
+  LOOP BOUND, not a comparison — `for (offset = -Infinity; offset <= Infinity; offset += 1)` never
+  terminates, measured, synchronously, on the login path — and `NaN` makes the loop never run at
+  all, so every correct code is rejected as if it were wrong. Editing `verifyTotp` with the screen
+  removed WEDGES `mfa.test.ts` rather than failing it; mutate with the `NaN` case.
+
+  **That sentence was false when it was written and four more sites closed it, `As of 2026-08-26`.**
+  It named the options `defineAuth` resolves and the ones a *service* call takes, and missed every
+  number a **cookie** or a **mailed link** is bounded by. `oauth.handshake.ttlMs` is the one that
+  matters: `openHandshake`'s `now - issuedAt > NaN` is false, so a year-old sealed handshake — the
+  state, nonce and PKCE verifier that ARE the callback leg's CSRF defence — opened and returned its
+  verifier, while `handshakeCookie` wrote `Max-Age=NaN`, which is not `delta-seconds`, so the
+  browser dropped the attribute and kept the cookie for the whole session. One number, both ends of
+  the deadline, off together and silently. `session.cookie.maxAgeSeconds` is the same shape beside
+  a `policy.absoluteTtlMs` that WAS screened; `kdf.maxConcurrent`/`kdf.maxQueued` are the second
+  thing that WEDGES after `mfa.drift` — core asks `active < maxConcurrent` then
+  `waiters.length >= maxQueued`, both false for `NaN`, so every `hashPassword` on the box parks in
+  an unbounded queue nothing releases and login stops answering rather than shedding.
+
+- **A number is screened ABOVE the write it feeds, not beside the arithmetic** (`As of
+  2026-08-26`). `issueVerification` read `input.ttlMs ?? DEFAULT_VERIFICATION_TTL_MS[purpose]`
+  straight into `new Date(now + ttl)` and threw a bare `RangeError` — `toISOString()` refuses an
+  Invalid Date — on the line AFTER `putVerification` had already resolved. Two faults from one
+  number: an uncoded throw out of the package, and a durable row whose expiry `consumeVerification`
+  compares as `now >= NaN`, false for ever, i.e. a password-reset link that never expires. The
+  write also upserts on `(purpose, identifier)`, so the failing call had destroyed whatever live
+  token that address held on its way out. `verify.test.ts` asserts the ordering directly (no row
+  written, no mail sent, the earlier token still redeemable) — moving the screen below the store
+  call fails those three and leaves the coded-refusal case green.
+
+- **The minimum is per option, and zero is usually legitimate.** `assertFiniteAuthCount`'s `min` is
+  `0 | 1` because only the call site knows what zero MEANS, and picking `1` for tidiness is how a
+  screen breaks a working deployment while every test still passes. `maxAgeSeconds: 0` is how a
+  cookie is expired — it is what sign-out emits — and `{ maxConcurrent: 0, maxQueued: 0 }` is a
+  gate that refuses every hash, which is how `password.test.ts` proves the unreadable-hash path
+  burns the same KDF a wrong password does. Both take `min: 0`. A TTL takes `min: 1`, because a
+  handshake or a mailed link that is already expired when it is issued is not a configuration.
+
 - Every credential failure throws `loginFailed()` — one code, one cause, one fix. Adding a
   parameter to it re-opens account enumeration.
 - **A stored hash Bun cannot read is the generic failure, and it burns the same KDF** (`As of
@@ -394,7 +448,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 
 | File | Job |
 |---|---|
-| `auth.ts` | `defineAuth`, entity schemas, `login`/`register`/`authenticate`/`logout` |
+| `auth.ts` | `defineAuth`, entity schemas, `login`/`register`/`authenticate`/`logout`. Three suites, split at the line ceiling along the three subjects: `auth.test.ts` (the credential flow), `auth-config.test.ts` (`defineAuth`'s defaults and refusals) and `auth-lockout.test.ts` (the tenant and address buckets) |
 | `policy-bridge.ts` | the one funnel: identity → `Actor`, all four `ActorKind`s |
 | `session.ts` | two expiries, rotation, revocation, device list, the cookie |
 | `adapter.ts` | the seam; `builtin-adapter.ts` (Postgres) + `memory-adapter.ts` |
@@ -414,6 +468,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `oauth-exchange.ts` | `oauthCredentials` + the one POST to the token endpoint |
 | `id-token.ts` | id token → claims this handshake may believe |
 | `id-token-fixture.ts` | the one string-input JWT builder the OAuth tests share. Off `index.ts` |
+| `auth-fixture.ts` | the KDF parameters, the password and the `AuthError` catcher the three `auth*.test.ts` suites share. Off `index.ts` |
 | `oauth-profile.ts` | claims or userinfo → one `OAuthProfile` |
 | `oauth-login.ts` | profile → account link → session. `completeOAuthLogin` is the entry point |
 | `oauth-login-fixture.ts` | the adapter, clock and profile the three `oauth-login*` suites share. Off `index.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "16.0.0",
+  "version": "18.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -24,15 +24,15 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "16.0.0",
-    "@ultimat3/db": "16.0.0",
-    "@ultimat3/schema": "16.0.0"
+    "@ultimat3/core": "18.0.0",
+    "@ultimat3/db": "18.0.0",
+    "@ultimat3/schema": "18.0.0"
   }
 }

package/src/auth-fixture.ts

@@ -0,0 +1,26 @@
+// Single responsibility: the three values every credential-flow suite needs — cheap KDF
+// parameters, the password they all sign in with, and the `AuthError` catcher. Three test files
+// share them, and three private copies is three chances for one to drift from what the flow
+// actually enforces. Not part of the public API — `index.ts` deliberately does not re-export it.
+
+import { AuthError } from './errors';
+import type { PasswordParams } from './password';
+
+// Fast KDF parameters: these tests are about the credential flow, not argon2's cost.
+export const FAST_PARAMS: PasswordParams = { algorithm: 'argon2id', memoryCost: 8192, timeCost: 1 };
+
+export const PASSWORD = 'correct-horse-battery-staple-42';
+
+/** Captures the thrown `AuthError`, or `undefined` when the call unexpectedly resolved. The
+ *  caller's `expect(error?.code).toBe(...)` is then the assertion that fails, naming the code it
+ *  wanted — a sentinel thrown from in here would carry no code and no fix. Anything that is not
+ *  an `AuthError` is rethrown untouched: this helper never swallows an unexpected failure. */
+export const caught = async (fn: () => Promise<unknown>): Promise<AuthError | undefined> => {
+  try {
+    await fn();
+    return undefined;
+  } catch (error) {
+    if (error instanceof AuthError) return error;
+    throw error;
+  }
+};

package/src/auth.ts

@@ -18,6 +18,7 @@ import {
   verifyPassword,
 } from './password';
 import { type PolicyActor, resolveActor } from './policy-bridge';
+import { assertPasswordPolicy, assertRateLimitPolicy, assertSessionPolicy } from './policy-numbers';
 import {
   type AuthLimiter,
   type AuthRateLimitPolicy,
@@ -176,6 +177,12 @@ 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 };
+  // Screened on the MERGED policy, before anything is built from it: an override is spread over
+  // defaults the author never restated, so the resolved object is the only one that can be judged
+  // — the same reason `defineHttpConfig` judges the merged `cors` rather than the input.
+  assertSessionPolicy(session);
+  assertPasswordPolicy(password);
+  assertRateLimitPolicy(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

package/src/errors.ts

@@ -216,6 +216,31 @@ export const mfaRequiredUnenforceable = (): AuthError =>
     fix: 'drop required from defineAuth({ mfa }) and gate it in your own sign-in handler, which is where the enrolment route lives: if (user.mfaSecret === null) send them to enrolTotp(auth, { account: user.email }) instead of createSession(auth.sessions, ...)',
   });
 
+/**
+ * A policy NUMBER that is not one, refused where `defineAuth` still names the key.
+ *
+ * Every one of these arrives as `Number(process.env.SESSION_TTL_MS)` as often as a literal, and
+ * that is `NaN` for an unset variable — not nullish, so the spread over the defaults keeps it, and
+ * then every comparison it reaches is false. What that produces is not a short session or a weak
+ * password, it is the RULE not existing: `now >= NaN` is false, so a session never expires on
+ * either clock; `password.length < NaN` is false, so the empty password was accepted. Both were
+ * measured. `X_CONFIG_INVALID` is core's code, borrowed rather than re-declared, beside
+ * `mfaRequiredUnenforceable` above and for the same reason — a declaration this package cannot
+ * honour is not a new kind of failure.
+ */
+export const authPolicyNumberInvalid = (
+  key: string,
+  value: number,
+  expected: string,
+  consequence: string,
+): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause: `defineAuth({ ${key}: ${String(value)} }) is not ${expected}; ${consequence}, so the rule is not enforced at all rather than enforced wrongly — and NaN is what Number(process.env.…) answers for an unset variable`,
+    fix: `pass ${expected} for ${key} in defineAuth, and parse an environment value before you pass it — Number.parseInt(process.env.AUTH_TTL_MS ?? '', 10) is NaN when the variable is unset, so give it a default: Number.parseInt(process.env.AUTH_TTL_MS ?? '2592000000', 10)`,
+    meta: { option: key, value: String(value) },
+  });
+
 export const passwordWeak = (reasons: readonly string[]): AuthError =>
   new AuthError({
     code: 'X_PASSWORD_WEAK',

package/src/jwks.ts

@@ -12,6 +12,7 @@ import { decodeJwtSegment, isRecord } from './json';
 import type { OAuthProvider } from './oauth';
 import { oauthExchangeFailed, oauthTokenInvalid } from './oauth-errors';
 import type { OAuthFetch } from './oauth-exchange';
+import { assertFiniteAuthCount } from './policy-numbers';
 import { base64UrlBytes } from './tokens';
 
 /**
@@ -112,7 +113,19 @@ const algorithmOf = (jwk: Record<string, unknown>): JwtAlgorithm | null => {
 export function createJwksClient(options: JwksClientOptions): JwksKeySource {
   const clock = options.clock ?? systemClock;
   const ttlMs = options.ttlMs ?? DEFAULT_JWKS_TTL_MS;
+  assertFiniteAuthCount(
+    'jwks.ttlMs',
+    ttlMs,
+    '`now >= fetchedAt + NaN` is false, so the key set is never stale and a rotation is never refetched — every login against the new kid fails until the process restarts',
+    1,
+  );
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  assertFiniteAuthCount(
+    'jwks.timeoutMs',
+    timeoutMs,
+    'AbortSignal.timeout throws a bare TypeError on it, several frames below the option that set it, and the single-flight deadline derived from it goes with it',
+    1,
+  );
   let keys = new Map<string, CryptoKey>();
   let fetchedAtMs = Number.NEGATIVE_INFINITY;
   // When the last UNKNOWN-`kid` refresh ran, tracked apart from `fetchedAtMs` because that field

package/src/kdf-gate.ts

@@ -8,6 +8,7 @@
 
 import { createFlightGate } from '@ultimat3/core';
 import { kdfOverloaded } from './errors';
+import { assertFiniteAuthCount } from './policy-numbers';
 
 export interface KdfLimits {
   /** Hashes running at once. Multiply by `memoryCost` for the resident ceiling this buys. */
@@ -43,6 +44,28 @@ export interface KdfGate {
  * are observations no caller here has ever had, and widening a public signature is not a refactor.
  */
 export function createKdfGate(limits: KdfLimits = DEFAULT_KDF_LIMITS): KdfGate {
+  // Screened at the CONSTRUCTOR, because this pair WEDGES rather than fails: core asks
+  // `active < maxConcurrent` and then `waiters.length >= maxQueued`, and both are false for `NaN`,
+  // so every hash on the box parks in a queue with no bound and nothing to release it — login
+  // stops answering instead of shedding.
+  //
+  // ZERO is legitimate at BOTH, which is why the minimum is 0 and not 1: `maxQueued: 0` means
+  // "shed at the width, never wait", and `{ maxConcurrent: 0, maxQueued: 0 }` is a gate that
+  // refuses every hash — `password.test.ts`'s way of proving the unreadable-hash path burns the
+  // same KDF the other two failures do. Refusing zero here would have failed that test, which is
+  // the deployment this screen must not break.
+  assertFiniteAuthCount(
+    'kdf.maxConcurrent',
+    limits.maxConcurrent,
+    '`active < NaN` is false, so no hash ever starts and every caller queues instead',
+    0,
+  );
+  assertFiniteAuthCount(
+    'kdf.maxQueued',
+    limits.maxQueued,
+    '`waiters.length >= NaN` is false, so the queue this gate exists to bound has no bound at all',
+    0,
+  );
   return createFlightGate(limits, {
     overflow: (state) => kdfOverloaded(state.active, state.queued),
   });

package/src/mfa.ts

@@ -3,8 +3,10 @@
 // phishing page stays valid for the rest of its 30 seconds. Recovery codes are hashed at rest
 // and single-use, so a database dump is not a permanent MFA bypass.
 
+import { finiteCount } from '@ultimat3/core';
 import type { Auth } from './auth';
 import { mfaSecretInvalid } from './errors';
+import { assertFiniteAuthCount } from './policy-numbers';
 import { randomBytes, sha256Hex, timingSafeEqual } from './tokens';
 
 const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
@@ -166,7 +168,17 @@ export function verifyTotp(input: VerifyTotpInput): TotpVerification {
   // "this account's secret is malformed" to whoever asked. It also keeps `totpCode`'s refusal off
   // the login path entirely — nothing below can reach it with a zero-length key.
   if (base32Decode(input.secret).length === 0) return { ok: false, step: null };
+  // A LOOP BOUND, screened before it becomes one: measured, `drift: Infinity` never terminates
+  // (`-Infinity + 1` is `-Infinity`) — a synchronous infinite loop on the login path, past every
+  // AbortSignal — and `drift: NaN` makes `-NaN <= NaN` false, so the loop never runs and every
+  // correct code is rejected as if it were wrong. Zero is legitimate: the current step only.
   const drift = input.drift ?? TOTP_DRIFT_STEPS;
+  assertFiniteAuthCount(
+    'mfa.drift',
+    drift,
+    'the verification loop either never terminates (Infinity) or never runs at all (NaN), and the second answers "wrong code" to every correct one',
+    0,
+  );
   const current = totpStep(input.at);
   const candidate = input.code.replaceAll(' ', '');
   for (let offset = -drift; offset <= drift; offset += 1) {
@@ -296,9 +308,21 @@ export interface RecoveryCodeSet {
 const normaliseRecoveryCode = (code: string): string =>
   code.replaceAll('-', '').replaceAll(' ', '').toUpperCase();
 
+/**
+ * `count` is a LOOP BOUND, so it fails in both directions and neither is a smaller set of codes.
+ * `NaN` — what `Number(process.env.RECOVERY_CODES)` answers for an unset variable, and not nullish,
+ * so the default never sees it — makes `index < count` false at once and enrols a user with ZERO
+ * ways back into their account, in a well-formed `{ codes: [], hashes: [] }` that no caller can
+ * tell from a real one. `Infinity` is the other end and it WEDGES: measured, the loop never
+ * terminates, synchronously, on the enrolment path. Same shape as `mfa.drift`.
+ *
+ * `finiteCount` from core rather than `assertFiniteAuthCount`, for the reason `randomToken` gives:
+ * that refusal spells `defineAuth({ <key>: … })` and this is a call-site argument.
+ */
 export function generateRecoveryCodes(count = 10): RecoveryCodeSet {
+  const wanted = finiteCount('generateRecoveryCodes', 'count', count, 1);
   const codes: string[] = [];
-  for (let index = 0; index < count; index += 1) {
+  for (let index = 0; index < wanted; index += 1) {
     const raw = base32Encode(randomBytes(10)).slice(0, 16);
     codes.push(`${raw.slice(0, 4)}-${raw.slice(4, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}`);
   }

package/src/oauth-cookie.ts

@@ -10,6 +10,7 @@ import { EnvMissingError, systemClock } from '@ultimat3/core';
 import type { OAuthHandshake, OAuthProviderId } from './oauth';
 import { oauthStateInvalid } from './oauth-errors';
 import { hasOAuthProvider } from './oauth-registry';
+import { assertFiniteAuthCount } from './policy-numbers';
 import { type RequestLike, readCookie } from './session';
 import { base64Url, timingSafeEqual } from './tokens';
 
@@ -30,6 +31,26 @@ export function handshakeCookieName(provider: OAuthProviderId): string {
 /** Long enough to read a consent screen, short enough that a lifted cookie is already stale. */
 export const DEFAULT_HANDSHAKE_TTL_MS = 10 * 60 * 1000;
 
+/**
+ * One screen for both ends of the deadline, because it is one number bounding two things: the
+ * server comparison in `openHandshake` and the `Max-Age` the browser is asked to honour. `NaN`
+ * switches off both at once and neither says anything — `now - issuedAt > NaN` is false forever,
+ * and `Max-Age=NaN` is not `delta-seconds`, so a browser drops the attribute and keeps the cookie
+ * until the tab closes. What survives is the state, nonce and PKCE verifier that are the CSRF
+ * defence of the callback leg, replayable a year later.
+ *
+ * Screened at every reader rather than once at seal time: the two legs are two HTTP requests and
+ * two calls, so a check on the way out is one the way back never runs.
+ */
+function handshakeTtlMs(options: HandshakeSealOptions | undefined): number {
+  return assertFiniteAuthCount(
+    'oauth.handshake.ttlMs',
+    options?.ttlMs ?? DEFAULT_HANDSHAKE_TTL_MS,
+    'the server-side replay deadline is a comparison that is false for every handshake and the cookie carries a Max-Age no browser keeps, so a lifted handshake stays redeemable',
+    1,
+  );
+}
+
 /** `wiki/Configuration.md` requires it at >=32 chars for the `web` role; this is that gate. */
 const MIN_SECRET_LENGTH = 32;
 
@@ -146,7 +167,7 @@ export function openHandshake(
   // The cookie's own `Max-Age` is the client's copy of this deadline, and a client is free to
   // ignore it — so the age that decides is measured here, against the server's clock.
   const clock = options?.clock ?? systemClock;
-  if (clock.now().getTime() - issuedAt > (options?.ttlMs ?? DEFAULT_HANDSHAKE_TTL_MS)) {
+  if (clock.now().getTime() - issuedAt > handshakeTtlMs(options)) {
     throw oauthStateInvalid(provider, 'the stored handshake expired before the callback arrived');
   }
 
@@ -164,7 +185,7 @@ export function handshakeCookie(
   handshake: OAuthHandshake,
   options?: HandshakeCookieOptions,
 ): string {
-  const maxAge = Math.floor((options?.ttlMs ?? DEFAULT_HANDSHAKE_TTL_MS) / 1000);
+  const maxAge = Math.floor(handshakeTtlMs(options) / 1000);
   // The handshake already names its provider, so the two legs cannot disagree about the name.
   const name = options?.name ?? handshakeCookieName(handshake.provider);
   return `${name}=${sealHandshake(handshake, options)}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;

package/src/oauth-discovery.ts

@@ -8,6 +8,11 @@ import { isRecord } from './json';
 import type { OAuthProvider } from './oauth';
 import { oauthExchangeFailed } from './oauth-errors';
 import type { OAuthFetch } from './oauth-exchange';
+import { assertFiniteAuthCount } from './policy-numbers';
+
+/** Named in the refusal above the one `fetch` this file makes. */
+const TIMEOUT_CONSEQUENCE =
+  'AbortSignal.timeout throws a bare TypeError on it, several frames below the option that set it, so the leg fails with an error that names neither this package nor the option';
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
@@ -50,13 +55,22 @@ export async function discoverOAuthProvider(
 ): Promise<OAuthProvider> {
   const url = discoveryUrl(input.issuer);
   const doFetch: OAuthFetch = input.fetch ?? ((target, init) => globalThis.fetch(target, init));
+  // Screened OUTSIDE the try below, deliberately: `AbortSignal.timeout(NaN)` throws, and the
+  // catch around this fetch renders every throw as a provider failure — so a typo in the app's
+  // own config read as the identity provider being unreachable.
+  const timeoutMs = assertFiniteAuthCount(
+    'oauth.discovery.timeoutMs',
+    input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    TIMEOUT_CONSEQUENCE,
+    1,
+  );
 
   let response: Response;
   try {
     response = await doFetch(url, {
       method: 'GET',
       headers: { Accept: 'application/json' },
-      signal: AbortSignal.timeout(input.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+      signal: AbortSignal.timeout(timeoutMs),
     });
   } catch (error) {
     throw oauthExchangeFailed({

package/src/oauth-exchange.ts

@@ -22,6 +22,7 @@ import {
 } from './oauth';
 import { oauthExchangeFailed, restartAt } from './oauth-errors';
 import { providerFor } from './oauth-registry';
+import { assertFiniteAuthCount } from './policy-numbers';
 
 /** Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to. */
 export type OAuthFetch = (input: string, init: RequestInit) => Promise<Response>;
@@ -29,6 +30,10 @@ export type OAuthFetch = (input: string, init: RequestInit) => Promise<Response>
 /** GitHub answers 403 to a request with no user agent, so every call this package makes has one. */
 export const OAUTH_USER_AGENT = 'ultimate-auth';
 
+/** Named in the refusal above the one `fetch` this file makes. */
+const TIMEOUT_CONSEQUENCE =
+  'AbortSignal.timeout throws a bare TypeError on it, several frames below the option that set it, so the leg fails with an error that names neither this package nor the option';
+
 const DEFAULT_TIMEOUT_MS = 10_000;
 const MAX_DETAIL_LENGTH = 200;
 
@@ -158,6 +163,15 @@ async function postForm(
   options: OAuthExchangeOptions,
 ): Promise<Record<string, unknown>> {
   const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  // Screened OUTSIDE the try below, deliberately: `AbortSignal.timeout(NaN)` throws, and the
+  // catch around this fetch renders every throw as a provider failure — so a typo in the app's
+  // own config read as the identity provider being unreachable.
+  const timeoutMs = assertFiniteAuthCount(
+    'oauth.exchange.timeoutMs',
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    TIMEOUT_CONSEQUENCE,
+    1,
+  );
   const url = providerFor(provider).tokenUrl;
 
   let response: Response;
@@ -171,7 +185,7 @@ async function postForm(
         'User-Agent': OAUTH_USER_AGENT,
       },
       body: body.toString(),
-      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+      signal: AbortSignal.timeout(timeoutMs),
     });
   } catch (error) {
     // The rendered value goes to the LOG, never into the `detail:`.

package/src/oauth-profile.ts

@@ -15,6 +15,11 @@ import {
   providerDetail,
 } from './oauth-exchange';
 import { providerFor } from './oauth-registry';
+import { assertFiniteAuthCount } from './policy-numbers';
+
+/** Named in the refusal above the one `fetch` this file makes. */
+const TIMEOUT_CONSEQUENCE =
+  'AbortSignal.timeout throws a bare TypeError on it, several frames below the option that set it, so the leg fails with an error that names neither this package nor the option';
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
@@ -49,6 +54,15 @@ async function getJson(
   options: OAuthProfileOptions,
 ): Promise<{ ok: true; body: unknown } | { ok: false; status: number; detail: string }> {
   const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  // Screened OUTSIDE the try below, deliberately: `AbortSignal.timeout(NaN)` throws, and the
+  // catch around this fetch renders every throw as a provider failure — so a typo in the app's
+  // own config read as the identity provider being unreachable.
+  const timeoutMs = assertFiniteAuthCount(
+    'oauth.profile.timeoutMs',
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    TIMEOUT_CONSEQUENCE,
+    1,
+  );
   let response: Response;
   try {
     response = await doFetch(url, {
@@ -58,7 +72,7 @@ async function getJson(
         Authorization: `Bearer ${accessToken}`,
         'User-Agent': OAUTH_USER_AGENT,
       },
-      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+      signal: AbortSignal.timeout(timeoutMs),
     });
   } catch (error) {
     // `renderThrowable`, never `error.message` behind an `instanceof`: `fetch` is INJECTED here,

package/src/policy-numbers.ts

@@ -0,0 +1,126 @@
+// Single responsibility: the numeric screen over every option this package bounds anything with —
+// the three policies `defineAuth` resolves, and the runtime options (`jwks`, the OAuth legs, TOTP
+// drift, the limiter's key cap) that arrive on a call rather than through config. One file, because
+// the rule is one rule: a duration, a length and an allowance are all "a whole positive number, and
+// NaN is what an unset environment variable parses to".
+
+import { authPolicyNumberInvalid } from './errors';
+import type { PasswordPolicy } from './password';
+import type { AuthRateLimitPolicy } from './rate-limit';
+import type { SessionPolicy } from './session';
+
+const WHOLE_POSITIVE = 'a whole number greater than zero';
+const WHOLE_NON_NEGATIVE = 'a whole number of zero or more';
+
+/**
+ * `Number.isSafeInteger`, not `Number.isFinite`: these are millisecond durations and attempt
+ * counts, and past 2^53 a double cannot name its own successor — a "duration" up there is already
+ * a rounded one, and `now + it` no longer moves.
+ *
+ * The `Finite` in the name is NOT load-bearing, `As of 2026-08-26`. It was: `bun run
+ * finite-bounds` matched a repair on the callee's NAME, so a screen named `whole` left every call
+ * site reading as unchecked. It now reads `SCREENING_CALLEES` in `scripts/lib/finite-screens.ts`,
+ * so a rename is a row edit rather than a gate failure.
+ */
+export function assertFiniteAuthCount(
+  key: string,
+  value: number,
+  consequence: string,
+  min: 0 | 1,
+): number {
+  if (Number.isSafeInteger(value) && value >= min) return value;
+  throw authPolicyNumberInvalid(
+    key,
+    value,
+    min === 1 ? WHOLE_POSITIVE : WHOLE_NON_NEGATIVE,
+    consequence,
+  );
+}
+
+/** Both clocks and the slide between them. A session that never expires is the failure here. */
+export function assertSessionPolicy(policy: SessionPolicy): void {
+  assertFiniteAuthCount(
+    'session.absoluteTtlMs',
+    policy.absoluteTtlMs,
+    'the absolute expiry becomes an Invalid Date and `now >= NaN` is false, so the session never expires on that clock',
+    1,
+  );
+  assertFiniteAuthCount(
+    'session.idleTtlMs',
+    policy.idleTtlMs,
+    '`now - lastSeenAt >= NaN` is false, so a session idle for years still reports itself live',
+    1,
+  );
+  if (policy.idleSlideMs !== undefined) {
+    assertFiniteAuthCount(
+      'session.idleSlideMs',
+      policy.idleSlideMs,
+      'the write that moves `lastSeenAt` forward is skipped or taken on every single request',
+      0,
+    );
+  }
+}
+
+/** The length rule, and the two KDF costs that decide what a stolen hash is worth. */
+export function assertPasswordPolicy(policy: PasswordPolicy): void {
+  assertFiniteAuthCount(
+    'password.minLength',
+    policy.minLength,
+    '`password.length < NaN` is false for every password, and the two-distinct-characters rule is guarded by `length > 0`, so the EMPTY password is accepted',
+    1,
+  );
+  assertFiniteAuthCount(
+    'password.params.memoryCost',
+    policy.params.memoryCost,
+    'argon2 refuses it several frames below the config line that set it, on the first registration',
+    1,
+  );
+  assertFiniteAuthCount(
+    'password.params.timeCost',
+    policy.params.timeCost,
+    'argon2 refuses it several frames below the config line that set it, on the first registration',
+    1,
+  );
+}
+
+/**
+ * The lockout numbers. These were already refused — by `assertAuthLimiterPolicy`, whose `NaN ===
+ * NaN` comparison fails — but as `X_AUTH_LIMITER_POLICY_MISMATCH`, which tells an operator the
+ * limiter enforces different numbers than the app declared. It does not: the number is a typo.
+ */
+export function assertRateLimitPolicy(policy: AuthRateLimitPolicy): void {
+  assertFiniteAuthCount(
+    'rateLimit.maxAttempts',
+    policy.maxAttempts,
+    '`failures.length >= NaN` is false, so the lockout never engages and guessing is unlimited',
+    1,
+  );
+  assertFiniteAuthCount(
+    'rateLimit.windowMs',
+    policy.windowMs,
+    'every recorded failure falls outside the window immediately, so nothing ever accumulates',
+    1,
+  );
+  assertFiniteAuthCount(
+    'rateLimit.lockoutMs',
+    policy.lockoutMs,
+    '`now < lockedUntil` is false, so a lockout that was established holds nobody',
+    1,
+  );
+  if (policy.orgMaxAttempts !== undefined) {
+    assertFiniteAuthCount(
+      'rateLimit.orgMaxAttempts',
+      policy.orgMaxAttempts,
+      'the tenant bucket never fills, so one org can saturate the shared limiter',
+      1,
+    );
+  }
+  if (policy.maxKeys !== undefined) {
+    assertFiniteAuthCount(
+      'rateLimit.maxKeys',
+      policy.maxKeys,
+      'the in-memory table has no ceiling, so a spray of distinct keys is memory the attacker chooses',
+      1,
+    );
+  }
+}

package/src/rate-limit.ts

@@ -11,6 +11,7 @@ import {
   authLimiterNotShared,
   authLimiterPolicyMismatch,
 } from './errors';
+import { assertFiniteAuthCount } from './policy-numbers';
 
 /**
  * Where a limiter's counters live. A limiter says which it provides; `AuthRateLimitPolicy` says
@@ -157,7 +158,15 @@ export function createAuthLimiter(
   policy: AuthRateLimitPolicy = DEFAULT_AUTH_RATE_LIMIT,
 ): MemoryAuthLimiter {
   const buckets = new Map<string, Bucket>();
-  const maxKeys = Math.max(1, Math.floor(policy.maxKeys ?? DEFAULT_MAX_AUTH_LIMIT_KEYS));
+  // Screened, not clamped: `Math.floor(NaN)` is `NaN`, so `buckets.size > maxKeys` is false and
+  // the sweep that bounds this table never runs. Half these keys are attacker-chosen (`ipKey`),
+  // which is what makes the ceiling the only thing between a spray and this process's memory.
+  const maxKeys = assertFiniteAuthCount(
+    'rateLimit.maxKeys',
+    policy.maxKeys ?? DEFAULT_MAX_AUTH_LIMIT_KEYS,
+    'the in-memory table has no ceiling, so a spray of distinct keys is memory the attacker chooses',
+    1,
+  );
   const evictTo = Math.max(1, Math.floor(maxKeys * 0.9));
   let lastSweepMs = Number.NEGATIVE_INFINITY;
 

package/src/session.ts

@@ -7,6 +7,7 @@
 import type { Clock } from '@ultimat3/core';
 import type { AuthSession, SessionStore } from './adapter';
 import { sessionExpired, sessionUnknown } from './errors';
+import { assertFiniteAuthCount } from './policy-numbers';
 import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
 
 export interface SessionPolicy {
@@ -230,6 +231,13 @@ export interface SessionCookieOptions {
  * - `SameSite=Lax` — not attached to cross-site POSTs, which is CSRF's whole mechanism.
  * - `Path=/`, no `Domain` — required by `__Host-`; a sibling subdomain cannot set or read it.
  * - `Max-Age`   — the client drops it at the absolute expiry, matching the server's ceiling.
+ *
+ * The two numbers behind that last attribute are screened here rather than merged first, because
+ * they are two different options and an error naming the one the caller did not pass is a `fix:`
+ * nobody can follow. `Max-Age` is `delta-seconds` — digits — so `NaN`, `Infinity` and `1.5` are
+ * attributes a browser DISCARDS: the cookie then lives until the tab closes, which is the client
+ * half of the session ceiling gone with no error anywhere. Zero is legitimate and stays legal, at
+ * both ends: it means "expire now", which is exactly what `clearSessionCookie` emits.
  */
 export function sessionCookie(
   token: string,
@@ -237,7 +245,22 @@ export function sessionCookie(
   options?: SessionCookieOptions,
 ): string {
   const name = options?.name ?? policy.cookieName;
-  const maxAge = options?.maxAgeSeconds ?? Math.floor(policy.absoluteTtlMs / 1000);
+  const maxAge =
+    options?.maxAgeSeconds === undefined
+      ? Math.floor(
+          assertFiniteAuthCount(
+            'session.absoluteTtlMs',
+            policy.absoluteTtlMs,
+            'the cookie carries `Max-Age=NaN`, which is not delta-seconds, so the browser drops the attribute and keeps the session cookie for the whole browsing session',
+            1,
+          ) / 1000,
+        )
+      : assertFiniteAuthCount(
+          'session.cookie.maxAgeSeconds',
+          options.maxAgeSeconds,
+          'the cookie carries an attribute that is not delta-seconds, so the browser drops it and keeps the session cookie for the whole browsing session',
+          0,
+        );
   return `${name}=${token}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
 }
 

package/src/tokens.ts

@@ -5,7 +5,7 @@
 // exact same one, and re-exporting it here keeps every existing `from '@ultimat3/auth'` import
 // working.
 
-import { timingSafeEqual } from '@ultimat3/core';
+import { finiteCount, timingSafeEqual } from '@ultimat3/core';
 
 export { timingSafeEqual };
 
@@ -24,9 +24,22 @@ export function base64Url(bytes: Uint8Array): string {
   return btoa(binary).replace(BASE64URL_UNSAFE, (char) => BASE64URL_REPLACEMENTS[char] ?? '');
 }
 
-/** 32 bytes -> 43 base64url chars. Opaque by construction: it encodes nothing about the user. */
+/**
+ * 32 bytes -> 43 base64url chars. Opaque by construction: it encodes nothing about the user.
+ *
+ * The default is not a screen — `??` guards nullish and `NaN` is not nullish — and
+ * `new Uint8Array(NaN)` is a zero-length array rather than a throw, so
+ * `randomToken(Number(process.env.TOKEN_BYTES))` on an unset variable answered `''`: the function
+ * whose entire job is an unguessable secret returning the empty string, with nothing said.
+ * `-1` was a bare uncoded `RangeError` out of the package. `min: 1`, because a zero-byte token is
+ * that same empty string — not a weak secret, no secret.
+ *
+ * `finiteCount` from core rather than this package's `assertFiniteAuthCount`: that one's refusal
+ * spells the edit `defineAuth({ <key>: … })` (`errors.ts`), and there is no `defineAuth` key here —
+ * the edit is at the call site, and a `fix:` naming a file that cannot hold it is worse than none.
+ */
 export function randomToken(byteLength = 32): string {
-  return base64Url(randomBytes(byteLength));
+  return base64Url(randomBytes(finiteCount('randomToken', 'byteLength', byteLength, 1)));
 }
 
 /**

package/src/verify.ts

@@ -7,6 +7,7 @@ import type { Clock } from '@ultimat3/core';
 import type { AuthVerification, VerificationStore } from './adapter';
 import { normaliseEmail } from './email';
 import { AuthError } from './errors';
+import { assertFiniteAuthCount } from './policy-numbers';
 import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
 
 /**
@@ -67,7 +68,18 @@ export async function issueVerification(
 ): Promise<IssuedVerification> {
   const now = runtime.clock.now();
   const token = randomToken(32);
-  const ttl = input.ttlMs ?? DEFAULT_VERIFICATION_TTL_MS[input.purpose];
+  // Screened HERE, above the write, not beside the `Date` it feeds. Unscreened this threw a bare
+  // `RangeError` out of the package — `new Date(now + NaN)` is an Invalid Date and `toISOString()`
+  // refuses one — on the line after `putVerification` had already resolved. The row survived the
+  // failure with an expiry `consumeVerification` reads as `now >= NaN`, which is false for ever:
+  // a reset link that never expires. And because the write upserts on `(purpose, identifier)`, it
+  // had replaced whatever live token that address held on its way to failing.
+  const ttl = assertFiniteAuthCount(
+    'verification.ttlMs',
+    input.ttlMs ?? DEFAULT_VERIFICATION_TTL_MS[input.purpose],
+    'the stored expiry is an Invalid Date, `now >= NaN` is false, and the mailed link is a password that never expires',
+    1,
+  );
   const expiresAt = new Date(now.getTime() + ttl);
   // The FOURTH identity door, and the one that did not normalise: `register`, `login`,
   // `profileEmail` and `accountKey` all do. `putVerification` upserts on `(purpose, identifier)`