@opensaas/stack-auth 0.21.0 → 0.23.0

package/src/config/derive-auth-lists.ts

@@ -0,0 +1,323 @@
+/**
+ * Pure `better-auth config → Auth lists` derivation.
+ *
+ * This module is intentionally free of side effects and plugin/runtime
+ * concerns: given the resolved better-auth model config (per-model `modelName`
+ * and `fields` column maps) plus any custom User fields, it produces the four
+ * OpenSaaS Auth lists (user/session/account/verification) with:
+ *
+ *  - list keys taken from each model's `modelName`
+ *  - a table `@@map` (list-level `db.map`) when the key differs from the
+ *    default better-auth model name
+ *  - field-level `@map` (`db.map`) for any better-auth field → column override
+ *  - relationship refs between the auth lists wired to the *derived* keys
+ *    (e.g. `Session.user → AuthUser.sessions`)
+ *
+ * When the developer supplies no `modelName`/`fields` overrides, the output is
+ * byte-for-byte the historical default set keyed `User`/`Session`/`Account`/
+ * `Verification` with the original field shapes — see the unit tests.
+ *
+ * `getAuthLists`/`convertBetterAuthSchema` (and the runtime user-key
+ * resolution) consume this module so derivation lives in exactly one place.
+ */
+
+import { list } from '@opensaas/stack-core'
+import { text, timestamp, checkbox, relationship } from '@opensaas/stack-core/fields'
+import type { ListConfig } from '@opensaas/stack-core'
+import type { ExtendUserListConfig } from '../lists/index.js'
+import type { NormalizedAuthModelConfig, NormalizedAuthModels } from './types.js'
+
+/**
+ * Default better-auth model names — used to decide whether a `@@map` is needed
+ * (only when the configured `modelName` differs from the default).
+ */
+const DEFAULT_MODEL_NAMES = {
+  user: 'User',
+  session: 'Session',
+  account: 'Account',
+  verification: 'Verification',
+} as const
+
+/**
+ * The derived Auth list set together with the keys each list was placed under.
+ * Keys are surfaced separately so callers (plugin add-vs-extend logic, runtime
+ * user-key resolution) don't have to re-derive them.
+ */
+export type DerivedAuthLists = {
+  /** Derived list keys, one per better-auth model. */
+  keys: {
+    user: string
+    session: string
+    account: string
+    verification: string
+  }
+  /** The derived list configs, keyed by their derived list keys. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  lists: Record<string, ListConfig<any>>
+}
+
+/**
+ * Build the list-level `db` config (`timestamps` + `@@map` + `@@schema`) for a
+ * derived list.
+ *
+ * Always opts the list into auto-timestamps (`timestamps: true`). better-auth's
+ * adapter writes `createdAt`/`updatedAt` on every auth row and the schema
+ * converter returns `null` for those columns (it assumes the generator injects
+ * them). Now that auto-timestamps are OFF by default (ADR-0004), each derived
+ * Auth list must opt back in so the generated models keep those columns and
+ * better-auth keeps working.
+ *
+ * When the developer renames the model (e.g. `modelName: 'AuthUser'`), we also
+ * pin the physical table name to that model name via `@@map("AuthUser")` so the
+ * generated list adopts the developer's live table exactly. When a `schema` is
+ * configured (plugin-level or per-model), the list is placed in that Postgres
+ * schema via `@@schema(...)`.
+ *
+ * With no `modelName`/`schema` overrides we emit only `timestamps: true`,
+ * leaving the default `User`/`Session`/... table/schema output unchanged.
+ */
+function listDb(
+  model: NormalizedAuthModelConfig,
+  defaultModelName: string,
+): { timestamps: true; map?: string; schema?: string } {
+  const map = model.modelName !== defaultModelName ? model.modelName : undefined
+  const schema = model.schema
+  return {
+    timestamps: true,
+    ...(map !== undefined ? { map } : {}),
+    ...(schema !== undefined ? { schema } : {}),
+  }
+}
+
+/**
+ * Resolve the `db.map` (`@map` column override) for a better-auth field, or
+ * `undefined` when there is no override (so default output is unchanged).
+ *
+ * The field builders capture `options.db` in a closure when generating Prisma
+ * types, so the column map MUST be passed through the builder's `db` option
+ * rather than patched onto the returned field object.
+ */
+function fieldDb(fieldName: string, fields: Record<string, string>): { map: string } | undefined {
+  const column = fields[fieldName]
+  return column ? { map: column } : undefined
+}
+
+/**
+ * Build the foreign-key `db` config for a `user` relationship, honouring a
+ * `userId` column override from the better-auth `fields` map.
+ */
+function userForeignKeyDb(
+  fields: Record<string, string>,
+): { foreignKey: { map: string } } | undefined {
+  const column = fields.userId
+  return column ? { foreignKey: { map: column } } : undefined
+}
+
+/**
+ * Create the Auth user list, applying derived field column maps + table map and
+ * wiring the session/account relationships to the derived keys.
+ */
+function createUserList(
+  model: NormalizedAuthModelConfig,
+  keys: DerivedAuthLists['keys'],
+  userConfig: ExtendUserListConfig,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+): ListConfig<any> {
+  const f = model.fields
+  return list({
+    fields: {
+      name: text({ validation: { isRequired: true }, db: fieldDb('name', f) }),
+      email: text({
+        validation: { isRequired: true },
+        isIndexed: 'unique',
+        db: fieldDb('email', f),
+      }),
+      emailVerified: checkbox({ defaultValue: false, db: fieldDb('emailVerified', f) }),
+      image: text({ db: fieldDb('image', f) }),
+
+      // Relationships to the other auth lists — refs follow the derived keys.
+      sessions: relationship({ ref: `${keys.session}.user`, many: true }),
+      accounts: relationship({ ref: `${keys.account}.user`, many: true }),
+
+      // Custom fields from user config
+      ...(userConfig.fields || {}),
+    },
+    db: listDb(model, DEFAULT_MODEL_NAMES.user),
+    access: userConfig.access || {
+      operation: {
+        query: () => true,
+        create: () => true,
+        update: ({ session, item }) => {
+          if (!session) return false
+          const userId = (session as { userId?: string }).userId
+          const itemId = (item as { id?: string })?.id
+          return userId === itemId
+        },
+        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: userConfig.hooks,
+  })
+}
+
+/**
+ * Create the Auth session list.
+ */
+function createSessionList(
+  model: NormalizedAuthModelConfig,
+  keys: DerivedAuthLists['keys'],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+): ListConfig<any> {
+  const f = model.fields
+  return list({
+    fields: {
+      token: text({
+        validation: { isRequired: true },
+        isIndexed: 'unique',
+        db: fieldDb('token', f),
+      }),
+      expiresAt: timestamp({ db: fieldDb('expiresAt', f) }),
+      ipAddress: text({ db: fieldDb('ipAddress', f) }),
+      userAgent: text({ db: fieldDb('userAgent', f) }),
+      user: relationship({
+        ref: `${keys.user}.sessions`,
+        db: userForeignKeyDb(f),
+      }),
+    },
+    db: listDb(model, DEFAULT_MODEL_NAMES.session),
+    access: {
+      operation: {
+        query: ({ session }) => {
+          if (!session) return false
+          const userId = (session as { userId?: string }).userId
+          if (!userId) return false
+          return {
+            user: { id: { equals: userId } },
+          } as Record<string, unknown>
+        },
+        create: () => true,
+        update: () => false,
+        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
+        },
+      },
+    },
+  })
+}
+
+/**
+ * Create the Auth account list.
+ */
+function createAccountList(
+  model: NormalizedAuthModelConfig,
+  keys: DerivedAuthLists['keys'],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+): ListConfig<any> {
+  const f = model.fields
+  return list({
+    fields: {
+      accountId: text({ validation: { isRequired: true }, db: fieldDb('accountId', f) }),
+      providerId: text({ validation: { isRequired: true }, db: fieldDb('providerId', f) }),
+      user: relationship({
+        ref: `${keys.user}.accounts`,
+        db: userForeignKeyDb(f),
+      }),
+      accessToken: text({ db: fieldDb('accessToken', f) }),
+      refreshToken: text({ db: fieldDb('refreshToken', f) }),
+      accessTokenExpiresAt: timestamp({ db: fieldDb('accessTokenExpiresAt', f) }),
+      refreshTokenExpiresAt: timestamp({ db: fieldDb('refreshTokenExpiresAt', f) }),
+      scope: text({ db: fieldDb('scope', f) }),
+      idToken: text({ db: fieldDb('idToken', f) }),
+      password: text({ db: fieldDb('password', f) }),
+    },
+    db: listDb(model, DEFAULT_MODEL_NAMES.account),
+    access: {
+      operation: {
+        query: ({ session }) => {
+          if (!session) return false
+          const userId = (session as { userId?: string }).userId
+          if (!userId) return false
+          return {
+            user: { id: { equals: userId } },
+          } as Record<string, unknown>
+        },
+        create: () => true,
+        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
+        },
+        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
+        },
+      },
+    },
+  })
+}
+
+/**
+ * Create the Auth verification list.
+ */
+function createVerificationList(
+  model: NormalizedAuthModelConfig,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+): ListConfig<any> {
+  const f = model.fields
+  return list({
+    fields: {
+      identifier: text({ validation: { isRequired: true }, db: fieldDb('identifier', f) }),
+      value: text({ validation: { isRequired: true }, db: fieldDb('value', f) }),
+      expiresAt: timestamp({ db: fieldDb('expiresAt', f) }),
+    },
+    db: listDb(model, DEFAULT_MODEL_NAMES.verification),
+    access: {
+      operation: {
+        query: () => false,
+        create: () => true,
+        update: () => false,
+        delete: () => true,
+      },
+    },
+  })
+}
+
+/**
+ * Derive the OpenSaaS Auth lists from the resolved better-auth model config.
+ *
+ * @param models - Resolved better-auth per-model config (modelName + field column maps)
+ * @param userConfig - Extra User-list fields/access/hooks supplied via `extendUserList`
+ * @returns The derived list keys and the four Auth list configs keyed by those keys
+ */
+export function deriveAuthLists(
+  models: NormalizedAuthModels,
+  userConfig: ExtendUserListConfig = {},
+): DerivedAuthLists {
+  const keys = {
+    user: models.user.modelName,
+    session: models.session.modelName,
+    account: models.account.modelName,
+    verification: models.verification.modelName,
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  const lists: Record<string, ListConfig<any>> = {
+    [keys.user]: createUserList(models.user, keys, userConfig),
+    [keys.session]: createSessionList(models.session, keys),
+    [keys.account]: createAccountList(models.account, keys),
+    [keys.verification]: createVerificationList(models.verification),
+  }
+
+  return { keys, lists }
+}

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/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 },
           })
         },