@ultimat3/auth 23.0.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';