@ultimat3/auth 22.15.0 → 24.0.0

package/src/rate-limit.ts

@@ -10,6 +10,7 @@ import {
   accountLocked,
   authLimiterNotShared,
   authLimiterPolicyMismatch,
+  ORG_KEY_PREFIX,
 } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
 
@@ -65,11 +66,22 @@ export const DEFAULT_AUTH_RATE_LIMIT: AuthRateLimitPolicy = Object.freeze({
   scope: 'process',
 });
 
+/** One counted attempt, as `reserve` took it — what `refund` gives back, and nothing else. */
+export interface AuthReservation {
+  readonly key: string;
+  /** The limiter's own clock at the take. It identifies the entry inside the window. */
+  readonly atMs: number;
+}
+
 /**
  * Async on every member, so a shared implementation can exist at all: a lockout that holds across
  * replicas is a network round trip, and a synchronous signature has no way to wait for one. The
  * in-memory limiter below answers immediately — the cost is one already-settled promise per call,
  * on a path that is about to run a KDF.
+ *
+ * The allowance is RESERVED, never checked: `reserve` counts the attempt in the same step that
+ * decides whether it may run, so N concurrent guesses spend N of the allowance before any of them
+ * reaches the KDF. A check followed later by a record let every one of them pass the check.
  */
 export interface AuthLimiter {
   /**
@@ -79,9 +91,18 @@ export interface AuthLimiter {
    * operator reads and nothing enforces.
    */
   readonly policy: AuthRateLimitPolicy;
-  /** Rejects with `X_ACCOUNT_LOCKED` if the key is inside a lockout. Call before any KDF work. */
-  assertAllowed(key: string): Promise<void>;
-  recordFailure(key: string): Promise<void>;
+  /**
+   * Count one attempt against the key, atomically, BEFORE any KDF work. Rejects with
+   * `X_ACCOUNT_LOCKED` — counting nothing — while the key is inside a lockout; the attempt that
+   * fills the window is admitted and starts the lockout. A failed attempt needs no further call:
+   * the reservation IS the recorded failure.
+   */
+  reserve(key: string): Promise<AuthReservation>;
+  /**
+   * Give one reservation back — the attempt succeeded, or never reached a verdict. Removes that
+   * one entry and lifts a lockout the window no longer justifies. Never clears the key.
+   */
+  refund(reservation: AuthReservation): Promise<void>;
   /** A success clears the window: a legitimate user is not punished for a typo yesterday. */
   recordSuccess(key: string): Promise<void>;
   lockedUntil(key: string): Promise<Date | null>;
@@ -113,7 +134,7 @@ export const ipKey = (ip: string): string => `ip:${ip}`;
  * in `@ultimat3/http` and `@ultimat3/jobs`: three limiters that spell one tenant three ways cannot
  * be read together during an incident.
  */
-export const orgKey = (orgId: string): string => `org:${orgId}`;
+export const orgKey = (orgId: string): string => `${ORG_KEY_PREFIX}${orgId}`;
 
 /**
  * The policy the tenant limiter enforces — the same window and lockout, a wider allowance. One
@@ -204,25 +225,38 @@ export function createAuthLimiter(
     get size() {
       return buckets.size;
     },
-    async assertAllowed(key) {
-      const bucket = buckets.get(key);
-      if (bucket === undefined) return;
-      const nowMs = clock.now().getTime();
-      if (bucket.lockedUntilMs <= nowMs) return;
-      throw accountLocked(key, Math.ceil((bucket.lockedUntilMs - nowMs) / 1000));
-    },
-    async recordFailure(key) {
+    // No `await` anywhere in the body: the check and the count are one synchronous step, which
+    // is the whole guarantee — concurrent callers are admitted one at a time, in order.
+    async reserve(key) {
       const nowMs = clock.now().getTime();
+      const existing = buckets.get(key);
+      if (existing !== undefined && existing.lockedUntilMs > nowMs) {
+        throw accountLocked(key, Math.ceil((existing.lockedUntilMs - nowMs) / 1000));
+      }
       const bucket = bucketFor(key);
       bucket.failures = bucket.failures.filter((at) => at > nowMs - policy.windowMs);
       bucket.failures.push(nowMs);
       if (bucket.failures.length >= policy.maxAttempts) {
         bucket.lockedUntilMs = nowMs + policy.lockoutMs;
       }
-      // The newest failure leaves the window last, so that is the earliest this entry is free —
+      // The newest attempt leaves the window last, so that is the earliest this entry is free —
       // unless a lockout outlives it. Recorded here because this is the only growth path.
       bucket.forgetAtMs = Math.max(bucket.lockedUntilMs, nowMs + policy.windowMs);
       if (buckets.size > maxKeys || nowMs - lastSweepMs >= SWEEP_EVERY_MS) sweep(nowMs);
+      return { key, atMs: nowMs };
+    },
+    async refund(reservation) {
+      const bucket = buckets.get(reservation.key);
+      if (bucket === undefined) return;
+      const index = bucket.failures.indexOf(reservation.atMs);
+      if (index < 0) return;
+      bucket.failures.splice(index, 1);
+      const nowMs = clock.now().getTime();
+      const live = bucket.failures.filter((at) => at > nowMs - policy.windowMs).length;
+      // A lockout this reservation completed is not one the remaining failures justify.
+      if (live < policy.maxAttempts) bucket.lockedUntilMs = 0;
+      if (bucket.failures.length === 0 && bucket.lockedUntilMs === 0)
+        buckets.delete(reservation.key);
     },
     async recordSuccess(key) {
       buckets.delete(key);

package/src/revocation.ts

@@ -7,7 +7,7 @@
 import { logger } from '@ultimat3/core';
 import type { AuthUser } from './adapter';
 import type { Auth } from './auth';
-import { authNotImplemented, authWriteFailed } from './errors';
+import { authWriteFailed } from './errors';
 
 /**
  * Every revocation is logged before it runs, with the reason the caller gave. An incident review
@@ -18,22 +18,14 @@ const record = (operation: string, scope: string, reason: string): void => {
   logger.warn('auth.revocation', { operation, scope, reason });
 };
 
-const unsupported = (method: string, adapterName: string) =>
-  authNotImplemented(
-    `${adapterName}.${method}()`,
-    `implement ${method}() on your AuthAdapter — BuiltinAdapter (Postgres) and MemoryAdapter are the two reference implementations, in packages/auth/src`,
-  );
-
 /** Every session this user holds, their current one included. Returns how many died. */
 export async function revokeUserSessions(
   auth: Auth,
   userId: string,
   reason: string,
 ): Promise<number> {
-  const remove = auth.adapter.deleteSessionsForUser?.bind(auth.adapter);
-  if (remove === undefined) throw unsupported('deleteSessionsForUser', auth.adapter.name);
   record('revokeUserSessions', userId, reason);
-  return await remove(userId);
+  return await auth.adapter.deleteSessionsForUser(userId);
 }
 
 /**
@@ -45,10 +37,8 @@ export async function revokeOrgSessions(
   orgId: string,
   reason: string,
 ): Promise<number> {
-  const remove = auth.adapter.deleteSessionsForOrg?.bind(auth.adapter);
-  if (remove === undefined) throw unsupported('deleteSessionsForOrg', auth.adapter.name);
   record('revokeOrgSessions', orgId, reason);
-  return await remove(orgId);
+  return await auth.adapter.deleteSessionsForOrg(orgId);
 }
 
 /**
@@ -61,37 +51,47 @@ export async function revokeSessionsCreatedBefore(
   before: Date,
   reason: string,
 ): Promise<number> {
-  const remove = auth.adapter.deleteSessionsCreatedBefore?.bind(auth.adapter);
-  if (remove === undefined) throw unsupported('deleteSessionsCreatedBefore', auth.adapter.name);
   record('revokeSessionsCreatedBefore', before.toISOString(), reason);
-  return await remove(before);
+  return await auth.adapter.deleteSessionsCreatedBefore(before);
 }
 
 export interface DisabledUser {
   readonly user: AuthUser;
   readonly sessionsRevoked: number;
+  /** Live api keys this user owned, now revoked. A key is the owner's credential too. */
+  readonly apiKeysRevoked: number;
 }
 
 /**
- * `disabledAt` is read by `login`, by `authenticate` and by the OAuth path — and until this
- * function existed, no code path anywhere ever SET it. Offboarding was an UPDATE somebody typed.
+ * `disabledAt` is read by `login`, by `authenticate`, by `verifyApiKey` and by the OAuth path.
+ *
+ * Stamping the column is not enough on its own: every one of those readers re-reads the user row,
+ * so a disabled account stops working on its next request, but the live session rows are still
+ * there and still slide, and the api keys still read as live in every listing. Both go in the
+ * same call, in that order — stamp first, so a request racing the revocation finds the row
+ * already disabled. Re-enabling restores neither.
  *
- * Stamping the column is not enough on its own: `authenticate` re-reads the user row on every
- * request, so a disabled account stops working on its next request, but the live session row is
- * still there and still slides. The sessions go in the same call, in that order — stamp first, so
- * a request racing the revocation finds the row already disabled.
+ * The log line is written before the first write, as every revocation's is: an incident review
+ * must find the reason even when the write that followed it failed.
  */
 export async function disableUser(
   auth: Auth,
   userId: string,
   reason: string,
 ): Promise<DisabledUser> {
-  const user = await auth.adapter.updateUser(userId, { disabledAt: auth.clock.now() });
+  record('disableUser', userId, reason);
+  const now = auth.clock.now();
+  const user = await auth.adapter.updateUser(userId, { disabledAt: now });
   // No row came back: either there is no such user, or the adapter did not return the update.
   // Both mean the account is not known to be disabled, and reporting success would be a lie.
   if (user === null) throw authWriteFailed('updateUser', 'x_users');
-  record('disableUser', userId, reason);
-  return { user, sessionsRevoked: await revokeUserSessions(auth, userId, reason) };
+  const sessionsRevoked = await auth.adapter.deleteSessionsForUser(userId);
+  let apiKeysRevoked = 0;
+  for (const key of await auth.adapter.listApiKeys(userId)) {
+    if (key.revokedAt !== null) continue;
+    if (await auth.adapter.revokeApiKey(key.id, now)) apiKeysRevoked += 1;
+  }
+  return { user, sessionsRevoked, apiKeysRevoked };
 }
 
 /** The inverse. No sessions are restored — a re-enabled account signs in again, deliberately. */

package/src/session.ts

@@ -5,6 +5,7 @@
 // to them without this package importing it (same-tier packages must not depend on each other).
 
 import type { Clock } from '@ultimat3/core';
+import { readCookie } from '@ultimat3/core';
 import type { AuthSession, SessionStore } from './adapter';
 import { sessionExpired, sessionUnknown } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
@@ -278,36 +279,9 @@ export function clearSessionCookie(policy: SessionPolicy, name?: string): string
 }
 
 /**
- * The one `Cookie:` parser in this package — the oauth handshake reads through it too, so it never
- * throws: a missing or unreadable cookie is `null` or the raw value, never an exception.
+ * The session token off the request, through core's `readCookie` — the oauth handshake reads
+ * through the same one, so neither throws: a missing or unreadable cookie is `null` or the raw value.
  */
-export function readCookie(request: RequestLike, name: string): string | null {
-  const header = request.headers.get('cookie');
-  if (header === null) return null;
-  for (const part of header.split(';')) {
-    const equals = part.indexOf('=');
-    if (equals < 0) continue;
-    if (part.slice(0, equals).trim() !== name) continue;
-    return decodeCookieValue(part.slice(equals + 1).trim());
-  }
-  return null;
-}
-
-/**
- * A `Cookie:` header is attacker-controlled, and `decodeURIComponent('%')` throws a bare
- * `URIError` — which escapes every coded path that reads through here: an OAuth callback would
- * answer 500 instead of `X_OAUTH_STATE_INVALID`. The raw value is returned instead, so the
- * caller's own rejection stays the readable failure. Nothing is loosened by it: a raw value is
- * still checked against a signature or a stored hash, and neither matches a mangled one.
- */
-function decodeCookieValue(raw: string): string {
-  try {
-    return decodeURIComponent(raw);
-  } catch {
-    return raw;
-  }
-}
-
 export function readSessionCookie(request: RequestLike, policy: SessionPolicy): string | null {
-  return readCookie(request, policy.cookieName);
+  return readCookie(request.headers.get('cookie'), policy.cookieName);
 }

package/src/tables.ts

@@ -9,16 +9,15 @@
 // |---|---|
 // | `x_users.password_hash` | an argon2id digest, never the password |
 // | `x_users.recovery_code_hashes` | SHA-256 digests, never the codes (`mfa.ts`) |
-// | `x_users.mfa_secret` | **the base32 TOTP seed, in the clear** — see below |
+// | `x_users.mfa_secret` | the TOTP seed SEALED under the app's master key (`mfa-secret.ts`) |
 // | `x_accounts.access_token` / `refresh_token` | **nothing.** The framework writes `null` |
 // | `x_sessions.*`, `x_verifications.token_hash` | digests and metadata, never a token |
 //
-// `mfa_secret` is the one plaintext secret this schema still holds, and it is stated here rather
-// than glossed: a TOTP seed is symmetric, so verifying a code requires the seed itself and a
-// digest cannot replace it. Encrypting it needs a key-management seam this package does not have,
-// which is a design change and not a patch — DEFERRED, deliberately, and written down so nobody
-// reads the header above as covering it. `mfa.ts`'s "a database dump is not a permanent MFA
-// bypass" is true of the recovery CODES and not of the seed.
+// `mfa_secret` cannot be a digest: a TOTP seed is symmetric, so verifying a code needs the seed
+// itself. It is sealed with `purpose: 'auth:x_users.mfa_secret'`, written by `saveTotpSecret` and
+// opened by `openTotpSecret`, which REFUSES a value that is not sealed (`X_MFA_SECRET_UNSEALED`).
+// The column type is unchanged, so there is no DDL to upgrade — a row written before sealing is
+// sealed in place by `x auth seal-mfa`, once.
 //
 // The two `x_accounts` token columns are kept in the DDL and written `null`: they held live
 // provider credentials in the clear and nothing in this package ever read them back
@@ -36,8 +35,7 @@ export const X_USERS_TABLE = `create table if not exists x_users (
   permissions           text[] not null default '{}',
   scopes                text[] not null default '{}',
   external_id           text unique,
-  -- The base32 TOTP seed, in the clear. A seed is symmetric: a digest cannot verify a code.
-  -- Encryption at rest is deferred and needs a key-management seam - see the header.
+  -- The TOTP seed, sealed (x1.<keyId>.<iv>.<ciphertext>). Never base32 in the clear.
   mfa_secret            text,
   recovery_code_hashes  text[] not null default '{}',
   disabled_at           timestamptz,

package/src/verify.ts

@@ -1,7 +1,7 @@
 // Single responsibility: email verification and password reset — the two flows where a link in
 // an inbox is a credential. Tokens are single-use, expiring, stored hashed and compared in
-// constant time. Mail leaves through an injected `MailSender` port: the app wires
-// `@ultimat3/mail`'s `send` into it, because auth must not depend on a sideways tier-3 package.
+// constant time. Mail leaves through an injected structural `MailSender` port: `@ultimat3/mail` is
+// tier 4 and auth is tier 2, so the app wires mail's `send` in and auth imports nothing upward.
 
 import type { Clock } from '@ultimat3/core';
 import type { AuthVerification, VerificationStore } from './adapter';

package/src/auth-fixture.ts

@@ -1,26 +0,0 @@
-// 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/id-token-fixture.ts

@@ -1,20 +0,0 @@
-// Single responsibility: the one way this package's tests mint an id token. Three OAuth test
-// files each needs a base64url-encoded JWT, and three private copies of the encoder is three
-// chances for one to drift from what `decodeIdToken` actually parses. Not part of the public
-// API — `index.ts` deliberately does not re-export it.
-
-import type { IdTokenClaims } from './id-token';
-import { base64Url } from './tokens';
-
-/** `base64Url` takes bytes because every real secret is bytes; a JWT segment is text. */
-export const base64UrlText = (value: string): string => base64Url(new TextEncoder().encode(value));
-
-/**
- * Header, payload, and a signature that is not one. Signatures are never checked here — the
- * token is only ever read straight off the token endpoint — so a fixture needs no signer.
- */
-// The union, and not `Record<string, unknown>` alone: `IdTokenClaims` is an `interface`, so it has
-// no implicit index signature and the one shape this fixture exists to serialise was the one shape
-// it refused. The record arm stays for the malformed payloads `id-token.test.ts` builds by hand.
-export const unsignedJwt = (claims: IdTokenClaims | Readonly<Record<string, unknown>>): string =>
-  `${base64UrlText('{"alg":"RS256"}')}.${base64UrlText(JSON.stringify(claims))}.signature`;

package/src/oauth-login-fixture.ts

@@ -1,53 +0,0 @@
-// The fixtures the three `oauth-login` suites share: the frozen instant, a fresh
-// `MemoryAdapter`-backed `Auth`, the two request bodies, the code of a rejection and a JSON
-// `Response`. Shared rather than copied — three suites building their own `Auth` would be three
-// flows that agree only by construction, the same reason `backfill-pass-fixture.ts` exists.
-
-import { frozenClock, isUltimateError } from '@ultimat3/core';
-import { type Auth, defineAuth } from './auth';
-import { MemoryAdapter } from './memory-adapter';
-import type { OAuthTokens } from './oauth-exchange';
-import type { OAuthProfile } from './oauth-profile';
-
-export const NOW = new Date('2026-08-09T12:00:00.000Z');
-
-export const credentials = { clientId: 'client-id', clientSecret: 'client-secret' };
-
-/** One adapter and the `Auth` over it, minted per `beforeEach` — never shared between tests. */
-export const freshAuth = (): { adapter: MemoryAdapter; auth: Auth } => {
-  const adapter = new MemoryAdapter();
-  return {
-    adapter,
-    auth: defineAuth({ adapter, clock: frozenClock(NOW), providers: ['github', 'google'] }),
-  };
-};
-
-export const profile = (overrides: Partial<OAuthProfile> = {}): OAuthProfile => ({
-  provider: 'github',
-  providerAccountId: '583231',
-  email: 'ada@example.com',
-  emailVerified: true,
-  name: 'Ada Lovelace',
-  ...overrides,
-});
-
-export const tokens = (overrides: Partial<OAuthTokens> = {}): OAuthTokens => ({
-  accessToken: 'gho_first',
-  refreshToken: null,
-  expiresAt: null,
-  idToken: null,
-  claims: null,
-  ...overrides,
-});
-
-export const codeOf = async (call: Promise<unknown>): Promise<string> => {
-  try {
-    await call;
-  } catch (error) {
-    return isUltimateError(error) ? error.code : `not-an-UltimateError: ${String(error)}`;
-  }
-  return 'did-not-throw';
-};
-
-export const json = (body: unknown): Response =>
-  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' } });