@ultimat3/auth 8.0.0 → 10.0.0

package/src/oauth-route.ts

@@ -8,12 +8,18 @@
 // is tier 4 and describes a rendered page. A bare `Request` in, a `Response` out, drivable from
 // a test and mountable by any router that can match a `:param`.
 
-import { type Clock, isUltimateError, renderThrowable, type UltimateError } from '@ultimat3/core';
+import {
+  type Clock,
+  isUltimateError,
+  logger,
+  renderThrowable,
+  type UltimateError,
+} from '@ultimat3/core';
 import type { Auth, LoginResult } from './auth';
-import { oauthDenied, oauthExchangeFailed, oauthProviderUnknown } from './errors';
 import { beginOAuth, type OAuthProviderId } from './oauth';
 import { BUILTIN_OAUTH_PROVIDER_IDS } from './oauth-builtins';
 import { clearHandshakeCookie, handshakeCookie, readHandshakeCookie } from './oauth-cookie';
+import { oauthDenied, oauthExchangeFailed, oauthProviderUnknown } from './oauth-errors';
 import type { OAuthClientCredentials, OAuthFetch } from './oauth-exchange';
 import { oauthCredentials } from './oauth-exchange';
 import { completeOAuthLogin, type ResolveOAuthGrants } from './oauth-login';
@@ -101,6 +107,24 @@ export const OAUTH_ROUTE_STATUS: Readonly<Record<string, number>> = {
   X_CONFIG_INVALID: 500,
 };
 
+/**
+ * The status for a code, read as an OWN key of the table above.
+ *
+ * `OAUTH_ROUTE_STATUS[code] ?? 502` is an index read on a plain object, so `Object.prototype`
+ * answered for `toString`, `constructor`, `hasOwnProperty` and `__proto__` — and `toString`
+ * yields a FUNCTION, which was handed straight to `ResponseInit.status`. `code` is a plain
+ * `string` on every `UltimateError`, so no cast makes that unreachable. Fourth instance of the
+ * class in the framework, after i18n's catalog lookup, schema's `coerce` and mcp's `validate-args`.
+ *
+ * Exported so a test can drive it without building a `Response`; `OAUTH_ROUTE_STATUS` stays
+ * exported unchanged, because `scripts/oauth-route-status.test.ts` pins it against
+ * `@ultimat3/http`'s `statusFor`.
+ */
+export function oauthRouteStatus(code: string): number {
+  // 502 is the default: an uncoded throw on this path came out of the provider conversation.
+  return Object.hasOwn(OAUTH_ROUTE_STATUS, code) ? (OAUTH_ROUTE_STATUS[code] ?? 502) : 502;
+}
+
 /**
  * What an anonymous caller is allowed to read. `UltimateError.toJSON()` carries `meta` and `stack`
  * — a developer's fields — and BOTH legs of this flow are public by definition, so serialising it
@@ -122,26 +146,42 @@ const publicBody = (coded: UltimateError): Record<string, string> => ({
  * wants a rendered page wraps these two descriptors; the framework ships the debuggable answer.
  */
 function problem(error: unknown, extraCookies: readonly string[]): Response {
-  const coded = isUltimateError(error)
-    ? error
-    : oauthExchangeFailed({
-        provider: 'oauth',
-        stage: 'token',
-        // `renderThrowable`, never `error.message`: the throw came from an adapter or a `fetch`
-        // this package does not own, and a getter on `message` — or a `Proxy` trapping
-        // `getPrototypeOf` — would make the callback's last answer throw instead of send.
-        detail: renderThrowable(error),
-        fix: 'throw an UltimateError from the AuthAdapter or OAuthFetch that failed — the factories are in packages/auth/src/errors.ts',
-      });
+  const coded = isUltimateError(error) ? error : uncoded(error);
   const headers = new Headers({ 'content-type': 'application/json; charset=utf-8' });
   for (const cookie of extraCookies) headers.append('set-cookie', cookie);
   return new Response(JSON.stringify(publicBody(coded)), {
-    // 502 is the default: an uncoded throw on this path came out of the provider conversation.
-    status: OAUTH_ROUTE_STATUS[coded.code] ?? 502,
+    status: oauthRouteStatus(coded.code),
     headers,
   });
 }
 
+/**
+ * A throw with no code: a bug in an `AuthAdapter` or an `OAuthFetch` this package does not own.
+ *
+ * Its text goes to the LOG and never into the response. `publicBody` publishes `cause`, and the
+ * rendered value went straight into it — so a bare
+ * `Error('connect ECONNREFUSED 10.4.2.17:5432 (postgres://app:hunter2@db.internal/prod)')` from a
+ * pool inside a callback was served to whoever typed the URL, as a 502 with the connection string
+ * in the body. The comment above `publicBody` says a stack and `meta` must never reach that
+ * reader; the field carrying the message was the one exception nobody meant to make.
+ *
+ * `renderThrowable`, never `error.message`: the value came from code this package does not own,
+ * and a getter on `message` — or a `Proxy` trapping `getPrototypeOf` — would make the callback's
+ * last answer throw instead of send. Same shape `rate-limit.ts`'s `loginFailed()` uses: one fixed
+ * sentence outward, the discriminating detail kept where only an operator can read it.
+ */
+function uncoded(error: unknown): UltimateError {
+  logger.error('auth.oauth.uncoded_failure', { detail: renderThrowable(error) });
+  return oauthExchangeFailed({
+    provider: 'oauth',
+    stage: 'token',
+    detail:
+      'an adapter or fetch this package does not own threw a value with no error code; the ' +
+      'detail is in this process log under auth.oauth.uncoded_failure',
+    fix: 'throw an UltimateError from the AuthAdapter or OAuthFetch that failed — the factories are in packages/auth/src/errors.ts, and the OAuth ones in packages/auth/src/oauth-errors.ts',
+  });
+}
+
 /** `/auth/oauth/github` → `github`; `/auth/oauth/github/callback` → `github`. */
 function providerSegment(request: Request, leg: 'start' | 'callback'): string {
   const segments = new URL(request.url).pathname.split('/').filter((s) => s.length > 0);
@@ -173,6 +213,37 @@ function assertEnabled(auth: Auth, segment: string): OAuthProviderId {
   return provider;
 }
 
+/**
+ * The credentials for a provider, or the SAME 404 an unknown provider gets.
+ *
+ * `assertEnabled` collapses "never heard of it" and "not enabled here" into one answer so an
+ * anonymous caller cannot enumerate this deployment's configuration. Past it, `oauthCredentials`
+ * threw `X_ENV_MISSING` and `problem()` answered 500 — publishing the app's own environment
+ * variable names in the `cause` and, worse, restoring the oracle: 500 meant "registered here",
+ * 404 meant "not". A provider with no credentials is not usable, which is the only thing this
+ * caller is entitled to learn.
+ *
+ * The real cause is not lost: `X_ENV_MISSING`'s `cause` and `fix` are the operator's, and they go
+ * to the process log where only an operator can read them.
+ */
+function credentialsFor(
+  provider: OAuthProviderId,
+  options: OAuthLoginOptions,
+): OAuthClientCredentials {
+  if (options.credentials !== undefined) return options.credentials;
+  try {
+    return oauthCredentials(provider, options.env ?? Bun.env);
+  } catch (error) {
+    if (!isUltimateError(error) || error.code !== 'X_ENV_MISSING') throw error;
+    logger.error('auth.oauth.credentials_missing', {
+      provider,
+      cause: error.cause,
+      fix: error.fix,
+    });
+    throw oauthProviderUnknown(provider, BUILTIN_OAUTH_PROVIDER_IDS);
+  }
+}
+
 function originFor(request: Request, options: OAuthLoginOptions): string {
   const env = options.env ?? Bun.env;
   const declared = options.baseUrl ?? env['APP_URL']?.trim() ?? '';
@@ -195,7 +266,7 @@ async function startHandler(
 ): Promise<Response> {
   try {
     const provider = assertEnabled(auth, providerSegment(request, 'start'));
-    const credentials = options.credentials ?? oauthCredentials(provider, options.env ?? Bun.env);
+    const credentials = credentialsFor(provider, options);
     const handshake = beginOAuth({
       provider,
       clientId: credentials.clientId,
@@ -233,6 +304,10 @@ async function callbackHandler(
   const clear = hasOAuthProvider(segment) ? [clearHandshakeCookie(segment)] : [];
   try {
     const provider = assertEnabled(auth, segment);
+    // Asked here purely so a provider with no credentials answers 404 on THIS leg too: the
+    // exchange below resolves them again from the same two sources. One oracle, closed on both
+    // halves — a 404 on start and a 500 on callback is the same enumeration one request later.
+    credentialsFor(provider, options);
     const url = new URL(request.url);
     assertNoProviderError(url, provider);
     const result: LoginResult = await completeOAuthLogin(auth, {

package/src/oauth.ts

@@ -4,7 +4,7 @@
 // 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 { oauthStateInvalid } from './oauth-errors';
 import { providerFor } from './oauth-registry';
 import { base64Url, randomToken, sha256Bytes, timingSafeEqual } from './tokens';
 

package/src/rate-limit.ts

@@ -85,6 +85,13 @@ export interface AuthLimiter {
   recordSuccess(key: string): Promise<void>;
   lockedUntil(key: string): Promise<Date | null>;
   reset(): Promise<void>;
+  /**
+   * Drop every expired row this limiter is keeping, and answer how many went. Optional because a
+   * limiter that bounds itself has nothing to sweep — `createAuthLimiter` evicts on write, so it
+   * omits this and `purgeAuthLimits()` skips it. A limiter backed by a table declares it, and
+   * that is what makes the framework's purge job able to reach one without knowing it is Postgres.
+   */
+  purgeExpired?(): Promise<number>;
 }
 
 /** What `createAuthLimiter` returns: the interface, plus the bound it keeps, observable. */

package/src/tables.ts

@@ -1,6 +1,29 @@
 // Single responsibility: the DDL `BuiltinAdapter` expects. Exported as plain strings so an app
-// can paste them into a migration and read exactly what auth stores — no column holds a
-// plaintext secret, and that is meant to be verifiable by reading, not by trusting.
+// can paste them into a migration and read EXACTLY what auth stores — verifiable by reading,
+// never by trusting.
+//
+// What is at rest, stated column by column rather than as a claim:
+//
+// | Column | Holds |
+// |---|---|
+// | `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_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.
+//
+// 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
+// (`oauth-login.ts`'s `accountFor`). The columns stay so an app that deliberately stores tokens
+// through its own `linkAccount` has somewhere to put them, and so an existing deployment needs
+// no migration to stop.
 
 export const X_USERS_TABLE = `create table if not exists x_users (
   id                    uuid primary key,
@@ -12,6 +35,8 @@ 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.
   mfa_secret            text,
   recovery_code_hashes  text[] not null default '{}',
   disabled_at           timestamptz,
@@ -52,6 +77,8 @@ export const X_ACCOUNTS_TABLE = `create table if not exists x_accounts (
   user_id               uuid not null references x_users (id) on delete cascade,
   provider              text not null,
   provider_account_id   text not null,
+  -- Written NULL by the framework. Nothing reads them back, and a live provider credential at
+  -- rest turns a database dump into third-party access. Kept for an app's own linkAccount().
   access_token          text,
   refresh_token         text,
   expires_at            timestamptz,

package/src/verify.ts

@@ -5,6 +5,7 @@
 
 import type { Clock } from '@ultimat3/core';
 import type { AuthVerification, VerificationStore } from './adapter';
+import { normaliseEmail } from './email';
 import { AuthError } from './errors';
 import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
 
@@ -68,10 +69,17 @@ export async function issueVerification(
   const token = randomToken(32);
   const ttl = input.ttlMs ?? DEFAULT_VERIFICATION_TTL_MS[input.purpose];
   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)`
+  // and `adapter.ts` promises that "issuing a new token invalidates the previous one" — a promise
+  // that was per SPELLING, so N live reset tokens for one address could be held at once by varying
+  // the case, and each one of them is a password. It is also the address the mail is sent to, so
+  // the link goes to the inbox the account is keyed by rather than to whatever a form posted.
+  const identifier = normaliseEmail(input.identifier);
   await runtime.store.putVerification({
     id: randomToken(12),
     purpose: input.purpose,
-    identifier: input.identifier,
+    identifier,
     tokenHash: sha256Hex(token),
     expiresAt,
     consumedAt: null,
@@ -79,7 +87,7 @@ export async function issueVerification(
   });
   await runtime.mail.send(
     VERIFICATION_TEMPLATES[input.purpose],
-    input.identifier,
+    identifier,
     {
       ...(input.data ?? {}),
       link: input.link?.(token) ?? token,
@@ -119,7 +127,13 @@ export async function consumeVerification(
   input: ConsumeVerificationInput,
 ): Promise<AuthVerification> {
   const tokenHash = sha256Hex(input.token);
-  const record = await runtime.store.takeVerification(input.purpose, input.identifier, tokenHash);
+  // Normalised on the way OUT as well as in, or a link issued for `ada@x.test` is unredeemable by
+  // a form that posted `Ada@X.test` — one door, one key.
+  const record = await runtime.store.takeVerification(
+    input.purpose,
+    normaliseEmail(input.identifier),
+    tokenHash,
+  );
   if (record === null) throw verificationInvalid(input.purpose);
   // Kept for the seam, not for the blessed adapters: `VerificationStore` is implementable by an
   // app, and one that ignores the third argument would otherwise redeem any token. Constant-time