better-ship 0.4.0 → 0.5.0

package/src/infrastructure/better-auth/options.ts

@@ -0,0 +1,232 @@
+import type {
+  BetterAuthOptions,
+  BetterAuthPlugin,
+  BetterAuthRateLimitStorage,
+  DBAdapterInstance,
+} from 'better-auth'
+import { isAPIError } from 'better-auth/api'
+import {
+  anonymous,
+  bearer,
+  captcha,
+  deviceAuthorization,
+  lastLoginMethod,
+  magicLink,
+  openAPI,
+  type CloudflareTurnstileOptions,
+  type LastLoginMethodOptions,
+} from 'better-auth/plugins'
+import { v7 as uuidv7 } from 'uuid'
+
+import { createLogger } from '@/core'
+
+const logger = createLogger('auth')
+
+// Better Auth does not export its default captcha paths; keep them when adding magic-link requests.
+const MAGIC_LINK_CAPTCHA_ENDPOINTS = [
+  '/sign-up/email',
+  '/sign-in/email',
+  '/request-password-reset',
+  '/sign-in/magic-link',
+]
+
+/**
+ * Shared policy from Porte and Typist. The factory merges application overrides into these defaults.
+ */
+export const authDefaults = {
+  onAPIError: {
+    throw: false,
+    onError(error) {
+      if (isAPIError(error) && error.statusCode < 500) return
+      logger.error('auth_operation_failed', { error })
+    },
+  },
+  rateLimit: { window: 60, max: 100 },
+  session: {
+    expiresIn: 60 * 60 * 24 * 7,
+    updateAge: 60 * 60 * 24,
+    freshAge: 60 * 60 * 24,
+    cookieCache: { enabled: true, maxAge: 300 },
+  },
+  advanced: {
+    database: { generateId: () => uuidv7(), joins: true },
+    ipAddress: { ipAddressHeaders: ['cf-connecting-ip', 'x-forwarded-for'] },
+  },
+} satisfies BetterAuthOptions
+
+/** Configure built-in plugins with native options. Runtime auth requires captcha; lastLoginMethod is enabled unless explicitly disabled. */
+export type AuthPluginOptions = {
+  readonly magicLink?: Parameters<typeof magicLink>[0]
+  readonly anonymous?: NonNullable<Parameters<typeof anonymous>[0]>
+  readonly captcha?: Omit<CloudflareTurnstileOptions, 'provider'>
+  readonly lastLoginMethod?: false | NonNullable<Parameters<typeof lastLoginMethod>[0]>
+  readonly openAPI?: NonNullable<Parameters<typeof openAPI>[0]>
+  readonly bearer?: NonNullable<Parameters<typeof bearer>[0]>
+  readonly deviceAuthorization?: NonNullable<Parameters<typeof deviceAuthorization>[0]>
+}
+
+/**
+ * Runtime auth requires rate limiting and Turnstile credentials. Schema generation omits both.
+ * Both modes select plugins through `integrations`, so schema generation must repeat the runtime selection.
+ */
+export type AuthConfig = Omit<BetterAuthOptions, 'database' | 'plugins' | 'rateLimit'> & {
+  readonly rateLimit?: Omit<
+    NonNullable<BetterAuthOptions['rateLimit']>,
+    'enabled' | 'storage' | 'customStorage'
+  >
+} & (
+    | {
+        readonly mode?: 'runtime'
+        readonly rateLimitStorage: BetterAuthRateLimitStorage
+        readonly integrations: AuthPluginOptions & {
+          readonly captcha: Omit<CloudflareTurnstileOptions, 'provider'>
+        }
+      }
+    | {
+        readonly mode: 'schema'
+        readonly rateLimitStorage?: never
+        readonly integrations: AuthPluginOptions
+      }
+  )
+
+type PluginTypes = {
+  magicLink: ReturnType<typeof magicLink>
+  anonymous: ReturnType<typeof anonymous>
+  captcha: ReturnType<typeof captcha>
+  lastLoginMethod: ReturnType<typeof lastLoginMethod<{}>>
+  openAPI: ReturnType<typeof openAPI>
+  bearer: ReturnType<typeof bearer>
+  deviceAuthorization: ReturnType<typeof deviceAuthorization>
+}
+
+type LastLoginPlugin<Options extends AuthPluginOptions> = Options extends {
+  readonly lastLoginMethod: infer Settings extends LastLoginMethodOptions
+}
+  ? ReturnType<typeof lastLoginMethod<Settings>>
+  : PluginTypes['lastLoginMethod']
+
+type SelectedPlugin<Options extends AuthPluginOptions, Key extends keyof PluginTypes> =
+  Options extends Record<Key, false | undefined>
+    ? []
+    : Options extends Record<Key, NonNullable<AuthPluginOptions[Key]>>
+      ? [Key extends 'lastLoginMethod' ? LastLoginPlugin<Options> : PluginTypes[Key]]
+      : Key extends 'lastLoginMethod'
+        ? [PluginTypes[Key]]
+        : []
+
+type SelectedPlugins<Options extends AuthPluginOptions> = [
+  ...SelectedPlugin<Options, 'captcha'>,
+  ...SelectedPlugin<Options, 'lastLoginMethod'>,
+  ...SelectedPlugin<Options, 'openAPI'>,
+  ...SelectedPlugin<Options, 'magicLink'>,
+  ...SelectedPlugin<Options, 'anonymous'>,
+  ...SelectedPlugin<Options, 'deviceAuthorization'>,
+  ...SelectedPlugin<Options, 'bearer'>,
+]
+
+type ConfiguredPlugins<Config extends AuthConfig> = SelectedPlugins<Config['integrations']>
+
+type MergeOptions<Defaults, Overrides> = Omit<Defaults, keyof Overrides> & Overrides
+
+type SessionOptions<Config extends AuthConfig> = MergeOptions<
+  typeof authDefaults.session,
+  NonNullable<Config['session']>
+>
+
+type ConfiguredOptions<Config extends AuthConfig, Plugins extends BetterAuthPlugin[]> = Omit<
+  Config,
+  'mode' | 'integrations' | 'rateLimitStorage' | 'rateLimit' | 'session' | 'advanced' | 'onAPIError'
+> & {
+  database: DBAdapterInstance
+  onAPIError: MergeOptions<typeof authDefaults.onAPIError, NonNullable<Config['onAPIError']>>
+  rateLimit: NonNullable<BetterAuthOptions['rateLimit']>
+  session: Omit<SessionOptions<Config>, 'cookieCache'> & {
+    cookieCache: MergeOptions<
+      typeof authDefaults.session.cookieCache,
+      NonNullable<NonNullable<Config['session']>['cookieCache']>
+    >
+  }
+  advanced: MergeOptions<typeof authDefaults.advanced, NonNullable<Config['advanced']>> & {
+    database: MergeOptions<
+      typeof authDefaults.advanced.database,
+      NonNullable<NonNullable<Config['advanced']>['database']>
+    >
+    ipAddress: MergeOptions<
+      typeof authDefaults.advanced.ipAddress,
+      NonNullable<NonNullable<Config['advanced']>['ipAddress']>
+    >
+  }
+  plugins: [...ConfiguredPlugins<Config>, ...Plugins]
+}
+
+/** A required database adapter and application config produce options with inferred plugin and session types. */
+export type BetterAuthOptionsFactory = <
+  const Config extends AuthConfig,
+  const Plugins extends BetterAuthPlugin[] = [],
+>(
+  database: DBAdapterInstance,
+  config: Config,
+  additionalPlugins?: Plugins,
+) => ConfiguredOptions<Config, Plugins>
+
+function buildPlugins<const Options extends AuthPluginOptions>(
+  options: Options,
+): SelectedPlugins<Options> {
+  const plugins: BetterAuthPlugin[] = []
+  if (options.captcha !== undefined) {
+    const captchaOptions = { ...options.captcha }
+    if (options.magicLink !== undefined && captchaOptions.endpoints === undefined)
+      captchaOptions.endpoints = [...MAGIC_LINK_CAPTCHA_ENDPOINTS]
+    plugins.push(captcha({ ...captchaOptions, provider: 'cloudflare-turnstile' }))
+  }
+  if (options.lastLoginMethod !== false) plugins.push(lastLoginMethod(options.lastLoginMethod))
+  if (options.openAPI !== undefined) plugins.push(openAPI(options.openAPI))
+  if (options.magicLink !== undefined)
+    plugins.push(magicLink({ expiresIn: 300, ...options.magicLink }))
+  if (options.anonymous !== undefined) plugins.push(anonymous(options.anonymous))
+  if (options.deviceAuthorization !== undefined)
+    plugins.push(deviceAuthorization(options.deviceAuthorization))
+  if (options.bearer !== undefined) plugins.push(bearer(options.bearer))
+  // SAFETY: Each branch adds exactly the plugin selected by the corresponding configuration key.
+  return plugins as SelectedPlugins<Options>
+}
+
+/**
+ * Build native Better Auth options with shared defaults and configured plugins; both arguments are required.
+ * Pass Stripe and other plugins in the third argument. Put tanstackStartCookies() last.
+ */
+export const createBetterAuthOptions: BetterAuthOptionsFactory = (
+  database,
+  config,
+  additionalPlugins,
+) => {
+  const { mode, integrations, rateLimitStorage, ...options } = config
+  const result: BetterAuthOptions = {
+    ...options,
+    database,
+    onAPIError: { ...authDefaults.onAPIError, ...options.onAPIError },
+    rateLimit:
+      mode === 'schema'
+        ? { enabled: false }
+        : {
+            ...authDefaults.rateLimit,
+            ...options.rateLimit,
+            enabled: true,
+            customStorage: rateLimitStorage,
+          },
+    session: {
+      ...authDefaults.session,
+      ...options.session,
+      cookieCache: { ...authDefaults.session.cookieCache, ...options.session?.cookieCache },
+    },
+    advanced: {
+      ...authDefaults.advanced,
+      ...options.advanced,
+      database: { ...authDefaults.advanced.database, ...options.advanced?.database },
+      ipAddress: { ...authDefaults.advanced.ipAddress, ...options.advanced?.ipAddress },
+    },
+    plugins: [...buildPlugins(integrations), ...(additionalPlugins ?? [])],
+  }
+  // SAFETY: The factory preserves configured field schemas and plugins while merging only the documented default fields.
+  return result as ConfiguredOptions<typeof config, Exclude<typeof additionalPlugins, undefined>>
+}

package/src/infrastructure/better-auth/rate-limit.ts

@@ -0,0 +1,69 @@
+import type { BetterAuthRateLimitStorage } from 'better-auth'
+
+import { AppError, createLogger } from '@/core'
+
+/** Each rule must match its binding's deployed limit and period. Cloudflare accepts only 10 or 60 seconds. */
+export type AuthRateLimitBinding = {
+  readonly binding: Pick<RateLimit, 'limit'>
+  readonly window: 10 | 60
+  readonly max: number
+}
+
+/** A binding failure with no known retry classification. The cause preserves the original failure. */
+export class AuthRateLimitError extends AppError {
+  readonly _tag = 'AuthRateLimitError'
+  readonly classification = 'unknown'
+
+  constructor(cause: unknown) {
+    super('Authentication rate limiter is unavailable', { cause })
+  }
+}
+
+/** No configured binding matches this Better Auth rule. Outage policy cannot bypass a configuration error. */
+export class UnsupportedAuthRateLimitRuleError extends AppError {
+  readonly _tag = 'UnsupportedAuthRateLimitRuleError'
+  readonly classification = 'terminal'
+
+  constructor(
+    readonly window: number,
+    readonly max: number,
+  ) {
+    super('No Cloudflare binding supports the authentication rate limit rule')
+  }
+}
+
+/** Typist allows requests during binding outages. Select block to propagate an error instead. */
+export type AuthRateLimitOptions = {
+  readonly failureMode?: 'allow' | 'block'
+}
+
+/**
+ * Port Typist and Porte's binding adapters with explicit rule matching and configurable outage behavior.
+ * Bindings enforce approximate limits per Cloudflare location; retryAfter is a conservative full window.
+ */
+export function createAuthRateLimitStorage(
+  bindings: readonly AuthRateLimitBinding[],
+  { failureMode = 'allow' }: AuthRateLimitOptions = {},
+): BetterAuthRateLimitStorage {
+  const logger = createLogger('auth-rate-limit')
+  return {
+    async consume(key, rule) {
+      const configured = bindings.find(
+        (entry) => entry.window === rule.window && entry.max === rule.max,
+      )
+      if (configured === undefined)
+        throw new UnsupportedAuthRateLimitRuleError(rule.window, rule.max)
+      try {
+        const { success } = await configured.binding.limit({ key })
+        return { allowed: success, retryAfter: success ? null : rule.window }
+      } catch (cause) {
+        if (failureMode === 'block') throw new AuthRateLimitError(cause)
+        logger.error('rate_limit_binding_failed', {
+          error: cause,
+          details: { window: rule.window, max: rule.max, failureMode },
+        })
+        return { allowed: true, retryAfter: null }
+      }
+    },
+  }
+}

package/src/infrastructure/better-auth/secondary-storage.ts

@@ -0,0 +1,21 @@
+import type { BetterAuthOptions } from 'better-auth'
+
+import type { AuthSecondaryStorage } from '../cloudflare/auth-secondary-storage.ts'
+
+type SecondaryStorage = NonNullable<BetterAuthOptions['secondaryStorage']>
+
+/**
+ * Implement Better Auth's SecondaryStorage interface through the application's AuthSecondaryStorage binding.
+ * Operations preserve TTL and atomic semantics; failures propagate without logging or retries.
+ */
+export function createAuthSecondaryStorage(
+  binding: Pick<DurableObjectNamespace<AuthSecondaryStorage>, 'getByName'>,
+): SecondaryStorage {
+  return {
+    get: (key) => binding.getByName(key).get(),
+    set: (key, value, ttl) => binding.getByName(key).set(value, ttl),
+    delete: (key) => binding.getByName(key).delete(),
+    getAndDelete: (key) => binding.getByName(key).getAndDelete(),
+    increment: (key, ttl) => binding.getByName(key).increment(ttl),
+  }
+}

package/src/infrastructure/better-auth/stripe.ts

@@ -0,0 +1,11 @@
+import { stripe } from '@better-auth/stripe'
+
+/**
+ * Configure the official Stripe plugin with Typist's customer creation policy.
+ * Customers are created at checkout by default. Native plans, callbacks, and overrides remain available.
+ */
+export function createStripePlugin<const Options extends Parameters<typeof stripe>[0]>(
+  options: Options,
+): ReturnType<typeof stripe<Options>> {
+  return stripe({ createCustomerOnSignUp: false, ...options })
+}

package/src/infrastructure/cloudflare/auth-secondary-storage.ts

@@ -0,0 +1,113 @@
+import { DurableObject } from 'cloudflare:workers'
+
+import { AppError } from '@/core'
+
+// Better Auth supplies whole seconds; an omitted TTL retains the value until explicit deletion.
+const MIN_TTL_SECONDS = 1
+const MILLISECONDS_PER_SECOND = 1000
+
+type StoredValue = { value: string; expiresAt: number | null }
+
+/** The supplied TTL cannot produce a valid expiry timestamp. Retrying the same input cannot fix it. */
+export class InvalidTtlError extends AppError {
+  readonly _tag = 'InvalidTtlError'
+  readonly classification = 'terminal'
+
+  constructor() {
+    super('TTL must be positive integer seconds with a safe expiry timestamp')
+  }
+}
+
+/** The stored value cannot be incremented safely. The failed operation leaves it unchanged. */
+export class InvalidCounterError extends AppError {
+  readonly _tag = 'InvalidCounterError'
+  readonly classification = 'terminal'
+
+  constructor() {
+    super('Counter must contain a safe integer that can be incremented')
+  }
+}
+
+/**
+ * Store one Better Auth secondary storage key per object. Export this class from the application's Worker entrypoint.
+ * Schedule cleanup at the caller's expiry; reads enforce expiry even when the alarm runs late.
+ * Requires compatibility date 2026-02-24 or later so deleteAll also removes the alarm atomically.
+ */
+export class AuthSecondaryStorage extends DurableObject {
+  /** Return null for absent or expired values, even when the cleanup alarm has not run. */
+  async get(): Promise<string | null> {
+    const record = await this.ctx.storage.get<StoredValue>('value')
+    return unexpiredRecord(record)?.value ?? null
+  }
+
+  /** Replace the value and its expiry. Omit ttl to keep the value until deletion. */
+  async set(value: string, ttl?: number): Promise<void> {
+    const expiresAt = ttl === undefined ? null : expiry(ttl)
+    await this.ctx.storage.transaction(async (transaction) => {
+      await transaction.put('value', { value, expiresAt })
+      if (expiresAt === null) await transaction.deleteAlarm()
+      else await transaction.setAlarm(expiresAt)
+    })
+  }
+
+  /** Remove the value and its cleanup alarm before answering. */
+  async delete(): Promise<void> {
+    await this.ctx.storage.deleteAll()
+  }
+
+  /** Consume the value once. Concurrent callers receive null after the first successful consumption. */
+  async getAndDelete(): Promise<string | null> {
+    // Storage input gates prevent another request from replacing the value between these operations.
+    const record = await this.ctx.storage.get<StoredValue>('value')
+    await this.ctx.storage.deleteAll()
+    return unexpiredRecord(record)?.value ?? null
+  }
+
+  /** Increment atomically. Apply ttl only when creating a counter or replacing an expired counter. */
+  async increment(ttl: number): Promise<number> {
+    const expiresAt = expiry(ttl)
+    return this.ctx.storage.transaction(async (transaction) => {
+      const record = unexpiredRecord(await transaction.get<StoredValue>('value'))
+      const count = record === undefined ? 1 : nextCount(record.value)
+      await transaction.put('value', {
+        value: String(count),
+        expiresAt: record === undefined ? expiresAt : record.expiresAt,
+      })
+      if (record === undefined) await transaction.setAlarm(expiresAt)
+      return count
+    })
+  }
+
+  /** Delete expired data. An old alarm must not delete a value whose expiry was extended. */
+  override async alarm(): Promise<void> {
+    const record = await this.ctx.storage.get<StoredValue>('value')
+    if (record?.expiresAt === null) return
+    if (record !== undefined && record.expiresAt > Date.now()) {
+      await this.ctx.storage.setAlarm(record.expiresAt)
+      return
+    }
+    await this.ctx.storage.deleteAll()
+  }
+}
+
+function unexpiredRecord(record: StoredValue | undefined): StoredValue | undefined {
+  if (record === undefined) return undefined
+  if (record.expiresAt !== null && record.expiresAt <= Date.now()) return undefined
+  return record
+}
+
+function expiry(ttl: number): number {
+  const expiresAt = Date.now() + ttl * MILLISECONDS_PER_SECOND
+  if (!Number.isSafeInteger(ttl) || ttl < MIN_TTL_SECONDS || !Number.isSafeInteger(expiresAt)) {
+    throw new InvalidTtlError()
+  }
+  return expiresAt
+}
+
+function nextCount(value: string): number {
+  const count = Number(value)
+  if (String(count) !== value || !Number.isSafeInteger(count) || !Number.isSafeInteger(count + 1)) {
+    throw new InvalidCounterError()
+  }
+  return count + 1
+}

package/src/infrastructure/tanstack/auth.middleware.ts

@@ -0,0 +1,89 @@
+import { createMiddleware, type Register, type RequestServerOptions } from '@tanstack/react-start'
+import { getRequestHeaders } from '@tanstack/react-start/server'
+import { getSessionCookie } from 'better-auth/cookies'
+
+import { AuthenticationError, StaleSessionError, createLogger } from '@/core'
+
+const logger = createLogger('auth-middleware')
+
+/** The fields middleware reads; generic callers retain every additional session and user field. */
+export type AuthSession = {
+  readonly user: { readonly id: string }
+  readonly session: { readonly id: string }
+}
+
+/** Authenticated context retains the application's complete user and session types. */
+export type RequiredAuthContext<Session extends AuthSession> = {
+  readonly user: Session['user']
+  readonly session: Session['session']
+}
+
+/** Optional authentication supplies both fields together or neither field. */
+export type AuthContext<Session extends AuthSession> =
+  | RequiredAuthContext<Session>
+  | {
+      readonly user: undefined
+      readonly session: undefined
+    }
+
+/** Select the current request's Better Auth instance from TanStack's registered context. */
+export type AuthMiddlewareOptions<Session extends AuthSession> = {
+  readonly getAuth: (context: RequestServerOptions<Register, undefined>['context']) => {
+    readonly api: {
+      readonly getSession: (options: { headers: Headers }) => Promise<Session | null>
+    }
+  }
+}
+
+/**
+ * Preserve Porte's function and request middleware contracts with application-owned services.
+ * Optional lookup failures log once and continue as guests. Required lookup failures propagate.
+ */
+export function createAuthMiddleware<Session extends AuthSession>(
+  options: AuthMiddlewareOptions<Session>,
+) {
+  const extractAuth = createMiddleware({ type: 'function' }).server<AuthContext<Session>>(
+    async ({ next, context }) => {
+      let resolved: Session | null
+      try {
+        resolved = await options.getAuth(context).api.getSession({ headers: getRequestHeaders() })
+      } catch (error) {
+        logger.error('get_session_failed', { error })
+        resolved = null
+      }
+      if (resolved === null)
+        return next<AuthContext<Session>>({ context: { user: undefined, session: undefined } })
+      return next<AuthContext<Session>>({
+        context: { user: resolved.user, session: resolved.session },
+      })
+    },
+  )
+
+  async function resolveRequiredSession(
+    context: RequestServerOptions<Register, undefined>['context'],
+    headers: Headers,
+  ): Promise<Session> {
+    const resolved = await options.getAuth(context).api.getSession({ headers })
+    if (resolved === null) {
+      if (getSessionCookie(headers)) throw new StaleSessionError()
+      throw new AuthenticationError()
+    }
+    return resolved
+  }
+
+  const requireAuth = createMiddleware({ type: 'function' }).server(async ({ next, context }) => {
+    const resolved = await resolveRequiredSession(context, getRequestHeaders())
+    return next<RequiredAuthContext<Session>>({
+      context: { user: resolved.user, session: resolved.session },
+    })
+  })
+  const requireAuthRequest = createMiddleware({ type: 'request' }).server(
+    async ({ request, next, context }) => {
+      const resolved = await resolveRequiredSession(context, request.headers)
+      return next<RequiredAuthContext<Session>>({
+        context: { user: resolved.user, session: resolved.session },
+      })
+    },
+  )
+  return { extractAuth, requireAuth, requireAuthRequest }
+}

package/src/infrastructure/tanstack/error.middleware.ts

@@ -0,0 +1,81 @@
+import { isNotFound, isRedirect, type AnyRedirect } from '@tanstack/react-router'
+import { createMiddleware, type Register, type RequestServerOptions } from '@tanstack/react-start'
+import type { BetterAuthCookies } from 'better-auth'
+
+import { StaleSessionError, type ErrorTable } from '@/core'
+
+import { createHttpErrorResponseConverter } from './http-error-response.ts'
+import { clearStaleSessionCookies } from './session-cookies.ts'
+import { createErrorPayloadConverter } from './to-error-payload.ts'
+
+type RequestContext = RequestServerOptions<Register, undefined>['context']
+
+/** The part of a Better Auth instance the boundary reads: its computed cookie definitions. */
+export type AuthCookieSource = {
+  readonly $context: Promise<{ readonly authCookies: BetterAuthCookies }>
+}
+
+/** The application's error table, its stale-session redirect, and its Better Auth instance. */
+export type ErrorMiddlewareOptions<Entries> = {
+  readonly errors: ErrorTable<Entries>
+  /** Build the redirect a server function throws for a stale session. */
+  readonly signIn: () => AnyRedirect
+  /** Select the request's Better Auth instance; its cookie definitions say what to clear. */
+  readonly getAuth: (context: RequestContext) => AuthCookieSource
+}
+
+/**
+ * Build both transport boundaries from one error table.
+ * Register `functionErrorMiddleware` globally. Put `routeErrorMiddleware` first in an API route's `server.middleware`.
+ */
+export function createErrorMiddleware<Entries>(options: ErrorMiddlewareOptions<Entries>) {
+  const toErrorPayload = createErrorPayloadConverter(options.errors)
+  const toHttpErrorResponse = createHttpErrorResponseConverter(options.errors)
+
+  async function clearSession(context: RequestContext): Promise<void> {
+    const { authCookies } = await options.getAuth(context).$context
+    clearStaleSessionCookies(authCookies)
+  }
+
+  async function handleFunctionError(cause: unknown, context: RequestContext): Promise<never> {
+    // oxlint-disable-next-line typescript/only-throw-error -- TanStack uses throwable control-flow objects.
+    if (isNotFound(cause) || isRedirect(cause)) throw cause
+    if (cause instanceof StaleSessionError) {
+      await clearSession(context)
+      // oxlint-disable-next-line typescript/only-throw-error -- Router redirects by throwing this.
+      throw options.signIn()
+    }
+    // oxlint-disable-next-line typescript/only-throw-error -- The client rejects with this and reads its tag.
+    throw toErrorPayload(cause)
+  }
+
+  // A route answers 401 instead of a redirect because fetch would follow it into the HTML shell.
+  async function handleRouteError(cause: unknown, context: RequestContext): Promise<Response> {
+    // oxlint-disable-next-line typescript/only-throw-error -- TanStack uses throwable control-flow objects.
+    if (isNotFound(cause) || isRedirect(cause)) throw cause
+    if (cause instanceof StaleSessionError) await clearSession(context)
+    return toHttpErrorResponse(cause)
+  }
+
+  const functionErrorMiddleware = createMiddleware({ type: 'function' }).server(
+    async ({ next, context }) => {
+      try {
+        return await next()
+      } catch (cause) {
+        return handleFunctionError(cause, context)
+      }
+    },
+  )
+
+  const routeErrorMiddleware = createMiddleware({ type: 'request' }).server(
+    async ({ next, context }) => {
+      try {
+        return await next()
+      } catch (cause) {
+        return handleRouteError(cause, context)
+      }
+    },
+  )
+
+  return { functionErrorMiddleware, routeErrorMiddleware, toErrorPayload, toHttpErrorResponse }
+}

package/src/infrastructure/tanstack/http-error-response.ts

@@ -0,0 +1,30 @@
+import { getReasonPhrase } from 'http-status-codes'
+import { z } from 'zod'
+
+import type { ErrorTable, ProblemDetails } from '@/core'
+
+import { resolveFailure } from './resolve-failure.ts'
+
+// A known delay becomes the header; a null delay sends no header.
+const RetryAfterSchema = z.object({ retryAfter: z.number() })
+
+/**
+ * Build the API route converter for one error table.
+ * The body is RFC 9457 problem details; public fields become extension members.
+ */
+export function createHttpErrorResponseConverter<Entries>(table: ErrorTable<Entries>) {
+  return function toHttpErrorResponse(cause: unknown): Response {
+    const { status, payload } = resolveFailure(table, cause)
+    const { _tag, message, ...fields } = payload
+    const body: ProblemDetails = {
+      type: 'about:blank',
+      title: getReasonPhrase(status),
+      detail: message,
+      ...fields,
+    }
+    const headers = new Headers({ 'Content-Type': 'application/problem+json' })
+    const retry = RetryAfterSchema.safeParse(payload)
+    if (retry.success) headers.set('Retry-After', String(retry.data.retryAfter))
+    return Response.json(body, { status, headers })
+  }
+}

package/src/infrastructure/tanstack/index.ts

@@ -0,0 +1,12 @@
+export {
+  createAuthMiddleware,
+  type AuthSession,
+  type AuthContext,
+  type RequiredAuthContext,
+  type AuthMiddlewareOptions,
+} from './auth.middleware.ts'
+export {
+  createErrorMiddleware,
+  type AuthCookieSource,
+  type ErrorMiddlewareOptions,
+} from './error.middleware.ts'