@ultimat3/auth 1.1.0 → 2.0.0

package/src/oauth.ts

@@ -1,9 +1,11 @@
 // Single responsibility: the OAuth2/OIDC handshake. PKCE is mandatory rather than
 // provider-dependent — an authorization code with no proof-of-possession is stealable from a
 // redirect, and "this provider does not need it" is how that becomes a real incident. Provider
-// configs are pure data: importing this file performs no network I/O and reads no env.
+// configs are pure data and live in `oauth-registry.ts`: importing this file performs no network
+// I/O and reads no env.
 
 import { oauthStateInvalid } from './errors';
+import { providerFor } from './oauth-registry';
 import { base64Url, randomToken, sha256Bytes, timingSafeEqual } from './tokens';
 
 export interface OAuthProvider {
@@ -18,67 +20,37 @@ export interface OAuthProvider {
    * token. A list rather than one string because Google has issued both forms for years.
    */
   readonly issuers: readonly string[];
+  /**
+   * Where this provider publishes the keys its id tokens are signed with. `null` for a provider
+   * that issues no id token (GitHub). A provider with a key set can have a token from it verified
+   * on a channel that is not the token endpoint — IdP-initiated login, `form_post`, back-channel
+   * logout — which is what `jwks.ts` and `verifyIdToken({ keys })` exist for.
+   */
+  readonly jwksUri: string | null;
   readonly scopes: readonly string[];
-  readonly usesPkce: boolean;
+  /**
+   * The literal `true`, not `boolean`. A provider config saying `usesPkce: false` was always
+   * invalid — an authorization code with no proof-of-possession is stealable from a redirect —
+   * and a comment saying so is not a build error. This is, and it deletes every downstream
+   * `if (provider.usesPkce)` branch along with the state it could ever have been false in.
+   *
+   * It stays the literal now that `registerOAuthProvider` is open to any app: the mechanism this
+   * package exists to own has to survive the opening, so an app cannot register a PKCE-less IdP.
+   */
+  readonly usesPkce: true;
   /** OIDC providers echo `nonce` in the id token; it binds the token to this browser. */
   readonly usesNonce: boolean;
   readonly clientIdEnv: string;
   readonly clientSecretEnv: string;
 }
 
-export const OAUTH_PROVIDERS = {
-  github: {
-    id: 'github',
-    authorizeUrl: 'https://github.com/login/oauth/authorize',
-    tokenUrl: 'https://github.com/login/oauth/access_token',
-    userInfoUrl: 'https://api.github.com/user',
-    // GitHub omits a private address from the profile; the identity is still incomplete
-    // without it, so the flow asks for the verified list rather than guessing.
-    userEmailsUrl: 'https://api.github.com/user/emails',
-    issuers: [],
-    scopes: ['read:user', 'user:email'],
-    usesPkce: true,
-    usesNonce: false,
-    clientIdEnv: 'GITHUB_CLIENT_ID',
-    clientSecretEnv: 'GITHUB_CLIENT_SECRET',
-  },
-  google: {
-    id: 'google',
-    authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
-    tokenUrl: 'https://oauth2.googleapis.com/token',
-    // Reached only when a narrowed `scopes` leaves the id token without an email claim.
-    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
-    userEmailsUrl: null,
-    issuers: ['https://accounts.google.com', 'accounts.google.com'],
-    scopes: ['openid', 'email', 'profile'],
-    usesPkce: true,
-    usesNonce: true,
-    clientIdEnv: 'GOOGLE_CLIENT_ID',
-    clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
-  },
-  apple: {
-    id: 'apple',
-    authorizeUrl: 'https://appleid.apple.com/auth/authorize',
-    tokenUrl: 'https://appleid.apple.com/auth/token',
-    // Apple returns claims in the id token only; there is no userinfo endpoint to call.
-    userInfoUrl: null,
-    userEmailsUrl: null,
-    issuers: ['https://appleid.apple.com'],
-    scopes: ['name', 'email'],
-    usesPkce: true,
-    usesNonce: true,
-    clientIdEnv: 'APPLE_CLIENT_ID',
-    // Apple alone does not accept a static secret: `APPLE_CLIENT_SECRET` must hold the ES256
-    // client-secret JWT signed with the .p8 key, which Apple expires every six months.
-    clientSecretEnv: 'APPLE_CLIENT_SECRET',
-  },
-} as const satisfies Readonly<Record<string, OAuthProvider>>;
-
-export type OAuthProviderId = keyof typeof OAUTH_PROVIDERS;
-
-export const OAUTH_PROVIDER_IDS: readonly OAuthProviderId[] = Object.freeze(
-  Object.keys(OAUTH_PROVIDERS) as OAuthProviderId[],
-);
+/**
+ * Any registered provider's id — `string`, not a closed union, since 1.3.0. The union of three
+ * consumer IdPs made an enterprise OP unrepresentable at the type level, which is a constraint no
+ * configuration can escape. `providerFor(id)` is the runtime check that replaces it, and it
+ * throws the same `X_OAUTH_PROVIDER_UNKNOWN` the route already answered with.
+ */
+export type OAuthProviderId = string;
 
 export interface PkcePair {
   readonly verifier: string;
@@ -115,7 +87,7 @@ export interface BeginOAuthInput {
 }
 
 export function beginOAuth(input: BeginOAuthInput): OAuthHandshake {
-  const provider = OAUTH_PROVIDERS[input.provider];
+  const provider = providerFor(input.provider);
   const pkce = createPkce();
   const state = randomToken(16);
   const nonce = randomToken(16);
@@ -155,11 +127,12 @@ export interface OAuthCallback {
  * tells an attacker which half to keep guessing at.
  */
 export function assertOAuthCallback(handshake: OAuthHandshake, callback: OAuthCallback): void {
-  const provider = OAUTH_PROVIDERS[handshake.provider];
+  const provider = providerFor(handshake.provider);
   if (!timingSafeEqual(handshake.state, callback.state)) {
     throw oauthStateInvalid(provider.id, 'state did not match the stored handshake');
   }
-  if (provider.usesPkce && handshake.verifier.length < 43) {
+  // Unconditional: `usesPkce` is the literal `true`, so there is no provider to exempt.
+  if (handshake.verifier.length < 43) {
     throw oauthStateInvalid(provider.id, 'no PKCE verifier was stored for this handshake');
   }
   if (callback.nonce !== undefined && !timingSafeEqual(handshake.nonce, callback.nonce)) {

package/src/password.ts

@@ -4,6 +4,7 @@
 // otherwise response time answers "is this email registered?" for free.
 
 import { passwordWeak } from './errors';
+import { kdfGate } from './kdf-gate';
 
 export interface PasswordParams {
   readonly algorithm: 'argon2id';
@@ -57,15 +58,24 @@ const COMMON_PASSWORDS: ReadonlySet<string> = new Set([
   'correcthorse',
 ]);
 
+/**
+ * Through `kdfGate()`, like every other KDF call here: 19 MiB of arena per hash and no per-source
+ * limiter that an IPv6 /64 cannot walk around means the ONLY thing bounding argon2 memory on this
+ * box is this gate. Past its queue it refuses with `X_OVERLOADED`, the same shed http's `admit`
+ * stage performs — a refusal that costs one comparison, not one arena.
+ */
 export async function hashPassword(
   password: string,
   params: PasswordParams = DEFAULT_PASSWORD_PARAMS,
 ): Promise<string> {
-  return await Bun.password.hash(password, {
-    algorithm: params.algorithm,
-    memoryCost: params.memoryCost,
-    timeCost: params.timeCost,
-  });
+  return await kdfGate().run(
+    async () =>
+      await Bun.password.hash(password, {
+        algorithm: params.algorithm,
+        memoryCost: params.memoryCost,
+        timeCost: params.timeCost,
+      }),
+  );
 }
 
 /** Reads the parameters back out of a PHC string. `null` means "not a hash we recognise". */
@@ -103,13 +113,15 @@ export interface VerifyPasswordInput {
  */
 export async function verifyPassword(input: VerifyPasswordInput): Promise<PasswordVerification> {
   const params = input.params ?? DEFAULT_PASSWORD_PARAMS;
-  if (input.hash === null) {
+  // Read into a local so the closure below narrows without a cast.
+  const hash = input.hash;
+  if (hash === null) {
     await hashPassword(input.password, params);
     return FAILED;
   }
-  const ok = await Bun.password.verify(input.password, input.hash);
+  const ok = await kdfGate().run(async () => await Bun.password.verify(input.password, hash));
   if (!ok) return FAILED;
-  return { ok: true, needsRehash: needsRehash(input.hash, params) };
+  return { ok: true, needsRehash: needsRehash(hash, params) };
 }
 
 export interface StrengthOptions {

package/src/policy-bridge.ts

@@ -38,12 +38,18 @@ const withPermissions = (actor: Actor, permissions: readonly string[]): PolicyAc
 });
 
 /**
- * A human. Roles come from the row and are expanded to permissions by policy; scopes stay
- * empty because a browser session is not scope-limited — the role set is the limit.
+ * A human. Roles come from the row and are expanded to permissions by policy; scopes come from
+ * the row too, and they are almost always empty.
+ *
+ * `scopes: []` used to be hardcoded here, which made a scope a thing no human could ever hold —
+ * so `hasScope(actor, 'tenancy:cross')`, whose own reasons name "an admin surface listing every
+ * org" and "support tooling", could only ever be satisfied by minting a `serviceActor` inside the
+ * handler. That discards the operator's identity and makes the sweep unattributable, which is the
+ * exact property the scope's required reason string exists to preserve.
  *
  * A session that has not satisfied an enrolled second factor resolves to an actor with no
- * roles and no permissions rather than an error, so a half-authenticated request can still
- * reach the "finish MFA" route and nothing else. Login throws `X_MFA_REQUIRED` separately.
+ * roles, no permissions and no scopes rather than an error, so a half-authenticated request can
+ * still reach the "finish MFA" route and nothing else. Login throws `X_MFA_REQUIRED` separately.
  */
 export function actorFromUser(user: AuthUser, session: AuthSession): PolicyActor {
   const mfaPending = user.mfaSecret !== null && !session.mfaSatisfied;
@@ -52,7 +58,7 @@ export function actorFromUser(user: AuthUser, session: AuthSession): PolicyActor
       id: user.id,
       orgId: user.orgId ?? undefined,
       roles: mfaPending ? [] : user.roles,
-      scopes: [],
+      scopes: mfaPending ? [] : user.scopes,
     }),
     mfaPending ? [] : user.permissions,
   );

package/src/privileges.ts

@@ -0,0 +1,74 @@
+// Single responsibility: changing what a user may do, and rotating the credential that was issued
+// under the old answer. `packages/auth/CLAUDE.md` has listed "rotate the session id on any
+// privilege change (`rotateSession`)" as a non-negotiable since 1.0, and
+// `SessionPolicy.rotateOnPrivilegeChange` has defaulted `true` — while `rotateSession` had no
+// caller anywhere outside its own test and the flag was read by nothing. Per axiom 3 the rule did
+// not exist. This is the caller that makes it exist.
+
+import type { AuthUser, UserPatch } from './adapter';
+import type { Auth } from './auth';
+import { authWriteFailed } from './errors';
+import { type IssuedSession, rotateSession, sessionCookie } from './session';
+
+/**
+ * The fields whose change invalidates whatever the current cookie was issued under. `roles`,
+ * `permissions` and `scopes` are what an actor is built from; `passwordHash` is the credential
+ * itself; `orgId` moves every tenant-scoped read the session can perform.
+ */
+const PRIVILEGE_FIELDS = ['roles', 'permissions', 'scopes', 'orgId', 'passwordHash'] as const;
+
+export interface UpdatePrivilegesResult {
+  readonly user: AuthUser;
+  /**
+   * The replacement session, present only when a current session was passed AND a privilege field
+   * actually changed. Set `cookie` on the response — the old id is already deleted, so a caller
+   * that drops this signs the user out rather than leaving a stale-privilege cookie live.
+   */
+  readonly session?: IssuedSession | undefined;
+  readonly cookie?: string | undefined;
+  /** Which of `PRIVILEGE_FIELDS` the patch actually named. Empty means nothing rotated. */
+  readonly changed: readonly string[];
+}
+
+const changedFields = (patch: UserPatch): readonly string[] =>
+  PRIVILEGE_FIELDS.filter((field) => patch[field] !== undefined);
+
+/**
+ * Apply the patch, then mint a new session id for the caller's own session when the patch touched
+ * privilege. Rotation is not about propagation — `authenticate` re-reads the user row on every
+ * request, so a revoked role takes effect on the very next one with no token-expiry lag, which is
+ * a better property than any claims-in-a-JWT design. It is about fixation: whoever planted or
+ * lifted the old cookie before the grant must not inherit the grant with it.
+ *
+ * `session` is optional because the common caller is an admin changing somebody ELSE's roles, and
+ * there is no cookie of theirs to rotate. That case wants `revokeUserSessions()` instead, and the
+ * two are deliberately separate calls — silently killing an operator's own session mid-request is
+ * not something a role edit should decide on its own.
+ */
+export async function updatePrivileges(
+  auth: Auth,
+  userId: string,
+  patch: UserPatch,
+  session?: IssuedSession['session'] | undefined,
+): Promise<UpdatePrivilegesResult> {
+  const user = await auth.adapter.updateUser(userId, patch);
+  if (user === null) throw authWriteFailed('updateUser', 'x_users');
+
+  const changed = changedFields(patch);
+  if (
+    changed.length === 0 ||
+    session === undefined ||
+    session.userId !== userId ||
+    !auth.sessions.policy.rotateOnPrivilegeChange
+  ) {
+    return { user, changed };
+  }
+
+  const issued = await rotateSession(auth.sessions, session);
+  return {
+    user,
+    changed,
+    session: issued,
+    cookie: sessionCookie(issued.token, auth.sessions.policy),
+  };
+}

package/src/rate-limit.ts

@@ -4,68 +4,198 @@
 // bypassable. `loginFailed()` lives here so the throttle and the message can never drift apart.
 
 import type { Clock } from '@ultimat3/core';
-import { AuthError, accountLocked } from './errors';
+import { normaliseEmail } from './email';
+import {
+  AuthError,
+  accountLocked,
+  authLimiterNotShared,
+  authLimiterPolicyMismatch,
+} from './errors';
+
+/**
+ * Where a limiter's counters live. A limiter says which it provides; `AuthRateLimitPolicy` says
+ * which the deployment requires, and the two are checked against each other once, at `defineAuth`.
+ */
+export type AuthLimiterScope = 'process' | 'shared';
+
+/**
+ * Hard bound on tracked keys. A key is one identity — `account:<email>` or `ip:<addr>` — so the
+ * natural cardinality is lower than `@ultimat3/http`'s per-route buckets, and so is the cap.
+ */
+export const DEFAULT_MAX_AUTH_LIMIT_KEYS = 10_000;
 
 export interface AuthRateLimitPolicy {
   /** Failures inside `windowMs` before the key is locked. */
   readonly maxAttempts: number;
   readonly windowMs: number;
   readonly lockoutMs: number;
+  /**
+   * The third bucket: failures inside `windowMs` against one TENANT, across every member and
+   * every source address. Per-IP buckets each grant their own quota and per-account buckets
+   * protect one person, so a misconfigured integration spraying one org's logins from 400
+   * addresses is capped by neither — it saturates the shared limiter and every other tenant's
+   * logins slow down behind it.
+   *
+   * A separate number and not `maxAttempts`, because a whole tenant sharing five attempts is a
+   * denial of service against that tenant. Defaults to `maxAttempts * ORG_ATTEMPT_FACTOR`.
+   */
+  readonly orgMaxAttempts?: number | undefined;
+  /** Bound on the in-memory table. Defaults to `DEFAULT_MAX_AUTH_LIMIT_KEYS`. */
+  readonly maxKeys?: number | undefined;
+  /**
+   * What this deployment requires of the limiter. `'shared'` says `maxAttempts` is the whole
+   * fleet's allowance, and a per-process limiter then refuses to build — because N replicas each
+   * counting their own failures let an account survive `maxAttempts × N` guesses, and a lockout
+   * one replica established is invisible to the rest.
+   */
+  readonly scope: AuthLimiterScope;
 }
 
+/** One tenant is worth this many individuals' allowances before it is throttled as a tenant. */
+export const ORG_ATTEMPT_FACTOR = 20;
+
 export const DEFAULT_AUTH_RATE_LIMIT: AuthRateLimitPolicy = Object.freeze({
   maxAttempts: 5,
   windowMs: 15 * 60 * 1000,
   lockoutMs: 15 * 60 * 1000,
+  orgMaxAttempts: 5 * ORG_ATTEMPT_FACTOR,
+  maxKeys: DEFAULT_MAX_AUTH_LIMIT_KEYS,
+  // One process is the only thing this package can promise without being told.
+  scope: 'process',
 });
 
+/**
+ * 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.
+ */
 export interface AuthLimiter {
-  /** Throws `X_ACCOUNT_LOCKED` if the key is inside a lockout. Call before any KDF work. */
-  assertAllowed(key: string): void;
-  recordFailure(key: string): void;
+  /**
+   * The limits this limiter actually enforces, including where it keeps its counters. Stated
+   * rather than assumed, because `defineAuth` compares it against the app's declaration: a
+   * limiter counting to 50 under a policy that says 5 makes `Auth.rateLimit` a number the
+   * 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>;
   /** A success clears the window: a legitimate user is not punished for a typo yesterday. */
-  recordSuccess(key: string): void;
-  lockedUntil(key: string): Date | null;
-  reset(): void;
+  recordSuccess(key: string): Promise<void>;
+  lockedUntil(key: string): Promise<Date | null>;
+  reset(): Promise<void>;
 }
 
-export const accountKey = (email: string): string => `account:${email.trim().toLowerCase()}`;
+/** What `createAuthLimiter` returns: the interface, plus the bound it keeps, observable. */
+export interface MemoryAuthLimiter extends AuthLimiter {
+  readonly size: number;
+}
+
+/**
+ * The SAME normalisation the lookup uses, from the one declaration — a bucket keyed differently
+ * from the row it protects hands a sprayer a fresh attempt budget per spelling of one address.
+ */
+export const accountKey = (email: string): string => `account:${normaliseEmail(email)}`;
 
 export const ipKey = (ip: string): string => `ip:${ip}`;
 
+/**
+ * The tenant bucket's key shape, declared here even though the general noisy-neighbour case lives
+ * 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}`;
+
+/**
+ * The policy the tenant limiter enforces — the same window and lockout, a wider allowance. One
+ * derivation, read by `defineAuth` when it builds the limiter and again when it checks an
+ * injected one, so the two cannot disagree about what was declared.
+ */
+export function orgRateLimit(policy: AuthRateLimitPolicy): AuthRateLimitPolicy {
+  return {
+    ...policy,
+    maxAttempts: policy.orgMaxAttempts ?? policy.maxAttempts * ORG_ATTEMPT_FACTOR,
+  };
+}
+
 interface Bucket {
   failures: number[];
   lockedUntilMs: number;
+  /**
+   * The instant this entry becomes indistinguishable from a missing one: the window has emptied
+   * and any lockout has expired, so it answers exactly as a first-ever attempt does.
+   */
+  forgetAtMs: number;
 }
 
+/** An idle limiter still sweeps this often, so one spray's state does not sit until the next. */
+const SWEEP_EVERY_MS = 60_000;
+
 /**
  * Sliding window over an injected `Clock` — never `Date.now()`, so a lockout test is
  * deterministic instead of a sleep. In-memory per process; a multi-process deployment passes
  * a shared implementation of the same interface.
+ *
+ * Bounded, because half the keys are attacker-chosen: `ipKey` mints one per source address, so
+ * a spray from an IPv6 /64 is a fresh key per attempt and an unbounded map is an OOM. Two rules
+ * keep it flat. An entry whose window has emptied and whose lockout has expired is *forgotten*,
+ * not evicted — it answers exactly as a missing one, so dropping it changes no decision. Only if
+ * that is not enough does the cap evict live state, and then the entries nearest to being
+ * forgotten anyway go first: a locked account is the last key to go, so filling the table is not
+ * a way to buy back attempts against one.
  */
 export function createAuthLimiter(
   clock: Clock,
   policy: AuthRateLimitPolicy = DEFAULT_AUTH_RATE_LIMIT,
-): AuthLimiter {
+): MemoryAuthLimiter {
   const buckets = new Map<string, Bucket>();
+  const maxKeys = Math.max(1, Math.floor(policy.maxKeys ?? DEFAULT_MAX_AUTH_LIMIT_KEYS));
+  const evictTo = Math.max(1, Math.floor(maxKeys * 0.9));
+  let lastSweepMs = Number.NEGATIVE_INFINITY;
 
   const bucketFor = (key: string): Bucket => {
     const existing = buckets.get(key);
     if (existing !== undefined) return existing;
-    const fresh: Bucket = { failures: [], lockedUntilMs: 0 };
+    const fresh: Bucket = { failures: [], lockedUntilMs: 0, forgetAtMs: 0 };
     buckets.set(key, fresh);
     return fresh;
   };
 
+  const sweep = (nowMs: number): void => {
+    lastSweepMs = nowMs;
+    for (const [key, bucket] of buckets) {
+      if (bucket.forgetAtMs <= nowMs) buckets.delete(key);
+    }
+    if (buckets.size <= maxKeys) return;
+    // Batched down to `evictTo` so this sort is paid once per 10% of the cap, not per failure.
+    // A live lockout outranks its deadline: two entries recorded a second apart are otherwise
+    // ordered by recency, which would let a spray evict the account it just locked.
+    const locked = (bucket: Bucket): number => (bucket.lockedUntilMs > nowMs ? 1 : 0);
+    const nearestForgotten = [...buckets.entries()].sort(
+      (a, b) => locked(a[1]) - locked(b[1]) || a[1].forgetAtMs - b[1].forgetAtMs,
+    );
+    for (const [key] of nearestForgotten) {
+      if (buckets.size <= evictTo) break;
+      buckets.delete(key);
+    }
+  };
+
   return {
-    assertAllowed(key) {
+    // The resolved policy, not the argument: `maxKeys` is normalized above, and a limiter that
+    // reported an unresolved bound would be reporting something it does not enforce.
+    policy: { ...policy, maxKeys, scope: 'process' },
+    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));
     },
-    recordFailure(key) {
+    async recordFailure(key) {
       const nowMs = clock.now().getTime();
       const bucket = bucketFor(key);
       bucket.failures = bucket.failures.filter((at) => at > nowMs - policy.windowMs);
@@ -73,21 +203,54 @@ export function createAuthLimiter(
       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 —
+      // 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);
     },
-    recordSuccess(key) {
+    async recordSuccess(key) {
       buckets.delete(key);
     },
-    lockedUntil(key) {
+    async lockedUntil(key) {
       const bucket = buckets.get(key);
       if (bucket === undefined || bucket.lockedUntilMs <= clock.now().getTime()) return null;
       return new Date(bucket.lockedUntilMs);
     },
-    reset() {
+    async reset() {
       buckets.clear();
     },
   };
 }
 
+/**
+ * The numbers a limiter is compared on. `maxKeys` is absent deliberately: it bounds one process'
+ * table, so a shared limiter has no opinion on it and comparing it would refuse a correct pairing.
+ */
+const ENFORCED_LIMITS = ['maxAttempts', 'windowMs', 'lockoutMs'] as const;
+
+/**
+ * At `defineAuth`, never at the first login. Two ways the declared policy and the limiter in use
+ * can disagree, and both end the same way — an operator reading `Auth.rateLimit` and believing a
+ * number nothing enforces:
+ *
+ * - a per-node limiter under a `'shared'` declaration is a lockout worth `maxAttempts × replicas`;
+ * - a limiter counting to its own numbers makes every other field of the policy decorative.
+ *
+ * The declaration stays the app's — this package cannot see how many processes the image runs,
+ * and inferring it would be wrong the first time the app scaled — so the framework's job is to
+ * refuse the pairing, not to guess either half of it.
+ */
+export function assertAuthLimiterPolicy(declared: AuthRateLimitPolicy, limiter: AuthLimiter): void {
+  if (declared.scope === 'shared' && limiter.policy.scope !== 'shared') {
+    throw authLimiterNotShared(limiter.policy.scope);
+  }
+  for (const field of ENFORCED_LIMITS) {
+    if (declared[field] !== limiter.policy[field]) {
+      throw authLimiterPolicyMismatch(field, declared[field], limiter.policy[field]);
+    }
+  }
+}
+
 /**
  * The single generic failure. Every credential path — unknown email, wrong password, disabled
  * account, unverified address — throws exactly this object shape, so the rendered error is

package/src/revocation.ts

@@ -0,0 +1,100 @@
+// Single responsibility: taking a credential away, at the three blast radii an incident actually
+// has — one person, one tenant, everything issued before an instant. `deleteOtherSessions` was the
+// only one of the three the seam could express, so "kill every session in this org, now" was a
+// per-user loop over an enumeration the adapter could not do, or a `TRUNCATE` that killed every
+// other tenant with it. Doing nothing meant thirty days, which is the absolute TTL.
+
+import { logger } from '@ultimat3/core';
+import type { AuthUser } from './adapter';
+import type { Auth } from './auth';
+import { authNotImplemented, authWriteFailed } from './errors';
+
+/**
+ * Every revocation is logged before it runs, with the reason the caller gave. An incident review
+ * asks "who killed these sessions and why" and a `delete` with no line answers neither; the reason
+ * is a required argument for the same rule `crossTenant()` requires one.
+ */
+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);
+}
+
+/**
+ * Every session held by every member of one org. The 03:00 answer to a confirmed credential
+ * compromise in one tenant, and the one thing the seam could not express at all.
+ */
+export async function revokeOrgSessions(
+  auth: Auth,
+  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);
+}
+
+/**
+ * Everything minted before an instant. The sweep that follows a rotated `SESSION_SECRET` or a
+ * suspected dump: it needs no enumeration of users, so it is the one that works when the list of
+ * affected accounts is exactly what is not known yet.
+ */
+export async function revokeSessionsCreatedBefore(
+  auth: Auth,
+  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);
+}
+
+export interface DisabledUser {
+  readonly user: AuthUser;
+  readonly sessionsRevoked: 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.
+ *
+ * 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.
+ */
+export async function disableUser(
+  auth: Auth,
+  userId: string,
+  reason: string,
+): Promise<DisabledUser> {
+  const user = await auth.adapter.updateUser(userId, { disabledAt: auth.clock.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) };
+}
+
+/** The inverse. No sessions are restored — a re-enabled account signs in again, deliberately. */
+export async function enableUser(auth: Auth, userId: string): Promise<AuthUser | null> {
+  return await auth.adapter.updateUser(userId, { disabledAt: null });
+}