@ultimat3/auth 9.0.0 → 11.0.0

package/src/limiter-install.ts

@@ -24,8 +24,20 @@ import type { AuthLimiter, AuthRateLimitPolicy } from './rate-limit';
 export type AuthLimiterFactory = (policy: AuthRateLimitPolicy) => AuthLimiter;
 
 let factory: AuthLimiterFactory | undefined;
-/** Every limiter this process built through the factory above, so a purge can reach them. */
-let built: AuthLimiter[] = [];
+/**
+ * The limiters a purge can still reach, ONE per distinct window.
+ *
+ * A list appended to per call is a leak with no ceiling: `installedAuthLimiter` runs twice per
+ * `defineAuth` — the account/IP bucket and the tenant bucket — and nothing trimmed it, so a
+ * process that redefines auth (`x dev`'s reload, a test file, a host building one `Auth` per app)
+ * held every limiter it ever built, and the store behind each, for its whole life.
+ *
+ * Keyed by `windowMs` because that is the only thing `purgeAuthLimits` reads: every limiter here
+ * writes the same two tables, so one per window is all a sweep can distinguish. The FIRST of a
+ * window is kept, which is the limiter the old list already swept — a second install clears the
+ * map, so nothing here outlives the pool it was built on either way.
+ */
+let built = new Map<number, AuthLimiter>();
 
 /**
  * The ONE install point, the same shape as `configureKdfGate` beside it: a host that owns the
@@ -37,13 +49,13 @@ let built: AuthLimiter[] = [];
  */
 export function configureAuthLimiters(next: AuthLimiterFactory): void {
   factory = next;
-  built = [];
+  built = new Map();
 }
 
 /** Back to `createAuthLimiter`, the per-process default. A host that installs one calls this on stop. */
 export function resetAuthLimiters(): void {
   factory = undefined;
-  built = [];
+  built = new Map();
 }
 
 /**
@@ -55,10 +67,20 @@ export function resetAuthLimiters(): void {
 export function installedAuthLimiter(policy: AuthRateLimitPolicy): AuthLimiter | undefined {
   if (factory === undefined) return undefined;
   const limiter = factory(policy);
-  built.push(limiter);
+  if (!built.has(policy.windowMs)) built.set(policy.windowMs, limiter);
   return limiter;
 }
 
+/**
+ * How many limiters a purge can still reach. Deliberately NOT exported from `src/index.ts`: it
+ * exists because unbounded retention has no other observation — `purgeAuthLimits` sweeps exactly
+ * one limiter however many were held, so no assertion about behaviour could see the growth. The
+ * same shape as `@ultimat3/realtime`'s `droppedChannelFrames`.
+ */
+export function installedLimiterCount(): number {
+  return built.size;
+}
+
 /** A limiter that keeps rows somebody else has to delete. The memory limiter sweeps itself. */
 type PurgingAuthLimiter = AuthLimiter & { purgeExpired(): Promise<number> };
 
@@ -82,7 +104,7 @@ const canPurge = (limiter: AuthLimiter): limiter is PurgingAuthLimiter =>
  */
 export async function purgeAuthLimits(): Promise<number> {
   let widest: PurgingAuthLimiter | undefined;
-  for (const limiter of built) {
+  for (const limiter of built.values()) {
     if (!canPurge(limiter)) continue;
     if (widest === undefined || limiter.policy.windowMs > widest.policy.windowMs) widest = limiter;
   }

package/src/memory-adapter.ts

@@ -2,6 +2,7 @@
 // database exists and the one every test in this package runs against — the same interface
 // Postgres and Better Auth implement, so a flow that works here works there or the seam is wrong.
 
+import { type Clock, systemClock } from '@ultimat3/core';
 import type {
   AuthAccount,
   AuthAdapter,
@@ -14,18 +15,29 @@ import type {
   UserPatch,
   UserQuery,
 } from './adapter';
+import { authUniqueViolation } from './errors';
 import { timingSafeEqual } from './tokens';
 
 const verificationKey = (purpose: string, identifier: string): string => `${purpose}:${identifier}`;
 
 export class MemoryAdapter implements AuthAdapter {
   readonly name = 'memory';
+  readonly #clock: Clock;
   readonly #users = new Map<string, AuthUser>();
   readonly #sessions = new Map<string, AuthSession>();
   readonly #accounts = new Map<string, AuthAccount>();
   readonly #verifications = new Map<string, AuthVerification>();
   readonly #apiKeys = new Map<string, AuthApiKeyRecord>();
 
+  /**
+   * The clock every instant this adapter stamps comes from — one argument, because a stamp is a
+   * fact about WHEN a call happened and a test that cannot move it can only assert a range.
+   * Defaults to `systemClock`, so `new MemoryAdapter()` is what it always was.
+   */
+  constructor(clock: Clock = systemClock) {
+    this.#clock = clock;
+  }
+
   /**
    * Exact match, because `BuiltinAdapter` issues `where email = $1` against a plain `text ...
    * unique` column and nothing folds case there. Normalising here instead made this the ONE
@@ -43,7 +55,35 @@ export class MemoryAdapter implements AuthAdapter {
     return this.#users.get(id) ?? null;
   }
 
+  /**
+   * The two UNIQUE constraints `x_users` declares, enforced here because `BuiltinAdapter` LEANS on
+   * them: `email text not null unique` and `external_id text unique` (`tables.ts`). Without them
+   * this adapter — the one `x new` scaffolds and every test runs against — accepted two rows at one
+   * address, and the second was unreachable forever, since `findUserByEmail` returns the first.
+   *
+   * Over the STORED string, exactly as Postgres compares it. No case folding: that is the
+   * divergence `adapter-parity.test.ts`'s first case pins, and `normaliseEmail` above the seam is
+   * what makes two spellings one address.
+   */
   async createUser(input: CreateUserInput): Promise<AuthUser> {
+    for (const existing of this.#users.values()) {
+      if (existing.email === input.email) {
+        throw authUniqueViolation('createUser', 'x_users', 'email');
+      }
+      // `!= null` in one predicate, spelled out: a Postgres unique index is NULLS DISTINCT, so
+      // `external_id text unique` constrains only the rows that CARRY a value and admits
+      // unlimited NULLs. `!== undefined` alone made a second account with no external id collide
+      // with the first — and `oauth-login.ts` hands over `grants.externalId ?? null` for every
+      // first-time OAuth user, so the second such signup failed against a constraint production
+      // does not have.
+      if (
+        input.externalId !== undefined &&
+        input.externalId !== null &&
+        existing.externalId === input.externalId
+      ) {
+        throw authUniqueViolation('createUser', 'x_users', 'external_id');
+      }
+    }
     const user: AuthUser = {
       id: input.id,
       // Stored as handed over, exactly as the `insert into x_users` binds it.
@@ -197,7 +237,10 @@ export class MemoryAdapter implements AuthAdapter {
     // Before the write, never after: a wrong guess that consumed the row would be an
     // unauthenticated way to kill the victim's live link, which is the Postgres adapter's rule too.
     if (!timingSafeEqual(tokenHash, record.tokenHash)) return null;
-    const consumed: AuthVerification = { ...record, consumedAt: new Date(record.createdAt) };
+    // The moment it was REDEEMED, which is what `consumed_at = now()` writes on the Postgres
+    // side. This was `new Date(record.createdAt)` — the moment it was ISSUED — so every window
+    // measured from the stamp read a redemption as having happened at issue time.
+    const consumed: AuthVerification = { ...record, consumedAt: this.#clock.now() };
     this.#verifications.set(key, consumed);
     return consumed;
   }

package/src/oauth-cookie.ts

@@ -7,8 +7,8 @@
 
 import type { Clock } from '@ultimat3/core';
 import { EnvMissingError, systemClock } from '@ultimat3/core';
-import { oauthStateInvalid } from './errors';
 import type { OAuthHandshake, OAuthProviderId } from './oauth';
+import { oauthStateInvalid } from './oauth-errors';
 import { hasOAuthProvider } from './oauth-registry';
 import { type RequestLike, readCookie } from './session';
 import { base64Url, timingSafeEqual } from './tokens';

package/src/oauth-discovery.ts

@@ -4,9 +4,9 @@
 // four endpoints that nobody re-checks when the vendor moves one.
 
 import { renderThrowable } from '@ultimat3/core';
-import { oauthExchangeFailed } from './errors';
 import { isRecord } from './json';
 import type { OAuthProvider } from './oauth';
+import { oauthExchangeFailed } from './oauth-errors';
 import type { OAuthFetch } from './oauth-exchange';
 
 const DEFAULT_TIMEOUT_MS = 10_000;

package/src/oauth-errors.ts

@@ -0,0 +1,178 @@
+// Single responsibility: the OAuth half of this package's error factories — every refusal a
+// provider handshake can produce, and the one phrase their fixes are built from.
+// Split from `errors.ts` at the 500-line ceiling; the codes, the titles and the single
+// `registerErrorCodes()` call stay there, so this file adds no code and registers nothing.
+
+import { renderCauseValue, renderFixLiteral } from '@ultimat3/core';
+import { AuthError } from './errors';
+import { oauthStartPath } from './oauth-paths';
+
+/**
+ * The `fix:` quotes `oauthStartPath` rather than a hand-written path. That is not tidiness: this
+ * line shipped naming `GET /auth/oauth/<provider>` while `@ultimat3/auth` mounted no route at all,
+ * so every caller who followed it hit a 404. One declaration, read by the mount and by the fix,
+ * is what stops that recurring — `oauthLogin()` cannot move without moving this sentence.
+ */
+export const oauthStateInvalid = (provider: string, part: string): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_STATE_INVALID',
+    cause: `${provider} callback rejected: ${part}`,
+    fix: `${restartAt(provider)} — a callback URL is single-use`,
+    meta: { provider },
+  });
+
+/** The one phrase every "start over" fix is built from, so none of them can name a dead route. */
+export const restartAt = (provider: string): string =>
+  `restart the flow at GET ${oauthStartPath(provider)}`;
+
+/**
+ * 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 },
+  });
+
+/**
+ * A URL segment naming a provider no `registerOAuthProvider` call has claimed, or one that is but
+ * was left out of `defineAuth({ providers })`. One refusal for both: which of the two it is
+ * describes the app's configuration to an unauthenticated caller, and the fix is the same sentence
+ * either way.
+ *
+ * **`supported` is the CALLER's to scope, because the two callers have two audiences.**
+ * `oauth-route.ts` passes `BUILTIN_OAUTH_PROVIDER_IDS` — its reader is an anonymous stranger who
+ * typed a URL, and the three built-ins are a framework constant already in the public docs, while
+ * the live registry holds whatever internal OP this deployment registered. `providerFor()` passes
+ * `oauthProviderIds()` — its reader is a developer holding a stack trace, and there the full list
+ * is exactly what makes the fix runnable. Neither ever passes `defineAuth({ providers })`: naming
+ * what this deployment turned on is the disclosure the shared refusal exists to prevent.
+ *
+ * The fix names `registerOAuthProvider` first so it stays executable for the branch the narrowed
+ * list cannot cover — a segment nothing registered cannot be added to `providers` at all, so
+ * "add it" alone was an instruction that could not be followed.
+ *
+ * The segment itself is a URL path the caller typed, so it goes through `renderCauseValue` in the
+ * sentence and `renderFixLiteral` in the command — a fix has to parse after a hostile value lands
+ * in it.
+ */
+export const oauthProviderUnknown = (provider: string, supported: readonly string[]): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_PROVIDER_UNKNOWN',
+    cause: `no oauth provider is mounted at ${renderCauseValue(oauthStartPath(provider))}`,
+    fix: `registerOAuthProvider({ id: ${renderFixLiteral(provider, '<id>')} }) if it is not built in, then add that id to defineAuth({ providers: [...] }) — known here: ${supported.map((id) => `'${id}'`).join(', ')}`,
+    meta: { provider },
+  });
+
+/**
+ * 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 },
+  });
+
+export interface OAuthExchangeFailure {
+  readonly provider: string;
+  /**
+   * Which leg of the server-to-server conversation failed. `discovery` and `jwks` are the two
+   * boot/verification legs an enterprise OP adds: reading `/.well-known/openid-configuration`,
+   * and reading the key set an id token's signature is checked against.
+   */
+  readonly stage: 'token' | 'userinfo' | 'discovery' | 'jwks';
+  readonly detail: string;
+  readonly status?: number | undefined;
+  readonly fix: string;
+}
+
+/**
+ * Deliberately specific, unlike every credential error above it. This one describes a
+ * conversation between two servers — naming the stage, the provider and its own status
+ * discloses nothing about any user, and is the difference between a fixable misconfiguration
+ * and a shrug.
+ */
+export const oauthExchangeFailed = (failure: OAuthExchangeFailure): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_EXCHANGE_FAILED',
+    cause:
+      `${failure.provider} ${failure.stage} request failed` +
+      `${failure.status === undefined ? '' : ` with HTTP ${failure.status}`}: ${failure.detail}`,
+    fix: failure.fix,
+    meta: {
+      provider: failure.provider,
+      stage: failure.stage,
+      ...(failure.status === undefined ? {} : { status: failure.status }),
+    },
+  });
+
+/**
+ * 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({
+    code: 'X_NOT_IMPLEMENTED',
+    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 — MemoryAdapter.updateUser is the reference implementation',
+    meta: { provider, userId },
+  });
+
+/** The token arrived, and is not one this handshake can trust: wrong `iss`, `aud`, or expired. */
+export const oauthTokenInvalid = (provider: string, reason: string, fix: string): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_TOKEN_INVALID',
+    cause: `${provider} id token rejected: ${reason}`,
+    fix,
+    meta: { provider },
+  });

package/src/oauth-exchange.ts

@@ -4,8 +4,13 @@
 // token is verified here, so no caller downstream can forget to.
 
 import type { Clock } from '@ultimat3/core';
-import { EnvMissingError, renderCauseValue, renderThrowable, systemClock } from '@ultimat3/core';
-import { oauthExchangeFailed, restartAt } from './errors';
+import {
+  EnvMissingError,
+  logger,
+  renderCauseValue,
+  renderThrowable,
+  systemClock,
+} from '@ultimat3/core';
 import { type IdTokenClaims, verifyIdToken } from './id-token';
 import { isRecord } from './json';
 import type { IdTokenKeys } from './jwks';
@@ -15,6 +20,7 @@ import {
   type OAuthHandshake,
   type OAuthProviderId,
 } from './oauth';
+import { oauthExchangeFailed, restartAt } from './oauth-errors';
 import { providerFor } from './oauth-registry';
 
 /** Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to. */
@@ -91,7 +97,31 @@ export function oauthCredentials(
  * mostly prose this package authored, and quoting that would make every readable message unread-
  * able. The rule is "remote text is rendered", and this function is where remote text is made.
  */
-export async function providerDetail(response: Response): Promise<string> {
+/**
+ * How much of a body this leg may quote back.
+ *
+ * `'raw'` — the default and what userinfo, discovery and jwks use: those requests carry a bearer
+ * token or nothing, and the raw text is what makes a misconfigured enterprise OP debuggable.
+ *
+ * `'coded-only'` — the `POST /token` leg, and ONLY it. That request carries `client_secret`, and
+ * an endpoint that echoes what it was sent (compromised, impersonated, or a misbehaving gateway)
+ * put the secret into an `X_OAUTH_EXCHANGE_FAILED` `cause:` that `oauth-route.ts` publishes to an
+ * unauthenticated caller. Measured: 38 of 42 characters of the secret reached the response body,
+ * and a shorter `redirect_uri` fits all of it inside `MAX_DETAIL_LENGTH`. A coded OAuth error
+ * still comes through — `invalid_grant`, `redirect_uri_mismatch` — because that is a field the
+ * SPEC defines and the whole reason this string exists.
+ */
+export type DetailEcho = 'raw' | 'coded-only';
+
+/** What a `coded-only` leg says instead of the body. Names why, so nobody re-adds the echo. */
+const OPAQUE_BODY =
+  'the endpoint answered with a body that is not a coded OAuth error, and this leg does not quote ' +
+  'one back because its request carries the client secret';
+
+export async function providerDetail(
+  response: Response,
+  echo: DetailEcho = 'raw',
+): Promise<string> {
   const text = await response.text().catch(() => '');
   if (text === '') return 'the response body was empty';
   try {
@@ -105,6 +135,7 @@ export async function providerDetail(response: Response): Promise<string> {
   } catch {
     // Not JSON — fall through to the truncated raw text below.
   }
+  if (echo === 'coded-only') return OPAQUE_BODY;
   return renderCauseValue(
     text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text,
   );
@@ -143,16 +174,31 @@ async function postForm(
       signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
     });
   } catch (error) {
-    // `renderThrowable`, never `error.message` behind an `instanceof`: the rejection comes from
-    // an injected `fetch`, and `instanceof` itself throws on a value whose `getPrototypeOf` trap
-    // does — losing the one refusal that tells a caller the code is already spent.
-    const reason = renderThrowable(error);
+    // The rendered value goes to the LOG, never into the `detail:`.
+    //
+    // `oauth-route.ts` publishes this cause to an unauthenticated caller, and the rejection comes
+    // from an injected `OAuthFetch` — an app's own wrapper, a proxy client, an adapter behind it —
+    // so its text is a server's internals. Reproduced: a bare
+    // `Error('connect ECONNREFUSED 10.4.2.17:5432 (postgres://app:hunter2@db.internal/prod)')`
+    // was served as the 502 body of a public callback. `problem()`'s uncoded branch does NOT catch
+    // this one: it is coded by the time it gets there.
+    //
+    // `renderThrowable`, never `error.message` behind an `instanceof`: `instanceof` itself throws
+    // on a value whose `getPrototypeOf` trap does, losing the one refusal that tells a caller the
+    // code is already spent. What stays in the sentence is `url` and the remedy, both framework
+    // constants, so the failure is still fixable without quoting anything this package does not own.
+    logger.error('auth.oauth.token_fetch_failed', {
+      provider,
+      url,
+      detail: renderThrowable(error),
+    });
     throw oauthExchangeFailed({
       provider,
       stage: 'token',
       detail:
-        `${reason} — nothing left this host for ${url} (egress, DNS or TLS); restart the ` +
-        'flow once it does, since the code is already spent',
+        `nothing left this host for ${url} (egress, DNS or TLS); the reason is in this process ` +
+        'log under auth.oauth.token_fetch_failed. Restart the flow once it does, since the code ' +
+        'is already spent',
       fix: `curl -sS -m 5 -o /dev/null ${url}`,
     });
   }
@@ -161,7 +207,9 @@ async function postForm(
     throw oauthExchangeFailed({
       provider,
       stage: 'token',
-      detail: await providerDetail(response),
+      // `coded-only`: this request carried `client_secret`, and `oauth-route.ts` publishes this
+      // cause to whoever typed the URL.
+      detail: await providerDetail(response, 'coded-only'),
       status: response.status,
       fix: fixForStatus(provider, response.status),
     });

package/src/oauth-login.ts

@@ -7,16 +7,15 @@ import { ConfigInvalidError, logger, uuid } 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 type { OAuthCallback, OAuthHandshake } from './oauth';
 import {
-  authWriteFailed,
   emailVerifiedNotStored,
-  mfaRequired,
   oauthAccountNotLinked,
   oauthExchangeFailed,
   oauthLinkingDisabled,
   restartAt,
-} from './errors';
-import type { OAuthCallback, OAuthHandshake } from './oauth';
+} from './oauth-errors';
 import {
   exchangeOAuthCode,
   type OAuthClientCredentials,
@@ -200,8 +199,20 @@ function accountFor(auth: Auth, user: AuthUser, input: OAuthSignInInput): AuthAc
     userId: user.id,
     provider: input.profile.provider,
     providerAccountId: input.profile.providerAccountId,
-    accessToken: input.tokens.accessToken,
-    refreshToken: input.tokens.refreshToken,
+    // `null`, deliberately — this package does not persist a provider credential.
+    //
+    // `x_accounts.access_token` and `refresh_token` held live provider tokens in the CLEAR, under
+    // a `tables.ts` header promising "no column holds a plaintext secret", and NOTHING read either
+    // one back: `oauth-profile.ts` uses the token from the exchange, in flight, and
+    // `packages/auth/CLAUDE.md` states that refresh is not implemented. Declared and never wired
+    // — the same deletion this repo already ran for `jobs.driver`, except this one made a database
+    // dump into a set of usable third-party credentials.
+    //
+    // The TYPE keeps both fields: `AuthAccount` is the documented adapter seam, and an app that
+    // deliberately stores tokens implements `linkAccount` itself. What changed is what the
+    // framework writes.
+    accessToken: null,
+    refreshToken: null,
     expiresAt: input.tokens.expiresAt,
     createdAt: auth.clock.now(),
   };

package/src/oauth-profile.ts

@@ -4,10 +4,10 @@
 // decides whether this login may attach itself to an existing account by address.
 
 import { logger, renderThrowable } from '@ultimat3/core';
-import { oauthExchangeFailed, restartAt } from './errors';
 import { idTokenEmailVerified, isVerifiedFlag } from './id-token';
 import { isRecord } from './json';
 import type { OAuthProviderId } from './oauth';
+import { oauthExchangeFailed, restartAt } from './oauth-errors';
 import {
   OAUTH_USER_AGENT,
   type OAuthFetch,

package/src/oauth-registry.ts

@@ -5,9 +5,9 @@
 // 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 { oauthProviderDuplicate, oauthProviderUnknown } from './errors';
 import type { OAuthProvider } from './oauth';
 import { BUILTIN_OAUTH_PROVIDERS } from './oauth-builtins';
+import { oauthProviderDuplicate, oauthProviderUnknown } from './oauth-errors';
 
 const registry = new Map<string, OAuthProvider>();