@ultimat3/auth 1.1.0 → 2.0.0

package/src/memory-adapter.ts

@@ -12,7 +12,9 @@ import type {
   CreateUserInput,
   SessionPatch,
   UserPatch,
+  UserQuery,
 } from './adapter';
+import { timingSafeEqual } from './tokens';
 
 const verificationKey = (purpose: string, identifier: string): string => `${purpose}:${identifier}`;
 
@@ -24,10 +26,15 @@ export class MemoryAdapter implements AuthAdapter {
   readonly #verifications = new Map<string, AuthVerification>();
   readonly #apiKeys = new Map<string, AuthApiKeyRecord>();
 
+  /**
+   * 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
+   * adapter that found an account Postgres would not, which is a linked account under `x dev` and
+   * a duplicate one in production. `normaliseEmail` is the caller's, above the seam.
+   */
   async findUserByEmail(email: string): Promise<AuthUser | null> {
-    const wanted = email.trim().toLowerCase();
     for (const user of this.#users.values()) {
-      if (user.email === wanted) return user;
+      if (user.email === email) return user;
     }
     return null;
   }
@@ -39,14 +46,17 @@ export class MemoryAdapter implements AuthAdapter {
   async createUser(input: CreateUserInput): Promise<AuthUser> {
     const user: AuthUser = {
       id: input.id,
-      email: input.email.trim().toLowerCase(),
+      // Stored as handed over, exactly as the `insert into x_users` binds it.
+      email: input.email,
       emailVerifiedAt: null,
       passwordHash: input.passwordHash,
       orgId: input.orgId,
       roles: [...input.roles],
       permissions: [],
+      scopes: [...(input.scopes ?? [])],
       mfaSecret: null,
       recoveryCodeHashes: [],
+      externalId: input.externalId ?? null,
       disabledAt: null,
       createdAt: input.createdAt,
     };
@@ -66,11 +76,30 @@ export class MemoryAdapter implements AuthAdapter {
       recoveryCodeHashes: patch.recoveryCodeHashes ?? user.recoveryCodeHashes,
       disabledAt: patch.disabledAt === undefined ? user.disabledAt : patch.disabledAt,
       roles: patch.roles ?? user.roles,
+      permissions: patch.permissions ?? user.permissions,
+      scopes: patch.scopes ?? user.scopes,
+      orgId: patch.orgId === undefined ? user.orgId : patch.orgId,
+      externalId: patch.externalId === undefined ? user.externalId : patch.externalId,
     };
     this.#users.set(id, next);
     return next;
   }
 
+  async findUserByExternalId(externalId: string): Promise<AuthUser | null> {
+    for (const user of this.#users.values()) {
+      if (user.externalId === externalId) return user;
+    }
+    return null;
+  }
+
+  async listUsersByOrg(orgId: string, query?: UserQuery): Promise<readonly AuthUser[]> {
+    return [...this.#users.values()]
+      .filter((user) => user.orgId === orgId)
+      .filter((user) => query?.includeDisabled === true || user.disabledAt === null)
+      .filter((user) => query?.role === undefined || user.roles.includes(query.role))
+      .sort((a, b) => a.email.localeCompare(b.email));
+  }
+
   async getSession(id: string): Promise<AuthSession | null> {
     return this.#sessions.get(id) ?? null;
   }
@@ -108,6 +137,32 @@ export class MemoryAdapter implements AuthAdapter {
     return killed;
   }
 
+  async deleteSessionsForUser(userId: string): Promise<number> {
+    return this.#deleteSessionsWhere((session) => session.userId === userId);
+  }
+
+  /** Joins through the user map, which is what the Postgres adapter's subselect does. */
+  async deleteSessionsForOrg(orgId: string): Promise<number> {
+    const members = new Set(
+      [...this.#users.values()].filter((user) => user.orgId === orgId).map((user) => user.id),
+    );
+    return this.#deleteSessionsWhere((session) => members.has(session.userId));
+  }
+
+  async deleteSessionsCreatedBefore(before: Date): Promise<number> {
+    return this.#deleteSessionsWhere((session) => session.createdAt.getTime() < before.getTime());
+  }
+
+  #deleteSessionsWhere(matches: (session: AuthSession) => boolean): number {
+    let killed = 0;
+    for (const [id, session] of this.#sessions) {
+      if (!matches(session)) continue;
+      this.#sessions.delete(id);
+      killed += 1;
+    }
+    return killed;
+  }
+
   async listSessions(userId: string): Promise<readonly AuthSession[]> {
     return [...this.#sessions.values()]
       .filter((session) => session.userId === userId)
@@ -131,10 +186,17 @@ export class MemoryAdapter implements AuthAdapter {
     this.#verifications.set(verificationKey(record.purpose, record.identifier), record);
   }
 
-  async takeVerification(purpose: string, identifier: string): Promise<AuthVerification | null> {
+  async takeVerification(
+    purpose: string,
+    identifier: string,
+    tokenHash: string,
+  ): Promise<AuthVerification | null> {
     const key = verificationKey(purpose, identifier);
     const record = this.#verifications.get(key);
     if (record === undefined || record.consumedAt !== null) return null;
+    // 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) };
     this.#verifications.set(key, consumed);
     return consumed;

package/src/oauth-builtins.ts

@@ -0,0 +1,77 @@
+// Single responsibility: the three consumer IdPs Ultimate ships with, as plain data. They live
+// apart from `oauth-registry.ts` so the registry can be seeded from them while `oauth.ts` reads
+// the registry — the only edge back to `oauth.ts` is the type, and a type is erased, so there is
+// no runtime cycle between the three files.
+
+import type { OAuthProvider } from './oauth';
+
+export const GITHUB_PROVIDER: OAuthProvider = {
+  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: [],
+  // GitHub is OAuth2 and not OIDC: no id token, therefore no key set to verify one against.
+  jwksUri: null,
+  scopes: ['read:user', 'user:email'],
+  usesPkce: true,
+  usesNonce: false,
+  clientIdEnv: 'GITHUB_CLIENT_ID',
+  clientSecretEnv: 'GITHUB_CLIENT_SECRET',
+};
+
+export const GOOGLE_PROVIDER: OAuthProvider = {
+  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'],
+  jwksUri: 'https://www.googleapis.com/oauth2/v3/certs',
+  scopes: ['openid', 'email', 'profile'],
+  usesPkce: true,
+  usesNonce: true,
+  clientIdEnv: 'GOOGLE_CLIENT_ID',
+  clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
+};
+
+export const APPLE_PROVIDER: OAuthProvider = {
+  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'],
+  jwksUri: 'https://appleid.apple.com/auth/keys',
+  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',
+};
+
+/** Seeded into the registry at import, through the same call an app registers its own IdP with. */
+export const BUILTIN_OAUTH_PROVIDERS: readonly OAuthProvider[] = Object.freeze([
+  GITHUB_PROVIDER,
+  GOOGLE_PROVIDER,
+  APPLE_PROVIDER,
+]);
+
+/**
+ * The three ids, and the only list an ANONYMOUS caller is ever shown. It is a framework constant
+ * already in the docs, so naming it discloses nothing; the live registry is not, because an app
+ * that registered `acme-internal-sso` has put its own vocabulary in there. `oauth-route.ts` is the
+ * one reader in this package — every other refusal reaches a developer and gets
+ * `oauthProviderIds()` instead. Off `index.ts` too, because an app writing its own login route
+ * owes an anonymous caller the same narrow list and must not have to restate the three ids.
+ */
+export const BUILTIN_OAUTH_PROVIDER_IDS: readonly string[] = Object.freeze(
+  BUILTIN_OAUTH_PROVIDERS.map((provider) => provider.id),
+);

package/src/oauth-cookie.ts

@@ -8,7 +8,8 @@
 import type { Clock } from '@ultimat3/core';
 import { EnvMissingError, systemClock } from '@ultimat3/core';
 import { oauthStateInvalid } from './errors';
-import { OAUTH_PROVIDERS, type OAuthHandshake, type OAuthProviderId } from './oauth';
+import type { OAuthHandshake, OAuthProviderId } from './oauth';
+import { hasOAuthProvider } from './oauth-registry';
 import { type RequestLike, readCookie } from './session';
 import { base64Url, timingSafeEqual } from './tokens';
 
@@ -138,7 +139,7 @@ export function openHandshake(
   ) {
     throw oauthStateInvalid(provider, 'the stored handshake is not a handshake');
   }
-  if (!Object.hasOwn(OAUTH_PROVIDERS, sealedProvider) || sealedProvider !== provider) {
+  if (!hasOAuthProvider(sealedProvider) || sealedProvider !== provider) {
     throw oauthStateInvalid(provider, 'the stored handshake belongs to a different provider');
   }
 
@@ -157,7 +158,7 @@ export function openHandshake(
  * session cookie's: the callback is a top-level cross-site GET from the provider, which `Lax`
  * still attaches the cookie to and `Strict` would strip — leaving every login to fail its state
  * check. A provider answering with `response_mode=form_post` POSTs instead, and this cookie
- * would not reach it; no provider in `OAUTH_PROVIDERS` is configured that way.
+ * would not reach it; none of the three built-in providers is configured that way.
  */
 export function handshakeCookie(
   handshake: OAuthHandshake,

package/src/oauth-discovery.ts

@@ -0,0 +1,132 @@
+// Single responsibility: turning an OIDC issuer URL into an `OAuthProvider`, by reading the
+// discovery document every conforming OP publishes (OIDC Discovery 1.0, §4). One `fetch`, at
+// boot, no dependency — an enterprise IdP is then three lines instead of a hand-copied table of
+// four endpoints that nobody re-checks when the vendor moves one.
+
+import { oauthExchangeFailed } from './errors';
+import { isRecord } from './json';
+import type { OAuthProvider } from './oauth';
+import type { OAuthFetch } from './oauth-exchange';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** The document lives at a fixed suffix off the issuer; the issuer keeps its own path. */
+export const discoveryUrl = (issuer: string): string =>
+  `${issuer.replace(/\/+$/, '')}/.well-known/openid-configuration`;
+
+export interface DiscoverOAuthProviderInput {
+  /** The id the URL segment carries: `/auth/oauth/<id>`. Also names the two env vars. */
+  readonly id: string;
+  readonly issuer: string;
+  /** Defaults to the OIDC minimum this package needs to identify somebody. */
+  readonly scopes?: readonly string[] | undefined;
+  readonly clientIdEnv?: string | undefined;
+  readonly clientSecretEnv?: string | undefined;
+  /** Injected in tests; production uses the global. */
+  readonly fetch?: OAuthFetch | undefined;
+  readonly timeoutMs?: number | undefined;
+}
+
+const stringOrNull = (body: Record<string, unknown>, key: string): string | null => {
+  const value = body[key];
+  return typeof value === 'string' && value !== '' ? value : null;
+};
+
+/** `bigco-sso` → `BIGCO_SSO_CLIENT_ID`, the same shape the three built-ins use. */
+const envPrefix = (id: string): string => id.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
+
+/**
+ * Reads the issuer's discovery document and returns the provider. It does **not** register:
+ * `registerOAuthProvider(await discoverOAuthProvider({ id, issuer }))` keeps one install point,
+ * and an app that wants to override one endpoint spreads the result before registering it.
+ *
+ * `issuers` is pinned to the `issuer` the document itself declares, not the URL that was asked
+ * for — a document that names a different issuer is answering for somebody else, and pinning the
+ * requested URL would let it.
+ */
+export async function discoverOAuthProvider(
+  input: DiscoverOAuthProviderInput,
+): Promise<OAuthProvider> {
+  const url = discoveryUrl(input.issuer);
+  const doFetch: OAuthFetch = input.fetch ?? ((target, init) => globalThis.fetch(target, init));
+
+  let response: Response;
+  try {
+    response = await doFetch(url, {
+      method: 'GET',
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(input.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+  } catch (error) {
+    throw oauthExchangeFailed({
+      provider: input.id,
+      stage: 'discovery',
+      detail:
+        error instanceof Error ? error.message : 'the request failed before a response arrived',
+      fix: `curl -sS -m 5 ${url}`,
+    });
+  }
+
+  if (!response.ok) {
+    throw oauthExchangeFailed({
+      provider: input.id,
+      stage: 'discovery',
+      detail: 'the issuer published no discovery document at the well-known path',
+      status: response.status,
+      fix: `curl -sS -m 5 ${url}   # then pass the real issuer URL to discoverOAuthProvider({ issuer })`,
+    });
+  }
+
+  const body: unknown = await response.json().catch(() => undefined);
+  if (!isRecord(body)) {
+    throw oauthExchangeFailed({
+      provider: input.id,
+      stage: 'discovery',
+      detail: 'the discovery document is not a JSON object',
+      fix: `confirm ${url} is the OP's own discovery document and not a login page`,
+    });
+  }
+
+  const issuer = stringOrNull(body, 'issuer');
+  const authorizeUrl = stringOrNull(body, 'authorization_endpoint');
+  const tokenUrl = stringOrNull(body, 'token_endpoint');
+  if (issuer === null || authorizeUrl === null || tokenUrl === null) {
+    throw oauthExchangeFailed({
+      provider: input.id,
+      stage: 'discovery',
+      detail:
+        'the discovery document is missing issuer, authorization_endpoint or token_endpoint, ' +
+        'so no handshake can be built from it',
+      fix: `curl -sS -m 5 ${url} | jq '{issuer, authorization_endpoint, token_endpoint}'`,
+    });
+  }
+
+  const jwksUri = stringOrNull(body, 'jwks_uri');
+  if (jwksUri === null) {
+    // Without a key set there is nothing to verify an id token against, and the only remaining
+    // trust is the TLS channel to the token endpoint — which is the exemption, not a default.
+    throw oauthExchangeFailed({
+      provider: input.id,
+      stage: 'discovery',
+      detail:
+        'the discovery document publishes no jwks_uri, so no id token from it can be verified',
+      fix: `register this provider by hand with an explicit jwksUri: registerOAuthProvider({ id: '${input.id}', ... })`,
+    });
+  }
+
+  const prefix = envPrefix(input.id);
+  return {
+    id: input.id,
+    authorizeUrl,
+    tokenUrl,
+    userInfoUrl: stringOrNull(body, 'userinfo_endpoint'),
+    userEmailsUrl: null,
+    issuers: [issuer],
+    jwksUri,
+    scopes: input.scopes ?? ['openid', 'email', 'profile'],
+    usesPkce: true,
+    usesNonce: true,
+    clientIdEnv: input.clientIdEnv ?? `${prefix}_CLIENT_ID`,
+    clientSecretEnv: input.clientSecretEnv ?? `${prefix}_CLIENT_SECRET`,
+  };
+}

package/src/oauth-exchange.ts

@@ -4,16 +4,18 @@
 // token is verified here, so no caller downstream can forget to.
 
 import type { Clock } from '@ultimat3/core';
-import { EnvMissingError, systemClock } from '@ultimat3/core';
-import { oauthExchangeFailed } from './errors';
+import { EnvMissingError, renderCauseValue, systemClock } from '@ultimat3/core';
+import { oauthExchangeFailed, restartAt } from './errors';
 import { type IdTokenClaims, verifyIdToken } from './id-token';
+import { isRecord } from './json';
+import type { IdTokenKeys } from './jwks';
 import {
   assertOAuthCallback,
-  OAUTH_PROVIDERS,
   type OAuthCallback,
   type OAuthHandshake,
   type OAuthProviderId,
 } from './oauth';
+import { providerFor } from './oauth-registry';
 
 /** Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to. */
 export type OAuthFetch = (input: string, init: RequestInit) => Promise<Response>;
@@ -45,6 +47,13 @@ export interface OAuthExchangeOptions {
   /** Injected in tests; production uses the global. */
   readonly fetch?: OAuthFetch | undefined;
   readonly timeoutMs?: number | undefined;
+  /**
+   * Defaults to `'token-endpoint-tls'`, and this is the one call site where that default is
+   * correct: the id token below was read off a TLS response from the provider's own token
+   * endpoint, which is the channel OIDC Core 3.1.3.7 exempts. An app that pins the key set anyway
+   * — a corporate egress proxy, a compliance requirement — passes `providerJwks(providerFor(id))`.
+   */
+  readonly keys?: IdTokenKeys | undefined;
 }
 
 /**
@@ -55,7 +64,7 @@ export function oauthCredentials(
   provider: OAuthProviderId,
   env: Readonly<Record<string, string | undefined>> = Bun.env,
 ): OAuthClientCredentials {
-  const { clientIdEnv, clientSecretEnv } = OAUTH_PROVIDERS[provider];
+  const { clientIdEnv, clientSecretEnv } = providerFor(provider);
   const clientId = env[clientIdEnv]?.trim() ?? '';
   const clientSecret = env[clientSecretEnv]?.trim() ?? '';
   const missing = [
@@ -72,10 +81,16 @@ export function oauthCredentials(
   return { clientId, clientSecret };
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
-/** Prefers the provider's own words; falls back to raw text, capped so a login page can't flood logs. */
+/**
+ * Prefers the provider's own words; falls back to raw text, capped so a login page can't flood logs.
+ *
+ * Every branch but the empty-body sentence is a REMOTE server's bytes, and this string is spliced
+ * into an `X_OAUTH_EXCHANGE_FAILED` cause — so a token endpoint that is compromised, impersonated
+ * or merely behind a hostile proxy could otherwise write a second log line an operator reads as
+ * genuine. Rendered here rather than at the factory because `OAuthExchangeFailure.detail` is
+ * 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> {
   const text = await response.text().catch(() => '');
   if (text === '') return 'the response body was empty';
@@ -83,21 +98,25 @@ export async function providerDetail(response: Response): Promise<string> {
     const parsed: unknown = JSON.parse(text);
     if (isRecord(parsed)) {
       const description = parsed['error_description'] ?? parsed['error'] ?? parsed['message'];
-      if (typeof description === 'string' && description !== '') return description;
+      if (typeof description === 'string' && description !== '') {
+        return renderCauseValue(description);
+      }
     }
   } catch {
     // Not JSON — fall through to the truncated raw text below.
   }
-  return text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text;
+  return renderCauseValue(
+    text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text,
+  );
 }
 
 function fixForStatus(provider: OAuthProviderId, status: number): string {
-  const { clientIdEnv, clientSecretEnv } = OAUTH_PROVIDERS[provider];
+  const { clientIdEnv, clientSecretEnv } = providerFor(provider);
   if (status === 401 || status === 403) {
     return `set ${clientIdEnv} and ${clientSecretEnv} to the current values in the ${provider} app settings`;
   }
   if (status === 400) {
-    return `register this exact redirect_uri in the ${provider} app settings, then restart the flow`;
+    return `register this exact redirect_uri in the ${provider} app settings, then ${restartAt(provider)}`;
   }
   return `retry; if it persists, check the ${provider} status page before changing anything`;
 }
@@ -108,7 +127,7 @@ async function postForm(
   options: OAuthExchangeOptions,
 ): Promise<Record<string, unknown>> {
   const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
-  const url = OAUTH_PROVIDERS[provider].tokenUrl;
+  const url = providerFor(provider).tokenUrl;
 
   let response: Response;
   try {
@@ -166,7 +185,7 @@ async function postForm(
       detail: typeof description === 'string' && description !== '' ? description : error,
       fix:
         error === 'bad_verification_code' || error === 'invalid_grant'
-          ? 'restart the flow — an authorization code is single-use and short-lived'
+          ? `${restartAt(provider)} — an authorization code is single-use and short-lived`
           : fixForStatus(provider, 400),
     });
   }
@@ -183,7 +202,7 @@ export async function exchangeOAuthCode(
   options: OAuthExchangeOptions,
 ): Promise<OAuthTokens> {
   assertOAuthCallback(handshake, callback);
-  const provider = OAUTH_PROVIDERS[handshake.provider];
+  const provider = providerFor(handshake.provider);
   const clock = options.clock ?? systemClock;
 
   const body = new URLSearchParams({
@@ -193,7 +212,9 @@ export async function exchangeOAuthCode(
     client_id: options.credentials.clientId,
     client_secret: options.credentials.clientSecret,
   });
-  if (provider.usesPkce) body.set('code_verifier', handshake.verifier);
+  // Unconditional: PKCE is not provider-dependent, and `OAuthProvider.usesPkce` is the type-level
+  // statement of that — there is no configuration in which this line is skipped.
+  body.set('code_verifier', handshake.verifier);
 
   const payload = await postForm(handshake.provider, body, options);
   const accessToken = payload['access_token'];
@@ -202,7 +223,7 @@ export async function exchangeOAuthCode(
       provider: provider.id,
       stage: 'token',
       detail: 'the response carried no access_token',
-      fix: `confirm the ${provider.id} app grants the scopes in OAUTH_PROVIDERS.${provider.id}.scopes`,
+      fix: `confirm the ${provider.id} app grants the scopes in providerFor('${provider.id}').scopes`,
     });
   }
 
@@ -233,12 +254,13 @@ export async function exchangeOAuthCode(
     claims:
       idToken === null
         ? null
-        : verifyIdToken({
+        : await verifyIdToken({
             provider: handshake.provider,
             idToken,
             clientId: options.credentials.clientId,
             nonce: handshake.nonce,
             clock,
+            keys: options.keys ?? 'token-endpoint-tls',
           }),
   };
 }

package/src/oauth-login-fixture.ts

@@ -0,0 +1,53 @@
+// The fixtures the three `oauth-login` suites share: the frozen instant, a fresh
+// `MemoryAdapter`-backed `Auth`, the two request bodies, the code of a rejection and a JSON
+// `Response`. Shared rather than copied — three suites building their own `Auth` would be three
+// flows that agree only by construction, the same reason `backfill-pass-fixture.ts` exists.
+
+import { frozenClock, isUltimateError } from '@ultimat3/core';
+import { type Auth, defineAuth } from './auth';
+import { MemoryAdapter } from './memory-adapter';
+import type { OAuthTokens } from './oauth-exchange';
+import type { OAuthProfile } from './oauth-profile';
+
+export const NOW = new Date('2026-08-09T12:00:00.000Z');
+
+export const credentials = { clientId: 'client-id', clientSecret: 'client-secret' };
+
+/** One adapter and the `Auth` over it, minted per `beforeEach` — never shared between tests. */
+export const freshAuth = (): { adapter: MemoryAdapter; auth: Auth } => {
+  const adapter = new MemoryAdapter();
+  return {
+    adapter,
+    auth: defineAuth({ adapter, clock: frozenClock(NOW), providers: ['github', 'google'] }),
+  };
+};
+
+export const profile = (overrides: Partial<OAuthProfile> = {}): OAuthProfile => ({
+  provider: 'github',
+  providerAccountId: '583231',
+  email: 'ada@example.com',
+  emailVerified: true,
+  name: 'Ada Lovelace',
+  ...overrides,
+});
+
+export const tokens = (overrides: Partial<OAuthTokens> = {}): OAuthTokens => ({
+  accessToken: 'gho_first',
+  refreshToken: null,
+  expiresAt: null,
+  idToken: null,
+  claims: null,
+  ...overrides,
+});
+
+export const codeOf = async (call: Promise<unknown>): Promise<string> => {
+  try {
+    await call;
+  } catch (error) {
+    return isUltimateError(error) ? error.code : `not-an-UltimateError: ${String(error)}`;
+  }
+  return 'did-not-throw';
+};
+
+export const json = (body: unknown): Response =>
+  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' } });