@opensaas/stack-auth 0.21.0 → 0.22.0

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 authPlugin()
+ * 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
 }

package/src/server/index.ts

@@ -3,7 +3,7 @@ import { prismaAdapter } from 'better-auth/adapters/prisma'
 import type { BetterAuthOptions } from 'better-auth'
 import type { OpenSaasConfig, AccessContext } from '@opensaas/stack-core'
 import type { DatabaseConfig } from '@opensaas/stack-core/internal'
-import type { NormalizedAuthConfig } from '../config/types.js'
+import type { NormalizedAuthConfig, NormalizedAuthModelConfig } from '../config/types.js'
 
 /**
  * Get better-auth database configuration from OpenSaas config
@@ -17,6 +17,22 @@ 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.
+ */
+function toBetterAuthModelOptions(
+  model: NormalizedAuthModelConfig,
+): { modelName?: string; fields?: Record<string, string> } | undefined {
+  const hasFields = Object.keys(model.fields).length > 0
+  const options: { modelName?: string; fields?: Record<string, string> } = {}
+  if (model.modelName) options.modelName = model.modelName
+  if (hasFields) options.fields = model.fields
+  return Object.keys(options).length > 0 ? options : undefined
+}
+
 /**
  * Create a better-auth instance from OpenSaas config
  * This should be called once at app startup
@@ -64,6 +80,20 @@ export function createAuth(
         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),
+            expiresIn: authConfig.session.expiresIn || 604800,
+            updateAge: authConfig.session.updateAge
+              ? (authConfig.session.expiresIn || 604800) / 10
+              : 0,
+          },
+          account: toBetterAuthModelOptions(authConfig.models.account),
+          verification: toBetterAuthModelOptions(authConfig.models.verification),
+
           // Enable email and password if configured
           emailAndPassword: authConfig.emailAndPassword.enabled
             ? {
@@ -72,14 +102,6 @@ export function createAuth(
               }
             : undefined,
 
-          // Configure session
-          session: {
-            expiresIn: authConfig.session.expiresIn || 604800,
-            updateAge: authConfig.session.updateAge
-              ? (authConfig.session.expiresIn || 604800) / 10
-              : 0,
-          },
-
           // Trust host (required for production)
           trustedOrigins: process.env.BETTER_AUTH_TRUSTED_ORIGINS?.split(',') || [],