@opensaas/stack-auth 0.39.2 → 0.40.0

package/src/mcp/better-auth.ts

@@ -1,14 +1,5 @@
-/**
- * Better Auth integration for MCP OAuth authentication
- * Provides session handling and authentication utilities
- */
-
 import type { McpSession, McpSessionProvider } from '@opensaas/stack-core/mcp'
 
-/**
- * Better Auth instance type (flexible)
- * Uses minimal typing to avoid tight coupling with better-auth package
- */
 export type BetterAuthInstance = {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Better Auth API types vary by plugins, must use any
   api: any
@@ -65,13 +56,11 @@ export function withMcpAuth(
   handler: (req: Request, session: McpSession) => Promise<Response> | Response,
 ): (req: Request) => Promise<Response> {
   return async (req: Request) => {
-    // Extract MCP session from Better Auth
     const session = await auth.api.getMcpSession({
       headers: req.headers,
     })
 
     if (!session) {
-      // Return 401 with WWW-Authenticate header for OAuth clients
       return new Response(null, {
         status: 401,
         headers: {
@@ -80,7 +69,6 @@ export function withMcpAuth(
       })
     }
 
-    // Call handler with authenticated session
     return handler(req, session)
   }
 }
@@ -118,25 +106,20 @@ export function hasScopes(session: McpSession, requiredScopes: string[]): boolea
   return requiredScopes.every((scope) => session.scopes!.includes(scope))
 }
 
-/**
- * Check if MCP session is expired
- */
 export function isSessionExpired(session: McpSession): boolean {
   if (!session.expiresAt) return false
   return new Date() > session.expiresAt
 }
 
 /**
- * Create OAuth discovery metadata handler
- * Exposes OAuth authorization server metadata for MCP clients
+ * Exposes OAuth authorization server metadata for MCP clients.
  *
- * This should be placed at `/.well-known/oauth-authorization-server/route.ts`
- * Better Auth already handles `/api/auth/.well-known/oauth-authorization-server`
- * but some clients may fail to parse WWW-Authenticate headers
+ * Place at `/.well-known/oauth-authorization-server/route.ts`. Better Auth
+ * already handles `/api/auth/.well-known/oauth-authorization-server`, but
+ * some clients may fail to parse the `WWW-Authenticate` header.
  */
 export function createOAuthDiscoveryHandler(_auth: BetterAuthInstance) {
   return async (req: Request) => {
-    // Delegate to Better Auth's built-in handler
     const authPath = '/api/auth/.well-known/oauth-authorization-server'
     const authUrl = new URL(authPath, req.url)
 
@@ -147,14 +130,12 @@ export function createOAuthDiscoveryHandler(_auth: BetterAuthInstance) {
 }
 
 /**
- * Create OAuth protected resource metadata handler
- * Exposes OAuth protected resource metadata for MCP clients
+ * Exposes OAuth protected resource metadata for MCP clients.
  *
- * This should be placed at `/.well-known/oauth-protected-resource/route.ts`
+ * Place at `/.well-known/oauth-protected-resource/route.ts`.
  */
 export function createOAuthProtectedResourceHandler(_auth: BetterAuthInstance) {
   return async (req: Request) => {
-    // Delegate to Better Auth's built-in handler
     const authPath = '/api/auth/.well-known/oauth-protected-resource'
     const authUrl = new URL(authPath, req.url)
 

package/src/plugins/index.ts

@@ -1,7 +1,6 @@
 /**
- * Re-export Better Auth plugins for convenience
- * This allows users to import plugins from @opensaas/stack-auth/plugins
- * instead of better-auth/plugins
+ * better-auth 1.7 split the MCP plugin out of `better-auth/plugins` into its
+ * own `@better-auth/mcp` package (an optional peer of this package) — see the
+ * 1.7.1 upgrade note in the auth package's CHANGELOG.
  */
-
-export { mcp } from 'better-auth/plugins'
+export { mcp } from '@better-auth/mcp'

package/src/runtime/types.ts

@@ -1,25 +1,17 @@
 /**
- * Type definitions for auth plugin runtime services
- * These types are used for type-safe access to context.plugins.auth
- */
-
-/**
- * Runtime services provided by the auth plugin
- * Available via context.plugins.auth
+ * Runtime services provided by the auth plugin, available via
+ * `context.plugins.auth`.
  */
 export interface AuthRuntimeServices {
   /**
-   * Get user by ID.
    * Resolves through the plugin runtime's `sudo` helper, so the result does
    * not depend on the application's User list access policy (ADR-0013).
    *
-   * @param userId - The ID of the user to fetch
    * @returns User object or null if not found
    */
   getUser: (userId: string) => Promise<unknown>
 
   /**
-   * Get current user from session.
    * Extracts userId from session and fetches user data through the plugin
    * runtime's `sudo` helper — see {@link getUser}.
    *

package/src/server/index.ts

@@ -7,13 +7,9 @@ import type { DatabaseConfig } from '@opensaas/stack-core/internal'
 import type { NormalizedAuthConfig, NormalizedAuthModelConfig } from '../config/types.js'
 
 /**
- * The `BetterAuthOptions` shape produced when an app's own plugin tuple is
- * passed to `buildBetterAuthOptions()`/`createAuth()` — the tuple plus the
- * `nextCookies()` plugin the stack always appends last. Carrying the literal
- * tuple type (rather than the widened `BetterAuthPlugin[]`) is what lets
- * `betterAuth()` re-infer plugin endpoints (e.g. `emailOTP()`'s
- * `api.signInEmailOTP`) and a `customSession()` plugin's replaced session
- * shape from the resulting options object.
+ * `BetterAuthOptions['plugins']` narrowed to the app's literal tuple plus the
+ * appended `nextCookies()` — see {@link buildBetterAuthOptions}'s tuple-typing
+ * doc for why this matters.
  */
 type ResolvedBetterAuthOptions<TPlugins extends readonly BetterAuthPlugin[]> = Omit<
   BetterAuthOptions,
@@ -53,9 +49,6 @@ function assertPluginTupleMatchesResolved(
   }
 }
 
-/**
- * Get better-auth database configuration from OpenSaas config
- */
 function getDatabaseConfig(
   dbConfig: DatabaseConfig,
   context: AccessContext,
@@ -66,10 +59,8 @@ function getDatabaseConfig(
 }
 
 /**
- * Translate a normalized OpenSaaS auth model config into the better-auth
- * per-model options (`modelName` + `fields` column map). Returns `undefined`
- * when there is nothing to override so the running auth instance keeps
- * better-auth's own defaults untouched.
+ * Returns `undefined` when there is nothing to override, so the running auth
+ * instance keeps better-auth's own defaults untouched.
  */
 function toBetterAuthModelOptions(
   model: NormalizedAuthModelConfig,
@@ -156,13 +147,6 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   )
 }
 
-/**
- * Deep-merge `overrides` onto `base`, recursing into plain-object values so a
- * nested addition (one database hook, one session sub-option) merges
- * alongside sibling keys the stack already set there rather than replacing
- * the whole branch. Arrays and any other value type replace outright.
- * `overrides` wins on every key collision.
- */
 function mergeBetterAuthOptions(
   base: Record<string, unknown>,
   overrides: Record<string, unknown>,
@@ -239,7 +223,6 @@ export async function buildBetterAuthOptions<const TPlugins extends readonly Bet
   const resolvedConfig = await Promise.resolve(opensaasConfig)
   const resolvedContext = await Promise.resolve(context)
 
-  // Extract auth config from plugin data
   const authConfig = resolvedConfig._pluginData?.auth as NormalizedAuthConfig | undefined
 
   if (!authConfig) {
@@ -280,13 +263,9 @@ export async function buildBetterAuthOptions<const TPlugins extends readonly Bet
     assertPluginTupleMatchesResolved(plugins, resolvedPlugins)
   }
 
-  // Build better-auth configuration
   const betterAuthConfig: BetterAuthOptions = {
     database: getDatabaseConfig(resolvedConfig.db, resolvedContext),
 
-    // Mirror the per-model config (modelName + field column maps) back to
-    // better-auth so the running auth instance reads/writes the same
-    // tables/columns the OpenSaaS Auth lists were derived from.
     user: toBetterAuthModelOptions(authConfig.models.user),
     session: {
       ...toBetterAuthModelOptions(authConfig.models.session),
@@ -301,7 +280,6 @@ export async function buildBetterAuthOptions<const TPlugins extends readonly Bet
     account: toBetterAuthModelOptions(authConfig.models.account),
     verification: toBetterAuthModelOptions(authConfig.models.verification),
 
-    // Enable email and password if configured
     emailAndPassword: authConfig.emailAndPassword.enabled
       ? {
           enabled: true,
@@ -316,8 +294,8 @@ export async function buildBetterAuthOptions<const TPlugins extends readonly Bet
         }
       : undefined,
 
-    // Email verification (independent of emailAndPassword — also covers
-    // e.g. a social-provider account whose email isn't yet verified)
+    // Independent of `emailAndPassword` — also covers e.g. a social-provider
+    // account whose email isn't yet verified.
     emailVerification: authConfig.emailVerification.enabled
       ? {
           sendVerificationEmail: authConfig.emailVerification.sendVerificationEmail,
@@ -326,10 +304,8 @@ export async function buildBetterAuthOptions<const TPlugins extends readonly Bet
         }
       : undefined,
 
-    // Trust host (required for production)
     trustedOrigins: process.env.BETTER_AUTH_TRUSTED_ORIGINS?.split(',') || [],
 
-    // Social providers
     socialProviders: Object.entries(authConfig.socialProviders)
       .filter(([_, config]) => config?.enabled !== false)
       .reduce(
@@ -345,10 +321,10 @@ export async function buildBetterAuthOptions<const TPlugins extends readonly Bet
         {} as Record<string, { clientId: string; clientSecret: string }>,
       ),
 
-    // Rate limiting configuration. `modelName`/`fields` are only forwarded
-    // when `models.rateLimit` was derived (rateLimit.storage === 'database')
-    // — mirroring the running instance's model options back to the table the
-    // `RateLimit` Auth list was derived from.
+    // `modelName`/`fields` are only forwarded when `models.rateLimit` was
+    // derived (rateLimit.storage === 'database') — mirroring the running
+    // instance's model options back to the table the `RateLimit` Auth list
+    // was derived from.
     rateLimit: authConfig.rateLimit
       ? {
           enabled: authConfig.rateLimit.enabled,
@@ -361,12 +337,10 @@ export async function buildBetterAuthOptions<const TPlugins extends readonly Bet
         }
       : undefined,
 
-    // Pass through any additional Better Auth plugins, then append
-    // nextCookies LAST so it can write the Set-Cookie headers produced by
-    // any auth.api.* call made inside a Next.js server action into Next's
-    // cookie store. This is what makes the server-action auth forms (which
-    // call auth.api.signInEmail/signUpEmail/etc. server-side) actually
-    // persist a session. It must be the final plugin in the array.
+    // nextCookies must be LAST so it can write the Set-Cookie headers
+    // produced by any auth.api.* call inside a Next.js server action into
+    // Next's cookie store — this is what makes the server-action auth forms
+    // actually persist a session.
     plugins: [...resolvedPlugins, nextCookies()],
   }
 
@@ -425,11 +399,9 @@ export function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(
   context: AccessContext | Promise<AccessContext>,
   plugins?: TPlugins,
 ): Auth<BetterAuthOptions> | Auth<ResolvedBetterAuthOptions<TPlugins>> {
-  // Resolve config and context asynchronously
   const configPromise = Promise.resolve(opensaasConfig)
   const contextPromise = Promise.resolve(context)
 
-  // Create auth instance lazily when needed
   type AuthInstance = Auth<BetterAuthOptions> | Auth<ResolvedBetterAuthOptions<TPlugins>>
   let authInstance: AuthInstance | null = null
   let authPromise: Promise<AuthInstance> | null = null
@@ -450,7 +422,6 @@ export function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(
     return authPromise
   }
 
-  // Return a proxy that lazily initializes the auth instance
   return new Proxy({} as AuthInstance, {
     get(_, prop) {
       if (prop === 'then') {
@@ -458,7 +429,6 @@ export function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(
         return undefined
       }
 
-      // Create a lazy wrapper function
       const lazyWrapper = async (...args: unknown[]) => {
         const instance = await getAuthInstance()
         const value = instance[prop as keyof typeof instance]
@@ -468,14 +438,12 @@ export function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(
         return value
       }
 
-      // Return a proxy that supports both direct calls and nested property access
       return new Proxy(lazyWrapper, {
         get(target, subProp) {
           if (subProp === 'then') {
             // Support await on nested properties
             return undefined
           }
-          // Handle nested property access (e.g., auth.api.getSession)
           return async (...args: unknown[]) => {
             const instance = await getAuthInstance()
             const parentValue = instance[prop as keyof typeof instance]
@@ -502,13 +470,6 @@ export function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(
  */
 const unresolvedSessionFieldWarnings = new Set<string>()
 
-/**
- * Warn (once per field, per process) that a `sessionFields` entry could not
- * be resolved from the session shape `auth.api.getSession()` actually
- * returned — naming the field and what keys were available to check, so the
- * gap is visible here instead of surfacing later as an access-control
- * function silently reading `undefined`.
- */
 function warnUnresolvedSessionField(field: string, resolvedSession: Record<string, unknown>): void {
   if (unresolvedSessionFieldWarnings.has(field)) return
   unresolvedSessionFieldWarnings.add(field)
@@ -527,17 +488,6 @@ function warnUnresolvedSessionField(field: string, resolvedSession: Record<strin
   )
 }
 
-/**
- * Resolve a single `sessionFields` entry off the resolved better-auth
- * session (whatever `auth.api.getSession()` returned — the default `{
- * session, user }` shape, or a `customSession` plugin's replaced shape).
- *
- * `userId` is special-cased to the authenticated user's `id` — the
- * documented default apps depend on. Every other name resolves against a
- * fixed precedence so a collision between sources is predictable rather
- * than incidental: a top-level key on the resolved session object, then the
- * `user` object, then the `session` sub-object.
- */
 function resolveSessionField(
   field: string,
   resolvedSession: Record<string, unknown>,
@@ -582,11 +532,8 @@ function resolveSessionField(
  * outage) into "anonymous" is indistinguishable from a mass sign-out under
  * fail-closed access control, so the caller must see it.
  *
- * Not called by any generated code before this helper existed — apps used to
- * hand-roll this same transform against `auth.api.getSession({ headers:
- * await headers() })`. Exported as the single reusable implementation; pass
- * the caller's request headers (e.g. Next.js `await headers()` in a Server
- * Component/action) so a session cookie can actually be resolved.
+ * Pass the caller's request headers (e.g. Next.js `await headers()` in a
+ * Server Component/action) so a session cookie can actually be resolved.
  *
  * `auth` is typed structurally over just the one member this function reads
  * — `api.getSession` — rather than a single concrete `Auth<Options>`

package/src/ui/components/ForgotPasswordForm.tsx

@@ -25,9 +25,6 @@ export type ForgotPasswordFormProps = {
 }
 
 /**
- * Forgot password form component
- * Allows users to request a password reset email
- *
  * Submits through an app-owned server action rather than calling the auth API
  * from the browser. See the "Auth action" contract in `@opensaas/stack-auth/ui`.
  *

package/src/ui/components/ResetPasswordForm.tsx

@@ -42,9 +42,6 @@ export type ResetPasswordFormProps = {
 }
 
 /**
- * Reset password form component
- * Completes a password reset using the token from the reset email.
- *
  * Submits through an app-owned server action rather than calling the auth API
  * from the browser. See the "Auth action" contract in `@opensaas/stack-auth/ui`.
  *
@@ -78,8 +75,6 @@ export function ResetPasswordForm({
   const [error, setError] = useState('')
   const [loading, setLoading] = useState(false)
 
-  // Guard: no token means the user hit this page directly or followed a
-  // malformed/expired link. Don't render a form that can't succeed.
   if (!token) {
     return (
       <div className={`w-full max-w-md mx-auto p-6 ${className}`}>

package/src/ui/components/SignInForm.tsx

@@ -46,9 +46,6 @@ export type SignInFormProps = {
 }
 
 /**
- * Sign in form component
- * Provides email/password sign in and OAuth provider buttons
- *
  * Submits through app-owned server actions rather than calling the auth API
  * from the browser. See the "Auth action" contract in `@opensaas/stack-auth/ui`.
  *
@@ -96,7 +93,6 @@ export function SignInForm({
         throw new Error(cleanAuthErrorMessage(result.error, 'Sign in failed'))
       }
 
-      // If onSuccess is provided, call it. Otherwise, automatically redirect
       if (onSuccess) {
         onSuccess()
       } else {

package/src/ui/components/SignUpForm.tsx

@@ -51,9 +51,6 @@ export type SignUpFormProps = {
 }
 
 /**
- * Sign up form component
- * Provides email/password registration and OAuth provider buttons
- *
  * Submits through app-owned server actions rather than calling the auth API
  * from the browser. See the "Auth action" contract in `@opensaas/stack-auth/ui`.
  *
@@ -90,7 +87,6 @@ export function SignUpForm({
     e.preventDefault()
     setError('')
 
-    // Validate password confirmation
     if (requirePasswordConfirmation && password !== confirmPassword) {
       setError('Passwords do not match')
       return
@@ -105,7 +101,6 @@ export function SignUpForm({
         throw new Error(cleanAuthErrorMessage(result.error, 'Sign up failed'))
       }
 
-      // If onSuccess is provided, call it. Otherwise, automatically redirect
       if (onSuccess) {
         onSuccess()
       } else {

package/src/ui/lib/clean-error-message.ts

@@ -1,10 +1,7 @@
 /**
- * Strip better-call's `[body.field]` validation prefixes from an auth error
- * message so forms can display something user-friendly.
- *
- * Better-auth surfaces validation errors like `[body.password] Password is too
- * short`. This removes those bracketed prefixes and normalises whitespace,
- * falling back to a default when the message is empty or missing.
+ * Strip better-call's `[body.field]` validation prefixes (e.g. `[body.password]
+ * Password is too short`) from an auth error message so forms can display
+ * something user-friendly.
  *
  * Internal to the auth forms — not part of the package's public contract.
  */

package/src/ui/types.ts

@@ -1,12 +1,7 @@
 /**
  * Contract types shared between the pre-built auth forms and the app-owned
- * server actions they invoke.
- *
- * The forms live in this package but never own an `auth` instance. Instead each
- * form receives **Auth actions** as props — `'use server'` functions the app
- * defines against its own better-auth instance. These types are the agreement
- * between the two: the app implements actions matching them, the forms call
- * actions matching them.
+ * `'use server'` actions they invoke instead of owning an `authClient`. See
+ * ADR-0020.
  */
 
 /**
@@ -15,30 +10,22 @@
  */
 export type AuthActionResult = { success: true } | { success: false; error: string }
 
-/** Input to the sign-in action. */
 export type SignInInput = { email: string; password: string }
 
-/** Input to the sign-up action. */
 export type SignUpInput = { name: string; email: string; password: string }
 
-/** Input to the request-password-reset action. */
 export type RequestPasswordResetInput = { email: string }
 
-/** Input to the reset-password action. */
 export type ResetPasswordInput = { token: string; password: string }
 
-/** Signs a user in with email + password. */
 export type SignInAction = (input: SignInInput) => Promise<AuthActionResult>
 
-/** Creates an account with email + password. */
 export type SignUpAction = (input: SignUpInput) => Promise<AuthActionResult>
 
-/** Requests a password-reset email. */
 export type RequestPasswordResetAction = (
   input: RequestPasswordResetInput,
 ) => Promise<AuthActionResult>
 
-/** Completes a password reset using a token from the reset email. */
 export type ResetPasswordAction = (input: ResetPasswordInput) => Promise<AuthActionResult>
 
 /**