@opensaas/stack-auth 0.20.1 → 0.22.0

package/src/config/index.ts

@@ -1,11 +1,63 @@
 import type {
   AuthConfig,
+  AuthModelConfig,
   NormalizedAuthConfig,
+  NormalizedAuthModelConfig,
+  NormalizedAuthModels,
   EmailPasswordConfig,
   EmailVerificationConfig,
   PasswordResetConfig,
 } from './types.js'
 
+/**
+ * Default better-auth model names. Used when the developer does not override
+ * `modelName`, preserving the historical `User`/`Session`/`Account`/`Verification`
+ * keys exactly.
+ */
+const DEFAULT_MODEL_NAMES = {
+  user: 'User',
+  session: 'Session',
+  account: 'Account',
+  verification: 'Verification',
+} as const
+
+/**
+ * Resolve a single better-auth model config block into its normalized form,
+ * falling back to the better-auth default model name and an empty column map.
+ * The model's Postgres schema is the per-model `schema` override when present,
+ * otherwise the plugin-level `schema` default (or `undefined` for `public`).
+ */
+function normalizeModelConfig(
+  config: AuthModelConfig | undefined,
+  defaultModelName: string,
+  defaultSchema: string | undefined,
+): NormalizedAuthModelConfig {
+  return {
+    modelName: config?.modelName || defaultModelName,
+    fields: config?.fields || {},
+    schema: config?.schema ?? defaultSchema,
+  }
+}
+
+/**
+ * Resolve the better-auth model config for all four auth models.
+ * `defaultSchema` is the plugin-level `schema` applied to every model unless a
+ * per-model `schema` override is given.
+ */
+function normalizeAuthModels(config: AuthConfig): NormalizedAuthModels {
+  const defaultSchema = config.schema
+  return {
+    user: normalizeModelConfig(config.user, DEFAULT_MODEL_NAMES.user, defaultSchema),
+    session: normalizeModelConfig(config.session, DEFAULT_MODEL_NAMES.session, defaultSchema),
+    account: normalizeModelConfig(config.account, DEFAULT_MODEL_NAMES.account, defaultSchema),
+    verification: normalizeModelConfig(
+      config.verification,
+      DEFAULT_MODEL_NAMES.verification,
+      defaultSchema,
+    ),
+  }
+}
+
 /**
  * Normalize auth configuration with defaults
  */
@@ -47,12 +99,18 @@ export function normalizeAuthConfig(config: AuthConfig): NormalizedAuthConfig {
   // Session fields defaults
   const sessionFields = config.sessionFields || ['userId', 'email', 'name']
 
+  // Resolve better-auth per-model config (modelName + field column maps).
+  // Defaults preserve the historical User/Session/Account/Verification keys.
+  const models = normalizeAuthModels(config)
+
   return {
     emailAndPassword,
     emailVerification,
     passwordReset,
     socialProviders: config.socialProviders || {},
     session,
+    models,
+    schema: config.schema,
     sessionFields,
     extendUserList: config.extendUserList || {},
     sendEmail:

package/src/config/plugin.ts

@@ -1,4 +1,5 @@
-import type { Plugin } from '@opensaas/stack-core'
+import type { Plugin } from '@opensaas/stack-core/extend'
+import { getDbKey } from '@opensaas/stack-core'
 import type { AuthConfig, NormalizedAuthConfig } from './types.js'
 import { normalizeAuthConfig } from './index.js'
 import { getAuthLists } from '../lists/index.js'
@@ -38,8 +39,12 @@ export function authPlugin(config: AuthConfig): Plugin {
     },
 
     init: async (context) => {
-      // Get auth lists from base Better Auth schema
-      const authLists = getAuthLists(normalized.extendUserList)
+      // Derive the auth lists from the better-auth model config (modelName +
+      // field column maps). With no overrides this yields the historical
+      // User/Session/Account/Verification keys; with overrides (e.g.
+      // user.modelName: 'AuthUser') the lists are keyed and column-mapped to
+      // match the developer's live better-auth tables.
+      const authLists = getAuthLists(normalized.extendUserList, normalized.models)
 
       // Extract additional lists from Better Auth plugins
       for (const plugin of normalized.betterAuthPlugins) {
@@ -66,10 +71,18 @@ export function authPlugin(config: AuthConfig): Plugin {
         }
       }
 
-      // Add all auth lists
+      // Add all auth lists.
+      //
+      // The plugin only ever touches its OWN derived keys. When a developer
+      // renames the auth user model (e.g. user.modelName: 'AuthUser'), the
+      // derived key is 'AuthUser' and an app's separate 'User' list is left
+      // untouched — the plugin never extends/overwrites a list it didn't
+      // derive. Extending only kicks in when an existing list shares the
+      // derived key (e.g. the default 'User'), which is the intended
+      // "merge auth fields into my User" behaviour.
       for (const [listName, listConfig] of Object.entries(authLists)) {
         if (context.config.lists[listName]) {
-          // If user defined a User list, extend it with auth fields
+          // A list already exists under this derived key — merge auth fields in.
           context.extendList(listName, {
             fields: listConfig.fields,
             hooks: listConfig.hooks,
@@ -87,7 +100,54 @@ export function authPlugin(config: AuthConfig): Plugin {
       context.setPluginData<NormalizedAuthConfig>('auth', normalized)
     },
 
+    beforeGenerate: (generationConfig) => {
+      // Collect every schema the Auth lists are placed in (per-model schema,
+      // else the plugin-level schema). When none is configured the Auth lists
+      // stay in the default `public` schema and we leave the config untouched —
+      // the greenfield default Prisma schema is unchanged (no `schemas`, no
+      // `previewFeatures`, no `@@schema`).
+      const authSchemas = Array.from(
+        new Set(
+          Object.values(normalized.models)
+            .map((model) => model.schema)
+            .filter((schema): schema is string => Boolean(schema)),
+        ),
+      )
+
+      if (authSchemas.length === 0) {
+        return generationConfig
+      }
+
+      // Multi-schema Prisma requires the datasource to list every schema in use
+      // AND every model to carry an `@@schema`. Merge the auth schema(s) into the
+      // datasource `schemas` array (always including `public` for the app's own
+      // lists), and default any list without an explicit `db.schema` to `public`
+      // so the generated multi-schema schema is coherent and valid.
+      const schemas = Array.from(
+        new Set(['public', ...(generationConfig.db.schemas ?? []), ...authSchemas]),
+      )
+
+      const lists = Object.fromEntries(
+        Object.entries(generationConfig.lists).map(([listKey, listConfig]) => {
+          if (listConfig.db?.schema) {
+            return [listKey, listConfig]
+          }
+          return [listKey, { ...listConfig, db: { ...listConfig.db, schema: 'public' } }]
+        }),
+      )
+
+      return {
+        ...generationConfig,
+        db: { ...generationConfig.db, schemas },
+        lists,
+      }
+    },
+
     runtime: (context) => {
+      // Resolve the user list's context.db key from the configured user model.
+      // context.db is keyed camelCase, so 'User' -> 'user', 'AuthUser' -> 'authUser'.
+      const userDbKey = getDbKey(normalized.models.user.modelName)
+
       // Provide auth-related utilities at runtime
       return {
         /**
@@ -95,9 +155,7 @@ export function authPlugin(config: AuthConfig): Plugin {
          * Uses the access-controlled context to fetch user data
          */
         getUser: async (userId: string) => {
-          // Use 'authUser' if custom User list name was provided, otherwise 'user'
-          const userListKey = 'user' // TODO: Make this configurable based on list name
-          return await context.db[userListKey].findUnique({
+          return await context.db[userDbKey].findUnique({
             where: { id: userId },
           })
         },
@@ -110,8 +168,7 @@ export function authPlugin(config: AuthConfig): Plugin {
           if (!context.session?.userId) {
             return null
           }
-          const userListKey = 'user'
-          return await context.db[userListKey].findUnique({
+          return await context.db[userDbKey].findUnique({
             where: { id: context.session.userId },
           })
         },

package/src/config/types.ts

@@ -82,6 +82,55 @@ export type SessionConfig = {
   updateAge?: boolean
 }
 
+/**
+ * Per-model better-auth configuration block.
+ *
+ * Mirrors better-auth's own `BetterAuthDBOptions` (the `user`/`session`/
+ * `account`/`verification` config a developer already writes): `modelName`
+ * renames the table/list and `fields` maps individual better-auth field names
+ * to database column names. The auth plugin derives its Auth lists from this
+ * config so the generated lists carry the same keys and column maps as the
+ * developer's live better-auth tables.
+ *
+ * @example
+ * ```typescript
+ * authPlugin({
+ *   user: { modelName: 'AuthUser', fields: { name: 'full_name' } },
+ *   session: { modelName: 'AuthSession' },
+ * })
+ * ```
+ */
+export type AuthModelConfig = {
+  /**
+   * The table/list name for this model.
+   * Becomes the OpenSaaS list key (and Prisma model name) and the table `@@map`.
+   * @default the default better-auth model name (e.g. 'User', 'Session')
+   */
+  modelName?: string
+  /**
+   * Map better-auth field names to database column names.
+   * Each entry generates a `@map("column")` on the derived field.
+   *
+   * @example
+   * ```typescript
+   * fields: { name: 'full_name', emailVerified: 'email_verified' }
+   * ```
+   */
+  fields?: Record<string, string>
+  /**
+   * Database schema (Postgres) for this auth model.
+   * Generates a `@@schema("...")` on the derived list, overriding the
+   * plugin-level {@link AuthConfig.schema} for this one model.
+   *
+   * @example
+   * ```typescript
+   * // Place the verification table in a different schema from the rest
+   * verification: { schema: 'auth_internal' }
+   * ```
+   */
+  schema?: string
+}
+
 /**
  * Auth configuration options
  */
@@ -107,9 +156,60 @@ export type AuthConfig = {
   socialProviders?: SocialProvidersConfig
 
   /**
-   * Session configuration
+   * Session configuration.
+   *
+   * Carries session expiry settings as well as the better-auth `session` model
+   * config (`modelName` + field column `fields` maps) used to derive the Auth
+   * session list.
+   */
+  session?: SessionConfig & AuthModelConfig
+
+  /**
+   * better-auth `user` model configuration (modelName + field column maps).
+   * Used to derive the Auth user list's key, table `@@map`, and field `@map`s.
+   *
+   * Custom fields beyond the better-auth basics are added via `extendUserList`.
+   */
+  user?: AuthModelConfig
+
+  /**
+   * better-auth `account` model configuration (modelName + field column maps).
+   */
+  account?: AuthModelConfig
+
+  /**
+   * better-auth `verification` model configuration (modelName + field column maps).
+   */
+  verification?: AuthModelConfig
+
+  /**
+   * Database schema (Postgres) for the generated Auth lists.
+   *
+   * When set, all four Auth lists (user/session/account/verification) are placed
+   * in this schema via `@@schema(...)`, and the stack's multi-schema support is
+   * wired automatically: the datasource `schemas` array gains this schema (plus
+   * `public`) and the `multiSchema` preview feature is enabled. A per-model
+   * {@link AuthModelConfig.schema} overrides this for an individual list.
+   *
+   * Useful for adopting an existing separate-schema better-auth installation
+   * (e.g. an `auth` Postgres schema) so the generated lists diff clean against
+   * the live tables. When unset, the Auth lists stay in the default `public`
+   * schema and no `@@schema` is emitted (greenfield default unchanged).
+   *
+   * Only applies to the `postgresql` provider.
+   *
+   * @example Adopt an `auth`-schema better-auth install
+   * ```typescript
+   * authPlugin({
+   *   schema: 'auth',
+   *   user: { modelName: 'AuthUser' },
+   *   session: { modelName: 'AuthSession' },
+   *   account: { modelName: 'AuthAccount' },
+   *   verification: { modelName: 'AuthVerification' },
+   * })
+   * ```
    */
-  session?: SessionConfig
+  schema?: string
 
   /**
    * Which fields to include in the session object
@@ -202,6 +302,30 @@ export type AuthConfig = {
   }
 }
 
+/**
+ * Resolved per-model auth configuration after normalization.
+ * Always carries a concrete `modelName` (the developer's override or the
+ * better-auth default) and a (possibly empty) `fields` column map. `schema`
+ * carries the resolved Postgres schema for the model (per-model override, else
+ * the plugin-level schema, else `undefined` for the default `public` schema).
+ */
+export type NormalizedAuthModelConfig = {
+  modelName: string
+  fields: Record<string, string>
+  schema?: string
+}
+
+/**
+ * Resolved auth model configuration for all four better-auth models.
+ * Consumed by the Auth-list derivation and the runtime user-key resolution.
+ */
+export type NormalizedAuthModels = {
+  user: NormalizedAuthModelConfig
+  session: NormalizedAuthModelConfig
+  account: NormalizedAuthModelConfig
+  verification: NormalizedAuthModelConfig
+}
+
 /**
  * Internal normalized auth configuration
  * Used after parsing user config
@@ -209,12 +333,31 @@ export type AuthConfig = {
 export type NormalizedAuthConfig = Required<
   Omit<
     AuthConfig,
-    'emailAndPassword' | 'emailVerification' | 'passwordReset' | 'betterAuthPlugins' | 'rateLimit'
+    | 'emailAndPassword'
+    | 'emailVerification'
+    | 'passwordReset'
+    | 'betterAuthPlugins'
+    | 'rateLimit'
+    | 'session'
+    | 'user'
+    | 'account'
+    | 'verification'
+    | 'schema'
   >
 > & {
   emailAndPassword: Required<EmailPasswordConfig>
   emailVerification: Required<EmailVerificationConfig>
   passwordReset: Required<PasswordResetConfig>
+  /** Resolved session expiry settings (model config lives under `models.session`). */
+  session: Required<SessionConfig>
+  /** Resolved better-auth model config (modelName + field column maps + schema) for all auth models. */
+  models: NormalizedAuthModels
+  /**
+   * Plugin-level Postgres schema for the Auth lists, if any. Resolved per-model
+   * schemas live on `models.<model>.schema`; this is the unresolved plugin-level
+   * default (used to wire the datasource `schemas` array during generation).
+   */
+  schema?: string
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Better Auth plugin types are not exposed, must use any
   betterAuthPlugins: any[]
   rateLimit?: {

package/src/index.ts

@@ -34,6 +34,19 @@ export { authPlugin } from './config/plugin.js'
 export type { AuthConfig, NormalizedAuthConfig } from './config/index.js'
 export type * from './config/types.js'
 
+// Pure better-auth config -> Auth lists derivation (advanced use cases)
+export { deriveAuthLists } from './config/derive-auth-lists.js'
+export type { DerivedAuthLists } from './config/derive-auth-lists.js'
+
+// "Adopt existing better-auth tables" recipe — sets the model/schema knobs that
+// match a pre-existing separate-schema better-auth install so a migrating
+// project reaches Schema parity without rebuilding the config by hand.
+export { adoptBetterAuthTables } from './config/adopt-better-auth-tables.js'
+export type {
+  AdoptBetterAuthTablesOptions,
+  AdoptBetterAuthTablesConfig,
+} from './config/adopt-better-auth-tables.js'
+
 // Runtime type exports
 export type { AuthRuntimeServices } from './runtime/types.js'
 

package/src/lists/index.ts

@@ -1,6 +1,6 @@
-import { list } from '@opensaas/stack-core'
-import { text, timestamp, checkbox, relationship } from '@opensaas/stack-core/fields'
 import type { ListConfig, FieldConfig } from '@opensaas/stack-core'
+import type { NormalizedAuthModels } from '../config/types.js'
+import { deriveAuthLists } from '../config/derive-auth-lists.js'
 
 /**
  * Configuration for extending the auto-generated User list
@@ -25,229 +25,69 @@ export type ExtendUserListConfig = {
 }
 
 /**
- * Create the base User list with better-auth required fields
- * This matches the better-auth user schema
+ * The default better-auth model config (no `modelName`/`fields` overrides).
+ * Produces the historical `User`/`Session`/`Account`/`Verification` keys with
+ * their original field shapes. Used by the backwards-compatible
+ * `createUserList`/`getAuthLists` helpers.
+ */
+const DEFAULT_MODELS: NormalizedAuthModels = {
+  user: { modelName: 'User', fields: {} },
+  session: { modelName: 'Session', fields: {} },
+  account: { modelName: 'Account', fields: {} },
+  verification: { modelName: 'Verification', fields: {} },
+}
+
+/**
+ * Create the base User list with better-auth required fields.
+ *
+ * Backwards-compatible helper: derives the default `User` list (keyed `User`,
+ * default field shapes) via {@link deriveAuthLists}.
  */
 export function createUserList(
-  config?: ExtendUserListConfig, // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  config?: ExtendUserListConfig,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 ): ListConfig<any> {
-  return list({
-    fields: {
-      // Better-auth required fields
-      name: text({
-        validation: { isRequired: true },
-      }),
-      email: text({
-        validation: { isRequired: true },
-        isIndexed: 'unique',
-      }),
-      emailVerified: checkbox({
-        defaultValue: false,
-      }),
-      image: text(),
-
-      // Relationships to other auth tables
-      sessions: relationship({
-        ref: 'Session.user',
-        many: true,
-      }),
-      accounts: relationship({
-        ref: 'Account.user',
-        many: true,
-      }),
-
-      // Custom fields from user config
-      ...(config?.fields || {}),
-    },
-    access: config?.access || {
-      operation: {
-        // Anyone can query users (for displaying names, etc.)
-        query: () => true,
-        // Anyone can create a user (sign up)
-        create: () => true,
-        // Only update your own user record
-        update: ({ session, item }) => {
-          if (!session) return false
-          const userId = (session as { userId?: string }).userId
-          const itemId = (item as { id?: string })?.id
-          return userId === itemId
-        },
-        // Only delete your own user record
-        delete: ({ session, item }) => {
-          if (!session) return false
-          const userId = (session as { userId?: string }).userId
-          const itemId = (item as { id?: string })?.id
-          return userId === itemId
-        },
-      },
-    },
-    hooks: config?.hooks,
-  })
+  return deriveAuthLists(DEFAULT_MODELS, config).lists.User
 }
 
 /**
- * Create the Session list for better-auth
- * Stores active user sessions
+ * Create the Session list for better-auth (default `Session` key).
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 export function createSessionList(): ListConfig<any> {
-  return list({
-    fields: {
-      // Session token (stored in cookie, used as primary key)
-      token: text({
-        validation: { isRequired: true },
-        isIndexed: 'unique',
-      }),
-      // Expiration timestamp
-      expiresAt: timestamp(),
-      // Optional: IP address for security
-      ipAddress: text(),
-      // Optional: User agent for security
-      userAgent: text(),
-      // Relationship to user (userId will be auto-generated)
-      user: relationship({
-        ref: 'User.sessions',
-      }),
-    },
-    access: {
-      operation: {
-        // Only the session owner can query their sessions
-        query: ({ session }) => {
-          if (!session) return false
-          const userId = (session as { userId?: string }).userId
-          if (!userId) return false
-          // Return Prisma filter for nested relationship
-          return {
-            user: {
-              id: { equals: userId },
-            },
-          } as Record<string, unknown>
-        },
-        // Better-auth handles session creation
-        create: () => true,
-        // No manual updates
-        update: () => false,
-        // Better-auth handles session deletion (logout)
-        delete: ({ session, item }) => {
-          if (!session) return false
-          const userId = (session as { userId?: string }).userId
-          const itemUserId = (item as { user?: { id?: string } })?.user?.id
-          return userId === itemUserId
-        },
-      },
-    },
-  })
+  return deriveAuthLists(DEFAULT_MODELS).lists.Session
 }
 
 /**
- * Create the Account list for better-auth
- * Stores OAuth provider accounts and credentials
+ * Create the Account list for better-auth (default `Account` key).
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 export function createAccountList(): ListConfig<any> {
-  return list({
-    fields: {
-      // Account identifier from provider
-      accountId: text({
-        validation: { isRequired: true },
-      }),
-      // Provider identifier (e.g., 'github', 'google', 'credentials')
-      providerId: text({
-        validation: { isRequired: true },
-      }),
-      // Relationship to user (userId will be auto-generated)
-      user: relationship({
-        ref: 'User.accounts',
-      }),
-      // OAuth tokens
-      accessToken: text(),
-      refreshToken: text(),
-      accessTokenExpiresAt: timestamp(),
-      refreshTokenExpiresAt: timestamp(),
-      scope: text(),
-      idToken: text(),
-      // Password hash for credential provider (better-auth stores in account table)
-      password: text(),
-    },
-    access: {
-      operation: {
-        // Only the account owner can query their accounts
-        query: ({ session }) => {
-          if (!session) return false
-          const userId = (session as { userId?: string }).userId
-          if (!userId) return false
-          // Return Prisma filter for nested relationship
-          return {
-            user: {
-              id: { equals: userId },
-            },
-          } as Record<string, unknown>
-        },
-        // Better-auth handles account creation
-        create: () => true,
-        // Better-auth handles account updates (token refresh)
-        update: ({ session, item }) => {
-          if (!session) return false
-          const userId = (session as { userId?: string }).userId
-          const itemUserId = (item as { user?: { id?: string } })?.user?.id
-          return userId === itemUserId
-        },
-        // Account owner can delete their accounts
-        delete: ({ session, item }) => {
-          if (!session) return false
-          const userId = (session as { userId?: string }).userId
-          const itemUserId = (item as { user?: { id?: string } })?.user?.id
-          return userId === itemUserId
-        },
-      },
-    },
-  })
+  return deriveAuthLists(DEFAULT_MODELS).lists.Account
 }
 
 /**
- * Create the Verification list for better-auth
- * Stores email verification tokens, password reset tokens, etc.
+ * Create the Verification list for better-auth (default `Verification` key).
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 export function createVerificationList(): ListConfig<any> {
-  return list({
-    fields: {
-      // Identifier (e.g., email address)
-      identifier: text({
-        validation: { isRequired: true },
-      }),
-      // Token value
-      value: text({
-        validation: { isRequired: true },
-      }),
-      // Expiration timestamp
-      expiresAt: timestamp(),
-    },
-    access: {
-      operation: {
-        // No public querying (better-auth handles verification internally)
-        query: () => false,
-        // Better-auth creates verification tokens
-        create: () => true,
-        // No updates
-        update: () => false,
-        // Better-auth deletes used/expired tokens
-        delete: () => true,
-      },
-    },
-  })
+  return deriveAuthLists(DEFAULT_MODELS).lists.Verification
 }
 
 /**
- * Get all auth lists required by better-auth
- * This is the main export used by withAuth()
+ * Get all auth lists required by better-auth.
+ *
+ * Derives the Auth lists from the resolved better-auth model config. When no
+ * `models` are supplied (or none carry overrides), the result is the historical
+ * default set keyed `User`/`Session`/`Account`/`Verification`.
+ *
+ * @param userConfig - Extra User-list fields/access/hooks (from `extendUserList`)
+ * @param models - Resolved better-auth model config; defaults to the better-auth defaults
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
-export function getAuthLists(userConfig?: ExtendUserListConfig): Record<string, ListConfig<any>> {
-  return {
-    User: createUserList(userConfig),
-    Session: createSessionList(),
-    Account: createAccountList(),
-    Verification: createVerificationList(),
-  }
+export function getAuthLists(
+  userConfig?: ExtendUserListConfig,
+  models: NormalizedAuthModels = DEFAULT_MODELS,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+): Record<string, ListConfig<any>> {
+  return deriveAuthLists(models, userConfig || {}).lists
 }