@opensaas/stack-auth 0.27.1 → 0.28.0

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

@@ -13,9 +13,12 @@
  *  - 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.
+ * When the developer supplies no `modelName`/`fields` overrides, the output
+ * keeps the historical default keys (`User`/`Session`/`Account`/
+ * `Verification`) and field shapes — see the unit tests. Per ADR-0013, each
+ * list ships with **no** operation-level access unless the caller supplies it
+ * (`accessConfig`, or `userConfig.access` for the user list) — deny-by-default,
+ * not the plugin's former permissive defaults.
  *
  * `getAuthLists`/`convertBetterAuthSchema` (and the runtime user-key
  * resolution) consume this module so derivation lives in exactly one place.
@@ -24,8 +27,9 @@
 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 { RelationshipField } from '@opensaas/stack-core/fields'
 import type { ExtendUserListConfig } from '../lists/index.js'
-import type { NormalizedAuthModelConfig, NormalizedAuthModels } from './types.js'
+import type { AuthAccessConfig, NormalizedAuthModelConfig, NormalizedAuthModels } from './types.js'
 
 /**
  * Default better-auth model names — used to decide whether a `@@map` is needed
@@ -103,24 +107,39 @@ function fieldDb(fieldName: string, fields: Record<string, string>): { map: stri
 }
 
 /**
- * Build the foreign-key `db` config for a `user` relationship, honouring a
- * `userId` column override from the better-auth `fields` map.
+ * Build the `db` config for a `user` relationship (`Session.user` /
+ * `Account.user`), honouring a `userId` column override from the better-auth
+ * `fields` map and mirroring better-auth's own FK shape: no separate FK index
+ * — the index is applied at the field level via `isIndexed: false` — and
+ * `onDelete: Cascade`, so a generated Auth schema diffs clean against a live
+ * better-auth database on both dimensions instead of showing a spurious index
+ * drop and a referential-action change (issue #679).
  */
-function userForeignKeyDb(
-  fields: Record<string, string>,
-): { foreignKey: { map: string } } | undefined {
+function userRelationshipDb(fields: Record<string, string>): NonNullable<RelationshipField['db']> {
   const column = fields.userId
-  return column ? { foreignKey: { map: column } } : undefined
+  return {
+    ...(column ? { foreignKey: { map: column } } : {}),
+    extendPrismaSchema: ({ fkLine, relationLine }) => ({
+      fkLine,
+      relationLine: relationLine.replace('@relation(', '@relation(onDelete: Cascade, '),
+    }),
+  }
 }
 
 /**
  * Create the Auth user list, applying derived field column maps + table map and
  * wiring the session/account relationships to the derived keys.
+ *
+ * Per ADR-0013, the plugin ships no permissive access default: the list is
+ * closed unless the application supplies access via `extendUserList.access`
+ * (takes precedence — it predates the keyed `access` passthrough and is
+ * User-specific) or the `access.user` passthrough.
  */
 function createUserList(
   model: NormalizedAuthModelConfig,
   keys: DerivedAuthLists['keys'],
   userConfig: ExtendUserListConfig,
+  access: AuthAccessConfig['user'],
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 ): ListConfig<any> {
   const f = model.fields
@@ -143,34 +162,21 @@ function createUserList(
       ...(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
-        },
-      },
-    },
+    access: userConfig.access || access,
     hooks: userConfig.hooks,
   })
 }
 
 /**
  * Create the Auth session list.
+ *
+ * Per ADR-0013, the plugin ships no permissive access default — closed unless
+ * the application supplies `access.session`.
  */
 function createSessionList(
   model: NormalizedAuthModelConfig,
   keys: DerivedAuthLists['keys'],
+  access: AuthAccessConfig['session'],
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 ): ListConfig<any> {
   const f = model.fields
@@ -186,39 +192,25 @@ function createSessionList(
       userAgent: text({ db: fieldDb('userAgent', f) }),
       user: relationship({
         ref: `${keys.user}.sessions`,
-        db: userForeignKeyDb(f),
+        isIndexed: false,
+        db: userRelationshipDb(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
-        },
-      },
-    },
+    access,
   })
 }
 
 /**
  * Create the Auth account list.
+ *
+ * Per ADR-0013, the plugin ships no permissive access default — closed unless
+ * the application supplies `access.account`.
  */
 function createAccountList(
   model: NormalizedAuthModelConfig,
   keys: DerivedAuthLists['keys'],
+  access: AuthAccessConfig['account'],
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 ): ListConfig<any> {
   const f = model.fields
@@ -228,7 +220,8 @@ function createAccountList(
       providerId: text({ validation: { isRequired: true }, db: fieldDb('providerId', f) }),
       user: relationship({
         ref: `${keys.user}.accounts`,
-        db: userForeignKeyDb(f),
+        isIndexed: false,
+        db: userRelationshipDb(f),
       }),
       accessToken: text({ db: fieldDb('accessToken', f) }),
       refreshToken: text({ db: fieldDb('refreshToken', f) }),
@@ -239,39 +232,19 @@ function createAccountList(
       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
-        },
-      },
-    },
+    access,
   })
 }
 
 /**
  * Create the Auth verification list.
+ *
+ * Per ADR-0013, the plugin ships no permissive access default — closed unless
+ * the application supplies `access.verification`.
  */
 function createVerificationList(
   model: NormalizedAuthModelConfig,
+  access: AuthAccessConfig['verification'],
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 ): ListConfig<any> {
   const f = model.fields
@@ -282,27 +255,28 @@ function createVerificationList(
       expiresAt: timestamp({ db: fieldDb('expiresAt', f) }),
     },
     db: listDb(model, DEFAULT_MODEL_NAMES.verification),
-    access: {
-      operation: {
-        query: () => false,
-        create: () => true,
-        update: () => false,
-        delete: () => true,
-      },
-    },
+    access,
   })
 }
 
 /**
  * Derive the OpenSaaS Auth lists from the resolved better-auth model config.
  *
+ * Per ADR-0013 the derived lists ship **closed** (no permissive operation
+ * access) unless the application supplies access via `accessConfig` (the
+ * `authPlugin({ access: … })` passthrough, keyed by better-auth model name) or,
+ * for the user list specifically, `userConfig.access` (`extendUserList.access`,
+ * which takes precedence — see {@link AuthAccessConfig}).
+ *
  * @param models - Resolved better-auth per-model config (modelName + field column maps)
  * @param userConfig - Extra User-list fields/access/hooks supplied via `extendUserList`
+ * @param accessConfig - App-authored access for each Auth list, keyed by better-auth model name
  * @returns The derived list keys and the four Auth list configs keyed by those keys
  */
 export function deriveAuthLists(
   models: NormalizedAuthModels,
   userConfig: ExtendUserListConfig = {},
+  accessConfig: AuthAccessConfig = {},
 ): DerivedAuthLists {
   const keys = {
     user: models.user.modelName,
@@ -313,10 +287,10 @@ export function deriveAuthLists(
 
   // 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),
+    [keys.user]: createUserList(models.user, keys, userConfig, accessConfig.user),
+    [keys.session]: createSessionList(models.session, keys, accessConfig.session),
+    [keys.account]: createAccountList(models.account, keys, accessConfig.account),
+    [keys.verification]: createVerificationList(models.verification, accessConfig.verification),
   }
 
   return { keys, lists }

package/src/config/index.ts

@@ -113,6 +113,7 @@ export function normalizeAuthConfig(config: AuthConfig): NormalizedAuthConfig {
     schema: config.schema,
     sessionFields,
     extendUserList: config.extendUserList || {},
+    access: config.access || {},
     sendEmail:
       config.sendEmail ||
       (async ({ to, subject, html }) => {

package/src/config/plugin.ts

@@ -44,23 +44,41 @@ export function authPlugin(config: AuthConfig): Plugin {
       // 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)
+      const authLists = getAuthLists(
+        normalized.extendUserList,
+        normalized.models,
+        normalized.access,
+      )
+
+      // The same base-model list keys the Auth lists above were derived under
+      // (e.g. `user.modelName: 'AuthUser'`). A provider plugin's schema
+      // extension of a base model (e.g. `user`) must resolve against this
+      // remap too, so it lands on the adopted Auth list rather than a
+      // re-derived key that can collide with an unrelated host list.
+      const baseModelKeys = {
+        user: normalized.models.user.modelName,
+        session: normalized.models.session.modelName,
+        account: normalized.models.account.modelName,
+        verification: normalized.models.verification.modelName,
+      }
 
       // Extract additional lists from Better Auth plugins
       for (const plugin of normalized.betterAuthPlugins) {
         if (plugin && typeof plugin === 'object' && 'schema' in plugin) {
           // Plugin has schema property - convert to OpenSaaS lists
           const pluginSchema = plugin.schema
-          const pluginLists = convertBetterAuthSchema(pluginSchema)
+          const pluginLists = convertBetterAuthSchema(pluginSchema, baseModelKeys)
 
           // Add or extend lists from plugin
           for (const [listName, listConfig] of Object.entries(pluginLists)) {
             if (context.config.lists[listName]) {
-              // List exists, extend it
+              // List already exists — merge fields/hooks/mcp in only. Access
+              // control belongs to whoever owns the list; per ADR-0013 an
+              // extension must never carry operation-level access for a
+              // pre-existing list (the plugin engine throws if it does).
               context.extendList(listName, {
                 fields: listConfig.fields,
                 hooks: listConfig.hooks,
-                access: listConfig.access,
                 mcp: listConfig.mcp,
               })
             } else {
@@ -82,11 +100,13 @@ export function authPlugin(config: AuthConfig): Plugin {
       // "merge auth fields into my User" behaviour.
       for (const [listName, listConfig] of Object.entries(authLists)) {
         if (context.config.lists[listName]) {
-          // A list already exists under this derived key — merge auth fields in.
+          // A list already exists under this derived key — merge auth fields
+          // in only. Access control belongs to whoever owns the list (the
+          // application declared it first), so the plugin never forwards its
+          // own access here — see ADR-0013.
           context.extendList(listName, {
             fields: listConfig.fields,
             hooks: listConfig.hooks,
-            access: listConfig.access,
             mcp: listConfig.mcp,
           })
         } else {
@@ -143,7 +163,7 @@ export function authPlugin(config: AuthConfig): Plugin {
       }
     },
 
-    runtime: (context) => {
+    runtime: (context, sudo) => {
       // 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)
@@ -151,24 +171,27 @@ export function authPlugin(config: AuthConfig): Plugin {
       // Provide auth-related utilities at runtime
       return {
         /**
-         * Get user by ID
-         * Uses the access-controlled context to fetch user data
+         * Get user by ID.
+         *
+         * Resolves through `sudo()` (per ADR-0013): the User list ships closed
+         * by default, and "who is this session" must not depend on the
+         * application's User access policy.
          */
         getUser: async (userId: string) => {
-          return await context.db[userDbKey].findUnique({
+          return await sudo().db[userDbKey].findUnique({
             where: { id: userId },
           })
         },
 
         /**
-         * Get current user from session
-         * Extracts userId from session and fetches user data
+         * Get current user from session. Extracts userId from session and
+         * fetches user data via `sudo()` — see {@link getUser}.
          */
         getCurrentUser: async () => {
           if (!context.session?.userId) {
             return null
           }
-          return await context.db[userDbKey].findUnique({
+          return await sudo().db[userDbKey].findUnique({
             where: { id: context.session.userId },
           })
         },

package/src/config/types.ts

@@ -1,3 +1,4 @@
+import type { ListConfig } from '@opensaas/stack-core'
 import type { ExtendUserListConfig } from '../lists/index.js'
 
 /**
@@ -100,6 +101,52 @@ export type SessionConfig = {
  * })
  * ```
  */
+/**
+ * App-authored operation + field-level access control for the Auth lists,
+ * keyed by better-auth model name (not by the derived list key, so it stays
+ * remap-proof when e.g. `user.modelName: 'AuthUser'`).
+ *
+ * Per ADR-0013, the auth plugin ships its created lists (User/Session/
+ * Account/Verification) **closed** — no permissive defaults. This is the
+ * application's seam to grant them access: the plugin applies each entry to
+ * the corresponding list when it creates it (its own `addList` path), so the
+ * access rides along with the list's `@@map`/`@@schema`/fields and can't
+ * drift from the plugin's shape. A model with no entry here stays closed
+ * (deny-by-default).
+ *
+ * @example
+ * ```typescript
+ * authPlugin({
+ *   access: {
+ *     // Signed-in users can read the directory; only self can write.
+ *     user: {
+ *       operation: {
+ *         query: ({ session }) => !!session,
+ *         update: ({ session, item }) => session?.userId === item.id,
+ *       },
+ *     },
+ *     // A user can read only their own sessions.
+ *     session: {
+ *       operation: {
+ *         query: ({ session }) =>
+ *           session ? { user: { id: { equals: session.userId } } } : false,
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export type AuthAccessConfig = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  user?: ListConfig<any>['access']
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  session?: ListConfig<any>['access']
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  account?: ListConfig<any>['access']
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  verification?: ListConfig<any>['access']
+}
+
 export type AuthModelConfig = {
   /**
    * The table/list name for this model.
@@ -239,6 +286,23 @@ export type AuthConfig = {
    */
   extendUserList?: ExtendUserListConfig
 
+  /**
+   * App-authored access control for the Auth lists (User/Session/Account/
+   * Verification), keyed by better-auth model name. See {@link AuthAccessConfig}.
+   *
+   * Per ADR-0013 the auth plugin ships these lists **closed** by default — a
+   * model with no entry here denies every operation (`context.db` reads/writes
+   * return `null`/`[]` and the list doesn't surface in the admin UI). Grant
+   * access explicitly for any Auth list your application reads or writes
+   * through `context.db`.
+   *
+   * For the `user` model specifically, {@link ExtendUserListConfig.access}
+   * (via `extendUserList.access`) is still honoured and takes precedence over
+   * `access.user` if both are set — it predates this option and remains the
+   * narrower, User-specific override.
+   */
+  access?: AuthAccessConfig
+
   /**
    * Custom email sending function for verification and password reset
    * If not provided, emails will be logged to console

package/src/lists/index.ts

@@ -1,5 +1,5 @@
 import type { ListConfig, FieldConfig } from '@opensaas/stack-core'
-import type { NormalizedAuthModels } from '../config/types.js'
+import type { AuthAccessConfig, NormalizedAuthModels } from '../config/types.js'
 import { deriveAuthLists } from '../config/derive-auth-lists.js'
 
 /**
@@ -12,8 +12,12 @@ export type ExtendUserListConfig = {
    */
   fields?: Record<string, FieldConfig>
   /**
-   * Access control for the User list
-   * If not provided, defaults to basic access control (users can update their own records)
+   * Access control for the User list.
+   *
+   * Per ADR-0013, if neither this nor `authPlugin({ access: { user: … } })` is
+   * provided, the User list is **closed** (deny-by-default) — it no longer
+   * defaults to permissive access. Takes precedence over `access.user` when
+   * both are set.
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   access?: ListConfig<any>['access']
@@ -83,11 +87,13 @@ export function createVerificationList(): ListConfig<any> {
  *
  * @param userConfig - Extra User-list fields/access/hooks (from `extendUserList`)
  * @param models - Resolved better-auth model config; defaults to the better-auth defaults
+ * @param accessConfig - App-authored access for each Auth list, keyed by better-auth model name
  */
 export function getAuthLists(
   userConfig?: ExtendUserListConfig,
   models: NormalizedAuthModels = DEFAULT_MODELS,
+  accessConfig?: AuthAccessConfig,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 ): Record<string, ListConfig<any>> {
-  return deriveAuthLists(models, userConfig || {}).lists
+  return deriveAuthLists(models, userConfig || {}, accessConfig || {}).lists
 }

package/src/runtime/types.ts

@@ -9,17 +9,19 @@
  */
 export interface AuthRuntimeServices {
   /**
-   * Get user by ID
-   * Uses the access-controlled context to fetch user data
+   * Get user by ID.
+   * Resolves through the plugin runtime's `sudo` helper, so the result does
+   * not depend on the application's User list access policy (ADR-0013).
    *
    * @param userId - The ID of the user to fetch
-   * @returns User object or null if not found or access denied
+   * @returns User object or null if not found
    */
   getUser: (userId: string) => Promise<unknown>
 
   /**
-   * Get current user from session
-   * Extracts userId from session and fetches user data
+   * Get current user from session.
+   * Extracts userId from session and fetches user data through the plugin
+   * runtime's `sudo` helper — see {@link getUser}.
    *
    * @returns Current user object or null if not authenticated or not found
    */