@opensaas/stack-auth 0.37.0 → 0.38.0

package/src/server/index.ts

@@ -1,11 +1,58 @@
 import { betterAuth } from 'better-auth'
 import { prismaAdapter } from 'better-auth/adapters/prisma'
 import { nextCookies } from 'better-auth/next-js'
-import type { BetterAuthOptions } from 'better-auth'
-import type { OpenSaasConfig, AccessContext } from '@opensaas/stack-core'
+import type { Auth, BetterAuthOptions, BetterAuthPlugin } from 'better-auth'
+import type { OpenSaasConfig, AccessContext, Session } from '@opensaas/stack-core'
 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.
+ */
+type ResolvedBetterAuthOptions<TPlugins extends readonly BetterAuthPlugin[]> = Omit<
+  BetterAuthOptions,
+  'plugins'
+> & {
+  plugins: [...TPlugins, ReturnType<typeof nextCookies>]
+}
+
+/**
+ * Guard against the supplied plugin tuple silently drifting from the plugin
+ * array actually resolved from `authPlugin({ betterAuthPlugins })` — the
+ * supplied tuple exists for typing only, so if it isn't the exact same
+ * instances in the exact same order, the type it produces would be a lie
+ * about what `betterAuth()` is actually constructed with.
+ */
+function assertPluginTupleMatchesResolved(
+  supplied: readonly BetterAuthPlugin[],
+  resolved: readonly BetterAuthPlugin[],
+): void {
+  if (supplied.length !== resolved.length) {
+    throw new Error(
+      '[@opensaas/stack-auth] The plugin tuple passed to `buildBetterAuthOptions()` / `createAuth()` ' +
+        `has ${supplied.length} plugin(s), but the plugin array resolved from \`authPlugin({ ` +
+        `betterAuthPlugins })\` has ${resolved.length}. Pass the exact same array (without ` +
+        '`nextCookies()` — the stack appends that itself).',
+    )
+  }
+
+  const mismatchIndex = supplied.findIndex((plugin, index) => plugin !== resolved[index])
+  if (mismatchIndex !== -1) {
+    throw new Error(
+      '[@opensaas/stack-auth] The plugin tuple passed to `buildBetterAuthOptions()` / `createAuth()` ' +
+        `does not match the plugin array resolved from \`authPlugin({ betterAuthPlugins })\` at index ` +
+        `${mismatchIndex} (got plugin "${supplied[mismatchIndex]?.id}", expected the same instance as ` +
+        `"${resolved[mismatchIndex]?.id}"). Pass the exact same array — same instances, same order.`,
+    )
+  }
+}
+
 /**
  * Get better-auth database configuration from OpenSaas config
  */
@@ -125,21 +172,55 @@ function mergeBetterAuthOptions(
  * authoritative for everything it models; the app's additions on top become
  * an explicit, reviewable diff instead of a parallel, hand-duplicated config.
  *
- * @example
+ * Called with just `(config, context)`, the return type is the widened
+ * `BetterAuthOptions` — `betterAuth()` infers its plugin/session types from
+ * the *literal* type of the options object, so constructing from this
+ * widened return erases plugin endpoints (e.g. `emailOTP()`'s
+ * `api.signInEmailOTP`) and a `customSession()` plugin's replaced session
+ * shape. **If your app reads `auth.api.*` in typed code and uses either of
+ * those, pass its plugin tuple as the third argument** — the exact same
+ * array already passed to `authPlugin({ betterAuthPlugins })` — so the
+ * return type carries the literal tuple instead:
+ *
  * ```typescript
  * import { betterAuth } from 'better-auth'
+ * import { emailOTP } from 'better-auth/plugins'
  * import { buildBetterAuthOptions } from '@opensaas/stack-auth/server'
  *
+ * export const appBetterAuthPlugins = [emailOTP()] // same array passed to authPlugin({ betterAuthPlugins })
+ *
  * export const auth = betterAuth({
- *   ...(await buildBetterAuthOptions(config, context)),
+ *   ...(await buildBetterAuthOptions(config, context, appBetterAuthPlugins)),
  *   databaseHooks: { user: { create: { after: syncDomainUser } } },
  * })
+ * // auth.api.signInEmailOTP / auth.api.getSession()'s customSession shape are now typed.
  * ```
+ *
+ * The supplied tuple is for typing only — the array actually used at runtime
+ * is always the one resolved from `authPlugin({ betterAuthPlugins })`, with
+ * exactly one `nextCookies()` appended last. Passing a tuple that isn't the
+ * same plugin instances in the same order throws, so the two can't silently
+ * drift apart.
+ *
+ * Note `createAuth()`'s lazy Proxy does not behave identically to a real
+ * `Auth` instance for every property (see its own doc comment) — reach for
+ * this builder plus `betterAuth()` instead when the app reads `auth.api.*`
+ * in typed code.
  */
 export async function buildBetterAuthOptions(
   opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
   context: AccessContext | Promise<AccessContext>,
-): Promise<BetterAuthOptions> {
+): Promise<BetterAuthOptions>
+export async function buildBetterAuthOptions<const TPlugins extends readonly BetterAuthPlugin[]>(
+  opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+  plugins: TPlugins,
+): Promise<ResolvedBetterAuthOptions<TPlugins>>
+export async function buildBetterAuthOptions<const TPlugins extends readonly BetterAuthPlugin[]>(
+  opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+  plugins?: TPlugins,
+): Promise<BetterAuthOptions | ResolvedBetterAuthOptions<TPlugins>> {
   const resolvedConfig = await Promise.resolve(opensaasConfig)
   const resolvedContext = await Promise.resolve(context)
 
@@ -179,6 +260,11 @@ export async function buildBetterAuthOptions(
 
   assertNoUnsupportedPassthroughKeys(authConfig.betterAuthOptions as Record<string, unknown>)
 
+  const resolvedPlugins = authConfig.betterAuthPlugins || []
+  if (plugins) {
+    assertPluginTupleMatchesResolved(plugins, resolvedPlugins)
+  }
+
   // Build better-auth configuration
   const betterAuthConfig: BetterAuthOptions = {
     database: getDatabaseConfig(resolvedConfig.db, resolvedContext),
@@ -259,47 +345,81 @@ export async function buildBetterAuthOptions(
     // 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.
-    plugins: [...(authConfig.betterAuthPlugins || []), nextCookies()],
+    plugins: [...resolvedPlugins, nextCookies()],
   }
 
   return mergeBetterAuthOptions(
     betterAuthConfig as unknown as Record<string, unknown>,
     authConfig.betterAuthOptions as Record<string, unknown>,
-  ) as BetterAuthOptions
+  ) as BetterAuthOptions | ResolvedBetterAuthOptions<TPlugins>
 }
 
 /**
  * Create a better-auth instance from OpenSaas config
  * This should be called once at app startup
  *
- * @example
+ * Returns a lazy `Proxy` (see the caveat below), typed as `Auth<BetterAuthOptions>`
+ * when called with just `(config, context)` — the widened type, same erasure
+ * caveat as {@link buildBetterAuthOptions}'s no-argument form. **If your app
+ * reads `auth.api.*` in typed code and relies on a plugin's endpoints (e.g.
+ * `emailOTP()`) or a `customSession()`'s replaced session shape, pass its
+ * plugin tuple as the third argument** — the exact same array already passed
+ * to `authPlugin({ betterAuthPlugins })` — so the declared type carries the
+ * literal tuple instead:
+ *
  * ```typescript
  * // lib/auth.ts
  * import { createAuth } from '@opensaas/stack-auth/server'
  * import config from '../opensaas.config'
  * import { rawOpensaasContext } from '@/.opensaas/context'
  *
- * export const auth = createAuth(config, rawOpensaasContext)
+ * export const appBetterAuthPlugins = [emailOTP()] // same array passed to authPlugin({ betterAuthPlugins })
+ *
+ * export const auth = createAuth(config, rawOpensaasContext, appBetterAuthPlugins)
  * ```
+ *
+ * As with the builder, the supplied tuple is for typing only, and a tuple
+ * that isn't the same plugin instances in the same order throws.
+ *
+ * **Proxy caveat:** the lazy `Proxy` this returns does not behave identically
+ * to a real `Auth` instance for every property — every access, including a
+ * non-function property, is surfaced through an `async` wrapper (so e.g.
+ * `auth.options` reads back as a `Promise`, not the plain object a real
+ * instance would return synchronously). The declared type does not model
+ * this difference; where it matters, reach for {@link buildBetterAuthOptions}
+ * plus `betterAuth()` instead, which constructs a real instance.
  */
 export function createAuth(
   opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
   context: AccessContext | Promise<AccessContext>,
-) {
+): Auth<BetterAuthOptions>
+export function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(
+  opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+  plugins: TPlugins,
+): Auth<ResolvedBetterAuthOptions<TPlugins>>
+export function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(
+  opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
+  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
-  let authInstance: ReturnType<typeof betterAuth> | null = null
-  let authPromise: Promise<ReturnType<typeof betterAuth>> | null = null
+  type AuthInstance = Auth<BetterAuthOptions> | Auth<ResolvedBetterAuthOptions<TPlugins>>
+  let authInstance: AuthInstance | null = null
+  let authPromise: Promise<AuthInstance> | null = null
 
   async function getAuthInstance() {
     if (authInstance) return authInstance
 
     if (!authPromise) {
       authPromise = (async () => {
-        const betterAuthConfig = await buildBetterAuthOptions(configPromise, contextPromise)
+        const betterAuthConfig = plugins
+          ? await buildBetterAuthOptions(configPromise, contextPromise, plugins)
+          : await buildBetterAuthOptions(configPromise, contextPromise)
         authInstance = betterAuth(betterAuthConfig)
         return authInstance
       })()
@@ -309,7 +429,7 @@ export function createAuth(
   }
 
   // Return a proxy that lazily initializes the auth instance
-  return new Proxy({} as ReturnType<typeof betterAuth>, {
+  return new Proxy({} as AuthInstance, {
     get(_, prop) {
       if (prop === 'then') {
         // Support await on the proxy itself
@@ -355,41 +475,121 @@ export function createAuth(
 }
 
 /**
- * Get session from better-auth and transform it to OpenSaas session format.
+ * Field names already warned about failing to resolve against a session, so a
+ * given field warns at most once per process rather than once per request.
+ */
+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)
+
+  const user = isPlainObject(resolvedSession.user) ? resolvedSession.user : undefined
+  const sessionRow = isPlainObject(resolvedSession.session) ? resolvedSession.session : undefined
+
+  console.warn(
+    `[@opensaas/stack-auth] sessionFields: "${field}" was not found on the resolved session. ` +
+      `Checked its top-level keys (${Object.keys(resolvedSession).join(', ') || 'none'}), ` +
+      `its "user" object (${user ? Object.keys(user).join(', ') || 'none' : 'not present'}), ` +
+      `and its "session" object (${sessionRow ? Object.keys(sessionRow).join(', ') || 'none' : 'not present'}). ` +
+      `The field is omitted from the projected session. A \`customSession\` plugin that nests this ` +
+      `value elsewhere is the app's own to reconcile — see the \`sessionFields\` reference. ` +
+      `This warning will not repeat for "${field}".`,
+  )
+}
+
+/**
+ * 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>,
+): { found: true; value: unknown } | { found: false } {
+  const user = isPlainObject(resolvedSession.user) ? resolvedSession.user : undefined
+
+  if (field === 'userId') {
+    return user && 'id' in user ? { found: true, value: user.id } : { found: false }
+  }
+
+  if (field in resolvedSession) {
+    return { found: true, value: resolvedSession[field] }
+  }
+  if (user && field in user) {
+    return { found: true, value: user[field] }
+  }
+  const sessionRow = isPlainObject(resolvedSession.session) ? resolvedSession.session : undefined
+  if (sessionRow && field in sessionRow) {
+    return { found: true, value: sessionRow[field] }
+  }
+  return { found: false }
+}
+
+/**
+ * Get session from better-auth and transform it to OpenSaas session format —
+ * a flattened projection of `sessionFields` off the *resolved* session
+ * object, not just its `user` sub-object. This is what makes a
+ * `customSession` plugin's fields (added at the top level, or a
+ * session-only field like the admin plugin's `impersonatedBy`) reachable.
+ * See the `sessionFields` reference for the resolution precedence.
+ *
+ * Returns `null` only when there is genuinely no session — a resolved
+ * session with no `user` key (a `customSession` plugin that dropped it) is
+ * still a session and still gets projected, never misreported as anonymous.
+ * A listed field that can't be resolved from the session shape is omitted
+ * and warns once per field per process (see `warnUnresolvedSessionField`)
+ * instead of silently vanishing into an access-control function reading
+ * `undefined`.
  *
- * Not called by any generated code today — apps currently hand-roll this same
- * transform against `auth.api.getSession({ headers: await headers() })` (see
- * `examples/starter-auth/lib/auth.ts`). Exported as a reusable helper for that
- * pattern; 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.
+ * Errors from the underlying `auth.api.getSession()` call propagate rather
+ * than becoming `null` — collapsing a lookup failure (e.g. a session-store
+ * 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.
  */
 export async function getSessionFromAuth(
   auth: ReturnType<typeof betterAuth>,
   sessionFields: string[],
   headers: Headers,
-) {
-  try {
-    const session = await auth.api.getSession({ headers })
+): Promise<Session | null> {
+  const resolvedSession = await auth.api.getSession({ headers })
 
-    if (!session?.user) {
-      return null
-    }
+  if (!resolvedSession) {
+    return null
+  }
 
-    // Build session object with requested fields
-    const result: Record<string, unknown> = {}
+  const resolvedSessionRecord = resolvedSession as Record<string, unknown>
+  const result: Record<string, unknown> = {}
 
-    for (const field of sessionFields) {
-      if (field === 'userId') {
-        result.userId = session.user.id
-      } else if (field in session.user) {
-        result[field] = session.user[field as keyof typeof session.user]
-      }
+  for (const field of sessionFields) {
+    const resolved = resolveSessionField(field, resolvedSessionRecord)
+    if (resolved.found) {
+      result[field] = resolved.value
+    } else {
+      warnUnresolvedSessionField(field, resolvedSessionRecord)
     }
-
-    return result
-  } catch {
-    return null
   }
+
+  return result
 }
 
 export type { BetterAuthOptions }

package/src/server/schema-converter.ts

@@ -12,13 +12,13 @@ import type { ListConfig, FieldConfig } from '@opensaas/stack-core'
  * Inferred from better-auth internal types
  */
 type BetterAuthFieldAttribute = {
-  type: string // 'string' | 'number' | 'boolean' | 'date' | etc.
+  type: string | string[] // 'string' | 'number' | 'boolean' | 'date' | etc., or an enum array
   required?: boolean
   unique?: boolean
   references?: {
     model: string
     field: string
-    onDelete?: 'cascade' | 'set null' | 'restrict'
+    onDelete?: 'no action' | 'restrict' | 'cascade' | 'set null' | 'set default'
   }
   defaultValue?: unknown
   returned?: boolean
@@ -29,7 +29,7 @@ type BetterAuthFieldAttribute = {
  * Better Auth table schema structure
  */
 type BetterAuthTableSchema = {
-  modelName: string
+  modelName?: string
   fields: Record<string, BetterAuthFieldAttribute>
 }
 

package/tests/server.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import type { BetterAuthOptions } from 'better-auth'
 import type { NormalizedAuthConfig } from '../src/config/types.js'
 import type { OpenSaasConfig, AccessContext } from '@opensaas/stack-core'
@@ -481,6 +481,108 @@ describe('buildBetterAuthOptions / createAuth parity', () => {
     expect(betterAuthMock).toHaveBeenCalledTimes(1)
     expect(betterAuthMock.mock.calls[0][0]).toEqual(built)
   })
+
+  it('createAuth with a plugin tuple constructs betterAuth with exactly what buildBetterAuthOptions returns for the same tuple', async () => {
+    const pluginA = { id: 'plugin-a' }
+    const authConfig = makeAuthConfig({ betterAuthPlugins: [pluginA] })
+    const opensaasConfig = makeOpensaasConfig(authConfig)
+    const context = makeContext()
+
+    const built = await buildBetterAuthOptions(opensaasConfig, context, [pluginA])
+
+    const auth = createAuth(opensaasConfig, context, [pluginA])
+    await auth.api.getSession({})
+
+    expect(betterAuthMock).toHaveBeenCalledTimes(1)
+    expect(betterAuthMock.mock.calls[0][0]).toEqual(built)
+  })
+
+  it('createAuth rejects when its plugin tuple does not match the resolved betterAuthPlugins', async () => {
+    const pluginA = { id: 'plugin-a' }
+    const differentInstance = { id: 'plugin-a' }
+    const authConfig = makeAuthConfig({ betterAuthPlugins: [pluginA] })
+    const opensaasConfig = makeOpensaasConfig(authConfig)
+    const context = makeContext()
+
+    const auth = createAuth(opensaasConfig, context, [differentInstance])
+
+    await expect(auth.api.getSession({})).rejects.toThrow(
+      /does not match the plugin array resolved/,
+    )
+    expect(betterAuthMock).not.toHaveBeenCalled()
+  })
+})
+
+describe('buildBetterAuthOptions plugin-tuple argument', () => {
+  beforeEach(() => {
+    betterAuthMock.mockClear()
+    prismaAdapterMock.mockClear()
+    nextCookiesMock.mockClear()
+  })
+
+  it('rejects when the supplied tuple has a different length than the resolved betterAuthPlugins', async () => {
+    const pluginA = { id: 'plugin-a' }
+    const authConfig = makeAuthConfig({ betterAuthPlugins: [pluginA] })
+
+    await expect(
+      buildBetterAuthOptions(makeOpensaasConfig(authConfig), makeContext(), []),
+    ).rejects.toThrow(/has 0 plugin\(s\), but the plugin array resolved.*has 1/)
+  })
+
+  it('rejects naming the mismatching index when a supplied plugin is not the same instance', async () => {
+    const pluginA = { id: 'plugin-a' }
+    const pluginB = { id: 'plugin-b' }
+    const differentInstance = { id: 'plugin-a' } // same id, different identity
+
+    const authConfig = makeAuthConfig({ betterAuthPlugins: [pluginA, pluginB] })
+
+    await expect(
+      buildBetterAuthOptions(makeOpensaasConfig(authConfig), makeContext(), [
+        differentInstance,
+        pluginB,
+      ]),
+    ).rejects.toThrow(/at index 0/)
+  })
+
+  it('rejects naming the mismatching index when the supplied order differs', async () => {
+    const pluginA = { id: 'plugin-a' }
+    const pluginB = { id: 'plugin-b' }
+    const authConfig = makeAuthConfig({ betterAuthPlugins: [pluginA, pluginB] })
+
+    await expect(
+      buildBetterAuthOptions(makeOpensaasConfig(authConfig), makeContext(), [pluginB, pluginA]),
+    ).rejects.toThrow(/at index 0/)
+  })
+
+  it('does not throw when the supplied tuple is the exact same instances in the same order', async () => {
+    const pluginA = { id: 'plugin-a' }
+    const pluginB = { id: 'plugin-b' }
+    const authConfig = makeAuthConfig({ betterAuthPlugins: [pluginA, pluginB] })
+
+    const config = await buildBetterAuthOptions(makeOpensaasConfig(authConfig), makeContext(), [
+      pluginA,
+      pluginB,
+    ])
+
+    expect(config.plugins).toEqual([pluginA, pluginB, { id: 'next-cookies' }])
+  })
+
+  it('appends exactly one nextCookies() plugin, last, whether or not a plugin tuple is supplied', async () => {
+    const pluginA = { id: 'plugin-a' }
+    const authConfig = makeAuthConfig({ betterAuthPlugins: [pluginA] })
+    const opensaasConfig = makeOpensaasConfig(authConfig)
+    const context = makeContext()
+
+    const withoutArg = await buildBetterAuthOptions(opensaasConfig, context)
+    expect(nextCookiesMock).toHaveBeenCalledTimes(1)
+    expect(withoutArg.plugins).toEqual([pluginA, { id: 'next-cookies' }])
+
+    nextCookiesMock.mockClear()
+
+    const withArg = await buildBetterAuthOptions(opensaasConfig, context, [pluginA])
+    expect(nextCookiesMock).toHaveBeenCalledTimes(1)
+    expect(withArg.plugins).toEqual([pluginA, { id: 'next-cookies' }])
+  })
 })
 
 describe('getSessionFromAuth', () => {
@@ -504,14 +606,118 @@ describe('getSessionFromAuth', () => {
     expect(result).toBeNull()
   })
 
-  it('returns null when auth.api.getSession throws', async () => {
+  it('propagates an error thrown by the underlying session lookup, distinguishable from no session', async () => {
     const getSession = vi.fn(async () => {
       throw new Error('boom')
     })
     const auth = { api: { getSession } } as unknown as Parameters<typeof getSessionFromAuth>[0]
 
-    const result = await getSessionFromAuth(auth, ['userId'], new Headers())
+    await expect(getSessionFromAuth(auth, ['userId'], new Headers())).rejects.toThrow('boom')
+  })
 
-    expect(result).toBeNull()
+  it('resolves the documented happy path unchanged: fields on the user, userId from user.id', async () => {
+    const getSession = vi.fn(async () => ({
+      user: { id: 'user-1', email: 'a@b.com', name: 'Ada' },
+    }))
+    const auth = { api: { getSession } } as unknown as Parameters<typeof getSessionFromAuth>[0]
+
+    const result = await getSessionFromAuth(auth, ['userId', 'email', 'name'], new Headers())
+
+    expect(result).toEqual({ userId: 'user-1', email: 'a@b.com', name: 'Ada' })
+  })
+
+  it('projects a customSession shape with no top-level user key instead of reporting anonymous', async () => {
+    // A customSession plugin can fully replace the resolved shape (e.g.
+    // nesting fields under a custom key) and drop the `user` object entirely
+    // — that must still be treated as "a session", not "no session".
+    const getSession = vi.fn(async () => ({
+      email: 'nested@example.com',
+      data: { role: 'admin' },
+    }))
+    const auth = { api: { getSession } } as unknown as Parameters<typeof getSessionFromAuth>[0]
+
+    const result = await getSessionFromAuth(auth, ['email'], new Headers())
+
+    expect(result).not.toBeNull()
+    expect(result).toEqual({ email: 'nested@example.com' })
+  })
+
+  it('resolves a field living on the session sub-object, not just the user', async () => {
+    const getSession = vi.fn(async () => ({
+      user: { id: 'user-1' },
+      session: { impersonatedBy: 'admin-1' },
+    }))
+    const auth = { api: { getSession } } as unknown as Parameters<typeof getSessionFromAuth>[0]
+
+    const result = await getSessionFromAuth(auth, ['userId', 'impersonatedBy'], new Headers())
+
+    expect(result).toEqual({ userId: 'user-1', impersonatedBy: 'admin-1' })
+  })
+
+  describe('resolution precedence', () => {
+    it('prefers a top-level key over the same name on user or session (deliberate collision)', async () => {
+      const getSession = vi.fn(async () => ({
+        role: 'top-level-role',
+        user: { role: 'user-role' },
+        session: { role: 'session-role' },
+      }))
+      const auth = { api: { getSession } } as unknown as Parameters<typeof getSessionFromAuth>[0]
+
+      const result = await getSessionFromAuth(auth, ['role'], new Headers())
+
+      expect(result).toEqual({ role: 'top-level-role' })
+    })
+
+    it('prefers the user object over the session sub-object when there is no top-level key', async () => {
+      const getSession = vi.fn(async () => ({
+        user: { role: 'user-role' },
+        session: { role: 'session-role' },
+      }))
+      const auth = { api: { getSession } } as unknown as Parameters<typeof getSessionFromAuth>[0]
+
+      const result = await getSessionFromAuth(auth, ['role'], new Headers())
+
+      expect(result).toEqual({ role: 'user-role' })
+    })
+  })
+
+  // The warn-once cache is module-level state, so these tests re-import the
+  // module fresh via vi.resetModules() — same pattern as the `select` no-op
+  // warning tests in packages/core/tests/context.test.ts.
+  describe('unresolved field warning', () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>
+    let freshGetSessionFromAuth: typeof getSessionFromAuth
+
+    beforeEach(async () => {
+      vi.resetModules()
+      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const mod = await import('../src/server/index.js')
+      freshGetSessionFromAuth = mod.getSessionFromAuth
+    })
+
+    afterEach(() => {
+      warnSpy.mockRestore()
+    })
+
+    it('omits an unresolvable field, warns once naming it, and does not throw', async () => {
+      const getSession = vi.fn(async () => ({ user: { id: 'user-1' } }))
+      const auth = { api: { getSession } } as unknown as Parameters<typeof getSessionFromAuth>[0]
+
+      const result = await freshGetSessionFromAuth(auth, ['userId', 'nickname'], new Headers())
+
+      expect(result).toEqual({ userId: 'user-1' })
+      expect(warnSpy).toHaveBeenCalledTimes(1)
+      expect(warnSpy.mock.calls[0][0]).toContain('"nickname"')
+    })
+
+    it('does not warn again for the same field on a second call', async () => {
+      const getSession = vi.fn(async () => ({ user: { id: 'user-1' } }))
+      const auth = { api: { getSession } } as unknown as Parameters<typeof getSessionFromAuth>[0]
+
+      await freshGetSessionFromAuth(auth, ['nickname'], new Headers())
+      await freshGetSessionFromAuth(auth, ['nickname'], new Headers())
+
+      expect(warnSpy).toHaveBeenCalledTimes(1)
+    })
   })
 })