@ultimat3/auth 23.0.0 → 25.0.0

package/src/oauth-grant-context.ts

@@ -0,0 +1,106 @@
+// Single responsibility: what `resolveGrants` may read besides the profile (#670). An IdP is free
+// to put authorization facts — groups, entitlements, `allowed_oauth_apps` — on `/userinfo` only,
+// or in an id-token claim `OAuthProfile` does not name; a seam that sees the profile alone refuses
+// a correctly granted user. The token set, the whole verified payload, and a lazy userinfo read.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import { decodeJwtSegment } from './json';
+import type { OAuthProviderId } from './oauth';
+import { oauthExchangeFailed } from './oauth-errors';
+import type { OAuthTokens } from './oauth-exchange';
+import { oauthStartPath } from './oauth-paths';
+import {
+  type OAuthProfile,
+  type OAuthProfileOptions,
+  userinfoAccountId,
+  userinfoBody,
+} from './oauth-profile';
+import { providerFor } from './oauth-registry';
+
+/** The second argument of `resolveGrants`. Read-only, and alive for one callback only. */
+export interface OAuthGrantContext {
+  readonly provider: OAuthProviderId;
+  /**
+   * The exchange's token set, in flight. The framework persists none of it (`accountFor` writes
+   * `null`), so an app that keeps a token past this call has chosen to store a credential.
+   */
+  readonly tokens: OAuthTokens;
+  /**
+   * Every claim of the id token the exchange VERIFIED — custom ones (`hd`, `groups`) included,
+   * which `tokens.claims` drops. `null` when the provider issued no id token.
+   */
+  readonly idTokenClaims: Readonly<Record<string, unknown>> | null;
+  /**
+   * The provider's userinfo answer, every claim, read with the access token. At most one request
+   * per login, however often it is asked: none at all when the profile was already read off
+   * userinfo (GitHub), whose body is handed back; a failed read is not remembered.
+   * A body naming another subject is `X_OAUTH_EXCHANGE_FAILED` — the same rule `oauthProfile`
+   * applies, so a grant can never be read off somebody else's identity.
+   */
+  userinfo(): Promise<Readonly<Record<string, unknown>>>;
+}
+
+/** The verified token's payload, whole. Its signature, `iss`, `aud` and `exp` were checked already. */
+function fullPayload(tokens: OAuthTokens): Readonly<Record<string, unknown>> | null {
+  if (tokens.claims === null || tokens.idToken === null) return null;
+  const payload = decodeJwtSegment(tokens.idToken.split('.')[1] ?? '');
+  return payload === null ? null : Object.freeze(payload);
+}
+
+async function readUserinfo(
+  profile: OAuthProfile,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions,
+): Promise<Readonly<Record<string, unknown>>> {
+  const { provider } = profile;
+  // Asked before `userinfoBody`, whose own refusal for this case speaks of a missing identity:
+  // here the identity is proven, and what is missing is the endpoint the app's rule reads.
+  if (providerFor(provider).userInfoUrl === null) {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'userinfo',
+      detail: `${provider} publishes no userinfo endpoint, so resolveGrants cannot read one`,
+      fix: `resolveGrants: (profile, { idTokenClaims }) => grantsFrom(idTokenClaims)   # ${provider} puts its claims in the id token, never behind context.userinfo()`,
+    });
+  }
+  const body = await userinfoBody(provider, tokens, options);
+  if (userinfoAccountId(body) !== profile.providerAccountId) {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'userinfo',
+      detail: 'the userinfo subject is not the subject of the identity being signed in',
+      fix: `registerOAuthProvider({ id: ${renderFixLiteral(provider, '<id>')}, userInfoUrl: '<the provider's own userinfo endpoint>', … })   # a proxy that rewrites sub is refused; then restart at ${oauthStartPath(provider)}`,
+    });
+  }
+  return Object.freeze(body);
+}
+
+/**
+ * Built once per callback, after the profile is proven and before `resolveGrants` runs. `fetched`
+ * is the userinfo body the profile read already made, if it made one — its subject IS the profile's.
+ */
+export function oauthGrantContext(
+  profile: OAuthProfile,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions,
+  fetched: Record<string, unknown> | null = null,
+): OAuthGrantContext {
+  let pending: Promise<Readonly<Record<string, unknown>>> | undefined =
+    fetched === null ? undefined : Promise.resolve(Object.freeze(fetched));
+  return Object.freeze({
+    provider: profile.provider,
+    tokens,
+    idTokenClaims: fullPayload(tokens),
+    userinfo() {
+      if (pending === undefined) {
+        const read = readUserinfo(profile, tokens, options);
+        pending = read;
+        // Forget a failure, so a seam that retries asks the provider again rather than the cache.
+        read.catch(() => {
+          if (pending === read) pending = undefined;
+        });
+      }
+      return pending;
+    },
+  });
+}

package/src/oauth-login.ts

@@ -3,19 +3,14 @@
 // matter which door the user came through. `completeOAuthLogin` is the blessed entry point;
 // the three steps under it are exported because a custom flow needs the seams, not a second path.
 
-import { ConfigInvalidError, logger, uuid } from '@ultimat3/core';
+import { ConfigInvalidError, logger, uuidV7 } from '@ultimat3/core';
 import type { AuthAccount, AuthUser } from './adapter';
 import type { Auth, LoginResult } from './auth';
 import { normaliseEmail } from './email';
-import { authWriteFailed, mfaRequired } from './errors';
+import { AuthError, authWriteFailed } from './errors';
+import { mfaChallengeRequired } from './mfa-challenge';
 import type { OAuthCallback, OAuthHandshake } from './oauth';
-import {
-  emailVerifiedNotStored,
-  oauthAccountNotLinked,
-  oauthExchangeFailed,
-  oauthLinkingDisabled,
-  restartAt,
-} from './oauth-errors';
+import { oauthExchangeFailed, restartAt } from './oauth-errors';
 import {
   exchangeOAuthCode,
   type OAuthClientCredentials,
@@ -23,11 +18,58 @@ import {
   type OAuthTokens,
   oauthCredentials,
 } from './oauth-exchange';
-import { type OAuthProfile, oauthProfile } from './oauth-profile';
+import { type OAuthGrantContext, oauthGrantContext } from './oauth-grant-context';
+import { type OAuthProfile, readOAuthProfile } from './oauth-profile';
 import { resolveActor } from './policy-bridge';
 import { loginFailed } from './rate-limit';
 import { createSession, sessionCookie } from './session';
 
+/**
+ * The address is proven to the provider, and an account that never proved it already holds it.
+ * Naming that is not account enumeration — this caller just demonstrated they own the address —
+ * and staying silent would leave them with a login that fails forever and no way out.
+ *
+ * The address itself rides in `meta`, never in `cause`: a log pipeline can redact a field by
+ * key, and cannot redact an address that was already interpolated into a sentence.
+ */
+export const oauthAccountNotLinked = (provider: string, email: string): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: `an account holds this ${provider} address but never verified it, so ${provider} may not claim it`,
+    fix: `sign in with that account's password and confirm the email-verify link, then retry ${provider}`,
+    meta: { provider, email },
+  });
+
+/**
+ * `link: 'never'` and a local account already holds the address. Same code and same disclosure
+ * rule as `oauthAccountNotLinked` — the caller proved to the provider that the address is theirs,
+ * so naming the collision is not enumeration — and the address rides in `meta`, never in `cause`.
+ */
+export const oauthLinkingDisabled = (provider: string, email: string): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: `an account already holds this address and defineAuth({ link: 'never' }) forbids ${provider} from claiming it`,
+    fix: "sign in with that account's own credentials, or set link: 'verified-email' in defineAuth to let a provider-verified address claim a locally-verified account",
+    meta: { provider, email },
+  });
+
+/**
+ * `CreateUserInput` carries no `emailVerifiedAt`, so a provider-verified address takes a second
+ * write. Falling back to the unstamped row would mint a session for a user every later login
+ * reads as unverified — the exact state `resolveUser` refuses to link a provider to — so the
+ * flow fails closed on an adapter that loses the stamp instead of half-succeeding.
+ */
+export const emailVerifiedNotStored = (provider: string, userId: string): AuthError =>
+  new AuthError({
+    // `X_AUTH_WRITE_FAILED`, the code for "an adapter write returned no row". It was
+    // `X_NOT_IMPLEMENTED` — a 501 telling an operator a feature is missing, about an adapter that
+    // implements `updateUser` and lost a write it accepted.
+    code: 'X_AUTH_WRITE_FAILED',
+    cause: `the adapter returned no row for new user ${userId}, so the ${provider}-verified address was never stamped verified`,
+    fix: 'return the updated row from AuthAdapter.updateUser — MemoryAuthAdapter.updateUser is the reference implementation',
+    meta: { provider, userId },
+  });
+
 /**
  * What the IdP's answer entitles this identity to, in the app's own vocabulary. Which group maps
  * to which role is business convention and never ships (axiom 8) — this is the seam it arrives
@@ -48,8 +90,15 @@ export interface OAuthGrants {
   readonly externalId?: string | null | undefined;
 }
 
-/** Called once per callback, after the profile is proven and before the session is minted. */
-export type ResolveOAuthGrants = (profile: OAuthProfile) => Promise<OAuthGrants> | OAuthGrants;
+/**
+ * Called once per callback, after the profile is proven and before the session is minted. The
+ * `context` is what the IdP said beyond the profile — the token set, every id-token claim, and a
+ * lazy `userinfo()` — for an IdP that keeps its grants off the id token (#670).
+ */
+export type ResolveOAuthGrants = (
+  profile: OAuthProfile,
+  context: OAuthGrantContext,
+) => Promise<OAuthGrants> | OAuthGrants;
 
 export interface OAuthSignInInput {
   readonly profile: OAuthProfile;
@@ -108,7 +157,7 @@ async function applyGrants(auth: Auth, user: AuthUser, grants: OAuthGrants): Pro
  * display casing (`Ada@Example.com`) and change it between logins, and `x_users.email` is a plain
  * case-sensitive `unique` column — so unnormalised, the lookup below missed the account the user
  * registered and `createUserFor` minted a second one at the same address, which `login()` could
- * then never reach. `MemoryAdapter` used to fold case itself, which is why no test saw it.
+ * then never reach. `MemoryAuthAdapter` used to fold case itself, which is why no test saw it.
  */
 const profileEmail = (profile: OAuthProfile): string | null =>
   profile.email === null ? null : normaliseEmail(profile.email);
@@ -125,6 +174,12 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
       fix: `request the email scope for ${input.profile.provider} in beginOAuth(), then ${restartAt(input.profile.provider)}`,
     });
   }
+  // The provider did not vouch for the address, so this caller has proven nothing about owning
+  // it. Minting the account anyway is the pre-hijack: the real owner's `register()` then collides,
+  // their verified-provider login is refused as "never verified", and the attacker's identity stays
+  // linked to the row they later claim. Answered exactly as `resolveUser` answers the same
+  // unverified address when it IS taken, so the two branches are no oracle for "is it taken?".
+  if (!input.profile.emailVerified) throw loginFailed();
   const grants = input.grants ?? {};
   if ((grants.roles ?? []).length === 0 && (grants.orgId ?? null) === null) {
     // Not an error — an app may genuinely want a roleless account until somebody approves it —
@@ -136,7 +191,7 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
     });
   }
   const created = await auth.adapter.createUser({
-    id: uuid(auth.clock),
+    id: uuidV7(auth.clock),
     email,
     // An OAuth-only account has no password to store, and must never be given a random one:
     // a hash nobody knows the input to is still a credential a reset flow could hand over.
@@ -147,7 +202,6 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
     externalId: grants.externalId ?? null,
     createdAt: auth.clock.now(),
   });
-  if (!input.profile.emailVerified) return created;
   // `CreateUserInput` has no `emailVerifiedAt`, so the stamp is a required second write. Returning
   // `created` when it does not land would sign in a user whose row says unverified — and the next
   // login through this same provider would then refuse to link it at all.
@@ -158,7 +212,7 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
 
 /**
  * Resolve the identity to a user: an already-linked account first, then an existing account
- * with the same address, then a fresh user.
+ * with the same address, then a fresh user — and a fresh user only for a provider-verified address.
  *
  * An address alone is not proof of ownership on either side. Attaching a provider identity to a
  * local account that never verified its own email hands the login to whoever registered that
@@ -195,7 +249,7 @@ async function resolveUser(
 
 function accountFor(auth: Auth, user: AuthUser, input: OAuthSignInInput): AuthAccount {
   return {
-    id: uuid(auth.clock),
+    id: uuidV7(auth.clock),
     userId: user.id,
     provider: input.profile.provider,
     providerAccountId: input.profile.providerAccountId,
@@ -244,7 +298,7 @@ export async function signInWithOAuth(auth: Auth, input: OAuthSignInInput): Prom
     linked === null ? account : { ...account, id: linked.id, createdAt: linked.createdAt },
   );
 
-  if (user.mfaSecret !== null) throw mfaRequired(user.id);
+  if (user.mfaSecret !== null) throw await mfaChallengeRequired(auth, user.id);
 
   const issued = await createSession(auth.sessions, {
     userId: user.id,
@@ -286,11 +340,12 @@ export async function completeOAuthLogin(
     fetch: input.fetch,
     timeoutMs: input.timeoutMs,
   });
-  const profile = await oauthProfile(provider, tokens, {
-    fetch: input.fetch,
-    timeoutMs: input.timeoutMs,
-  });
-  const grants = input.resolveGrants === undefined ? undefined : await input.resolveGrants(profile);
+  const options = { fetch: input.fetch, timeoutMs: input.timeoutMs };
+  const { profile, userinfo } = await readOAuthProfile(provider, tokens, options);
+  const grants =
+    input.resolveGrants === undefined
+      ? undefined
+      : await input.resolveGrants(profile, oauthGrantContext(profile, tokens, options, userinfo));
   return await signInWithOAuth(auth, {
     profile,
     tokens,

package/src/oauth-profile.ts

@@ -133,11 +133,16 @@ async function githubPrimaryEmail(
   return verified.find((entry) => entry.primary) ?? verified[0] ?? null;
 }
 
-async function fromUserInfo(
+/**
+ * The provider's userinfo answer, whole: every claim, the ones `OAuthProfile` names and the ones it
+ * does not. Shared by the profile below and by `resolveGrants`' `userinfo()` (#670), so the two
+ * reads refuse the same three failures with the same codes — one endpoint, one reader.
+ */
+export async function userinfoBody(
   provider: OAuthProviderId,
   tokens: OAuthTokens,
   options: OAuthProfileOptions,
-): Promise<OAuthProfile> {
+): Promise<Record<string, unknown>> {
   const config = providerFor(provider);
   const url = config.userInfoUrl;
   if (url === null) {
@@ -167,12 +172,30 @@ async function fromUserInfo(
       fix: `confirm ${url} is the provider's real userinfo endpoint and not a proxy`,
     });
   }
+  return result.body;
+}
 
-  const body = result.body;
-  // GitHub's id is a number; OIDC's `sub` is a string. Both are stable, so both are accepted.
+/** GitHub's id is a number; OIDC's `sub` is a string. Both are stable, so both are accepted. */
+export function userinfoAccountId(body: Readonly<Record<string, unknown>>): string {
   const rawId = body['sub'] ?? body['id'];
-  const providerAccountId =
-    typeof rawId === 'number' ? String(rawId) : typeof rawId === 'string' ? rawId : '';
+  return typeof rawId === 'number' ? String(rawId) : typeof rawId === 'string' ? rawId : '';
+}
+
+/** A profile, and the userinfo body it was read from when it was read from one. */
+export interface OAuthProfileRead {
+  readonly profile: OAuthProfile;
+  /** `null` when the id token answered alone and no userinfo request was made. */
+  readonly userinfo: Record<string, unknown> | null;
+}
+
+async function fromUserInfo(
+  provider: OAuthProviderId,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions,
+): Promise<OAuthProfileRead> {
+  const config = providerFor(provider);
+  const body = await userinfoBody(provider, tokens, options);
+  const providerAccountId = userinfoAccountId(body);
   if (providerAccountId === '') {
     throw oauthExchangeFailed({
       provider,
@@ -193,13 +216,14 @@ async function fromUserInfo(
     }
   }
 
-  return {
+  const profile: OAuthProfile = {
     provider,
     providerAccountId,
     email,
     emailVerified,
     name: stringOrNull(body['name']) ?? stringOrNull(body['login']),
   };
+  return { profile, userinfo: body };
 }
 
 /**
@@ -212,17 +236,29 @@ export async function oauthProfile(
   tokens: OAuthTokens,
   options: OAuthProfileOptions = {},
 ): Promise<OAuthProfile> {
+  return (await readOAuthProfile(provider, tokens, options)).profile;
+}
+
+/**
+ * `oauthProfile`, keeping the userinfo body it fetched — so `resolveGrants`' `userinfo()` hands
+ * that body back instead of asking the provider a second time in the same login (#670).
+ */
+export async function readOAuthProfile(
+  provider: OAuthProviderId,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions = {},
+): Promise<OAuthProfileRead> {
   const claims = tokens.claims;
   if (claims === null) return await fromUserInfo(provider, tokens, options);
 
   const email = stringOrNull(claims.email);
   const userInfoUrl = providerFor(provider).userInfoUrl;
   if (email === null && userInfoUrl !== null) {
-    const profile = await fromUserInfo(provider, tokens, options);
+    const read = await fromUserInfo(provider, tokens, options);
     // Two surfaces, one identity — or this is not that identity. Overwriting the subject and
     // keeping the address would link the account on an address belonging to whoever the second
     // call described, so a disagreement ends the handshake instead of being reconciled.
-    if (profile.providerAccountId !== claims.sub) {
+    if (read.profile.providerAccountId !== claims.sub) {
       throw oauthExchangeFailed({
         provider,
         stage: 'userinfo',
@@ -230,14 +266,15 @@ export async function oauthProfile(
         fix: `confirm ${userInfoUrl} is ${provider}'s own userinfo endpoint and not a proxy that rewrites sub`,
       });
     }
-    return profile;
+    return read;
   }
 
-  return {
+  const profile: OAuthProfile = {
     provider,
     providerAccountId: claims.sub,
     email,
     emailVerified: email !== null && idTokenEmailVerified(claims),
     name: stringOrNull(claims.name),
   };
+  return { profile, userinfo: null };
 }

package/src/oauth-registry.ts

@@ -5,9 +5,24 @@
 // account linking with it. The three built-ins register through the same call an app uses, so the
 // opening does not create a second path.
 
+import { renderCauseValue, renderFixLiteral } from '@ultimat3/core';
+import { AuthError } from './errors';
 import type { OAuthProvider } from './oauth';
 import { BUILTIN_OAUTH_PROVIDERS } from './oauth-builtins';
-import { oauthProviderDuplicate, oauthProviderUnknown } from './oauth-errors';
+import { oauthProviderUnknown } from './oauth-errors';
+
+/**
+ * Two `registerOAuthProvider` calls claiming one id. A silent replacement would let whichever
+ * module imported second decide where every login for that id goes — including which `issuers`
+ * an id token may claim — so the second registration refuses at boot instead.
+ */
+export const oauthProviderDuplicate = (provider: string): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_PROVIDER_DUPLICATE',
+    cause: `an oauth provider is already registered as ${renderCauseValue(provider)}, so the second registration would silently replace the first`,
+    fix: `give one of them a different id, or delete the duplicate registerOAuthProvider({ id: ${renderFixLiteral(provider, '<id>')} }) call`,
+    meta: { provider },
+  });
 
 const registry = new Map<string, OAuthProvider>();
 

package/src/oauth-route.ts

@@ -10,16 +10,20 @@
 
 import {
   type Clock,
+  EnvMissingError,
   isUltimateError,
   logger,
+  renderCauseValue,
+  renderFixShellArg,
   renderThrowable,
   type UltimateError,
 } from '@ultimat3/core';
 import type { Auth, LoginResult } from './auth';
+import { AuthError } 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 { oauthExchangeFailed, oauthProviderUnknown, restartAt } from './oauth-errors';
 import type { OAuthClientCredentials, OAuthFetch } from './oauth-exchange';
 import { oauthCredentials } from './oauth-exchange';
 import { completeOAuthLogin, type ResolveOAuthGrants } from './oauth-login';
@@ -30,6 +34,30 @@ import {
 } from './oauth-paths';
 import { hasOAuthProvider } from './oauth-registry';
 
+/**
+ * The provider came back with `error=` and no code — almost always the user pressing Cancel.
+ * A separate code from `X_OAUTH_EXCHANGE_FAILED` on purpose: nothing was exchanged, nothing is
+ * misconfigured, and folding the single commonest non-success outcome of a login into the code
+ * that means "the client secret is wrong" makes both unreadable in a log and pages the wrong person.
+ */
+export const oauthDenied = (
+  provider: string,
+  reason: string,
+  description: string | null,
+): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_DENIED',
+    // `reason` and `description` are query parameters off the callback URL — whatever the browser
+    // was redirected with, newlines and quotes included. `renderCauseValue` renders them as JSON
+    // string literals, so a forged `error_description` cannot forge a second log line or break the
+    // sentence around it. Both are already `string` by type: this is escaping, not throw-safety.
+    cause: `${provider} declined the authorization: ${renderCauseValue(reason)}${
+      description === null ? '' : ` (${renderCauseValue(description)})`
+    }`,
+    fix: `${restartAt(provider)} and approve the ${provider} consent screen`,
+    meta: { provider, reason },
+  });
+
 /**
  * What a router needs to mount one of these. Structural, like `RequestLike` in `session.ts`:
  * `@ultimat3/http` binds to this shape, this package never binds to `@ultimat3/http`.
@@ -52,9 +80,9 @@ export interface OAuthLoginRoutes {
 
 export interface OAuthLoginOptions {
   /**
-   * The origin the provider redirects back to. Defaults to `APP_URL`, then to the request's own
-   * origin — which is the `Host` header, so it is preferred last: a forged one only ever produces
-   * a `redirect_uri` the provider refuses, but naming the canonical origin costs nothing.
+   * The origin the provider redirects back to. Defaults to `APP_URL`; with neither, the start leg
+   * refuses (`X_ENV_MISSING`). Never the request's own origin: that is the `Host` header, which
+   * the caller writes.
    */
   readonly baseUrl?: string | undefined;
   /** Defaults to the two env vars in the provider table, read per request, never at import. */
@@ -125,34 +153,44 @@ export function oauthRouteStatus(code: string): number {
   return Object.hasOwn(OAUTH_ROUTE_STATUS, code) ? (OAUTH_ROUTE_STATUS[code] ?? 502) : 502;
 }
 
+/** The one sentence every refusal carries outward. The event name is where the rest went. */
+const PUBLIC_CAUSE =
+  'the sign-in was refused; its cause and its fix are in this server\u2019s log under auth.oauth.refused';
+
+/** A code this framework would have minted — the only kind spliced into a command. */
+const FRAMEWORK_CODE = /^X_[A-Z0-9_]+$/;
+
 /**
- * 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
- * whole published a stack trace and whatever a factory put in `meta` to whoever typed the URL. Four
- * fields, the same four on every code: no per-code judgement about which `meta` key is safe today.
+ * What an anonymous caller is allowed to read: the code, its registered title and docs link, and
+ * one fixed sentence. Both legs are public by definition, and an authored `cause`/`fix` is written
+ * for the developer — it names env vars, endpoints and what a provider answered — so neither is
+ * served, on any code: no per-code judgement about which sentence is safe today.
  */
 const publicBody = (coded: UltimateError): Record<string, string> => ({
   code: coded.code,
   title: coded.title,
-  cause: coded.cause,
-  fix: coded.fix,
+  cause: PUBLIC_CAUSE,
+  fix: FRAMEWORK_CODE.test(coded.code)
+    ? `x errors explain ${renderFixShellArg(coded.code, '<CODE>')} --json`
+    : 'x errors list --json',
   docs: coded.docs,
 });
 
 /**
- * Failure is JSON, never a redirect to a login page carrying `?error=`. A callback is the one
- * request in the flow whose failure the developer has to read, and a redirect that drops the code
- * and the fix line is exactly how three dead `fix:` strings survived a whole release. An app that
- * wants a rendered page wraps these two descriptors; the framework ships the debuggable answer.
+ * Failure is JSON, never a redirect to a login page carrying `?error=`: the status and the code
+ * are the answer a client branches on. The developer's half — the cause and the fix line — is
+ * logged as `auth.oauth.refused`, where only an operator reads it. An app that wants a rendered
+ * page wraps these two descriptors.
  */
 function problem(error: unknown, extraCookies: readonly string[]): Response {
   const coded = isUltimateError(error) ? error : uncoded(error);
+  const status = oauthRouteStatus(coded.code);
+  const fields = { code: coded.code, status, cause: coded.cause, fix: coded.fix };
+  if (status >= 500) logger.error('auth.oauth.refused', fields);
+  else logger.info('auth.oauth.refused', fields);
   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)), {
-    status: oauthRouteStatus(coded.code),
-    headers,
-  });
+  return new Response(JSON.stringify(publicBody(coded)), { status, headers });
 }
 
 /**
@@ -244,10 +282,22 @@ function credentialsFor(
   }
 }
 
-function originFor(request: Request, options: OAuthLoginOptions): string {
+/**
+ * The declared origin, or a refusal. The request's own origin is the `Host` header, so a
+ * `redirect_uri` built from it is one the caller chose.
+ */
+function declaredOrigin(options: OAuthLoginOptions): string {
   const env = options.env ?? Bun.env;
-  const declared = options.baseUrl ?? env['APP_URL']?.trim() ?? '';
-  return declared === '' ? new URL(request.url).origin : declared.replace(/\/+$/, '');
+  const declared = (options.baseUrl ?? env['APP_URL'] ?? '').trim();
+  if (declared === '') {
+    throw new EnvMissingError({
+      cause:
+        'APP_URL is not set and oauthLogin() was given no baseUrl, so there is no declared origin to build the provider redirect_uri from',
+      fix: 'export APP_URL=http://localhost:3000   # the origin this app is served from',
+      meta: { key: 'APP_URL' },
+    });
+  }
+  return declared.replace(/\/+$/, '');
 }
 
 /** The handshake's own options, assembled once so both legs seal and open it identically. */
@@ -265,12 +315,15 @@ async function startHandler(
   request: Request,
 ): Promise<Response> {
   try {
+    // Before the provider is looked at: asked after, a missing origin answered 500 for a provider
+    // this app enabled and 404 for one it did not.
+    const origin = declaredOrigin(options);
     const provider = assertEnabled(auth, providerSegment(request, 'start'));
     const credentials = credentialsFor(provider, options);
     const handshake = beginOAuth({
       provider,
       clientId: credentials.clientId,
-      redirectUri: `${originFor(request, options)}${oauthCallbackPath(provider)}`,
+      redirectUri: `${origin}${oauthCallbackPath(provider)}`,
       scopes: options.scopes,
     });
     return new Response(null, {

package/src/oauth.ts

@@ -4,9 +4,10 @@
 // configs are pure data and live in `oauth-registry.ts`: importing this file performs no network
 // I/O and reads no env.
 
+import { timingSafeEqual } from '@ultimat3/core';
 import { oauthStateInvalid } from './oauth-errors';
 import { providerFor } from './oauth-registry';
-import { base64Url, randomToken, sha256Bytes, timingSafeEqual } from './tokens';
+import { base64Url, randomToken, sha256Bytes } from './tokens';
 
 export interface OAuthProvider {
   readonly id: string;
@@ -63,7 +64,7 @@ export function pkceChallenge(verifier: string): string {
   return base64Url(sha256Bytes(verifier));
 }
 
-export function createPkce(): PkcePair {
+export function pkcePair(): PkcePair {
   // 32 random bytes -> 43 base64url chars, the RFC's minimum verifier length.
   const verifier = randomToken(32);
   return { verifier, challenge: pkceChallenge(verifier), method: 'S256' };
@@ -88,7 +89,7 @@ export interface BeginOAuthInput {
 
 export function beginOAuth(input: BeginOAuthInput): OAuthHandshake {
   const provider = providerFor(input.provider);
-  const pkce = createPkce();
+  const pkce = pkcePair();
   const state = randomToken(16);
   const nonce = randomToken(16);
   const url = new URL(provider.authorizeUrl);