@opensaas/stack-auth 0.36.0 → 0.37.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @opensaas/stack-auth@0.36.0 build /home/runner/work/stack/stack/packages/auth
+> @opensaas/stack-auth@0.37.0 build /home/runner/work/stack/stack/packages/auth
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # @opensaas/stack-auth
 
+## 0.37.0
+
+### Minor Changes
+
+- [#872](https://github.com/OpenSaasAU/stack/pull/872) [`17acf04`](https://github.com/OpenSaasAU/stack/commit/17acf046b494da184c2b77434a7b4d3400ca32f2) Thanks [@borisno2](https://github.com/borisno2)! - `createAuth()` now forwards `AuthConfig` options it previously normalized but silently dropped: `emailAndPassword.minPasswordLength`, `passwordReset.enabled`/`tokenExpiration` (wired to better-auth's `sendResetPassword`), and `emailVerification.enabled`/`sendOnSignUp`/`tokenExpiration` (wired to `sendVerificationEmail`).
+
+  The stack does not wrap these email callbacks in any way — `emailAndPassword.sendResetPassword` and `emailVerification.sendVerificationEmail` are better-auth's own option shape, forwarded straight through, so an app configures them exactly as it would when calling `betterAuth()` directly:
+
+  ```typescript
+  authPlugin({
+    emailAndPassword: {
+      enabled: true,
+      sendResetPassword: async ({ user, url }) => {
+        await resend.emails.send({
+          to: user.email,
+          subject: 'Reset your password',
+          html: `<a href="${url}">Reset your password</a>`,
+        })
+      },
+    },
+    emailVerification: {
+      enabled: true,
+      sendVerificationEmail: async ({ user, url }) => {
+        await resend.emails.send({
+          to: user.email,
+          subject: 'Verify your email',
+          html: `<a href="${url}">Verify your email</a>`,
+        })
+      },
+    },
+  })
+  ```
+
+  If not provided, reset/verification emails are logged to console instead of sent — apps relying on the previous no-op behavior (verification/reset emails silently not sending) will start sending real emails once `emailVerification`/`passwordReset` are enabled and these callbacks are configured.
+
+  Two related fixes, both changing existing behavior:
+
+  - `session.updateAge` is retyped from `boolean` to `number | false` — the number of seconds between session refreshes, passed straight through to better-auth's own `session.updateAge` instead of being computed as `expiresIn / 10`. The default changes from `true` to `86400` (1 day), matching better-auth's own default. Update any `updateAge: true` config to a duration in seconds (e.g. `86400`). `updateAge: false` now correctly maps to better-auth's `disableSessionRefresh: true` (previously it mapped to `updateAge: 0`, which better-auth treats as "refresh on every request" — the opposite of disabling refresh).
+  - `getSessionFromAuth(auth, sessionFields, headers)` gains a required third `headers: Headers` parameter. Previously it always called `auth.api.getSession({ headers: new Headers() })`, an empty header set that could never resolve a session cookie, so the function always returned `null`. Callers must now pass the request's real headers (e.g. Next.js `await headers()`).
+
+  Setting `emailAndPassword.requireConfirmation` (while `emailAndPassword.enabled` is true) now logs a `console.warn` — it has no better-auth server-side equivalent (it's a UI-only "confirm password" concern). Pass `requirePasswordConfirmation` directly to `<SignUpForm>`/`<ResetPasswordForm>` instead. Similarly, `passwordReset.enabled` now warns if `emailAndPassword.enabled` is false, since password reset has no effect without a password-based account.
+
+- [#871](https://github.com/OpenSaasAU/stack/pull/871) [`06375ca`](https://github.com/OpenSaasAU/stack/commit/06375cad571677e92bfe84c35ff55240f3546a1f) Thanks [@{](https://github.com/{)! - Add a per-model `tableName` option, independent of `modelName`, so a renamed Auth list key can still adopt a differently-named live table — most commonly better-auth's own default lowercase table names (`user`, `session`, `account`, `verification`).
+
+  ```typescript
+  authPlugin({
+   modelName: 'AuthUser', tableName: 'user' },
+    session: { modelName: 'AuthSession', tableName: 'session' },
+  })
+  ```
+
+  `adoptBetterAuthTables()` gains matching `useBetterAuthTableNames` and `tableNames` options:
+
+  ```typescript
+  adoptBetterAuthTables({ useBetterAuthTableNames: true })
+  // or explicitly:
+  adoptBetterAuthTables({ tableNames: { user: 'user', session: 'session' } })
+  ```
+
+  With no `tableName` set, behaviour is unchanged: the table name still follows `modelName` when it differs from the better-auth default, otherwise no `@@map` is emitted.
+
+- [#874](https://github.com/OpenSaasAU/stack/pull/874) [`7ef9dbc`](https://github.com/OpenSaasAU/stack/commit/7ef9dbc2f94cc4e7ab831ecafb3ef65159a3c55e) Thanks [@borisno2](https://github.com/borisno2)! - Add a `betterAuthOptions` escape hatch on `AuthConfig` for better-auth options the stack doesn't model, plus an exported `buildBetterAuthOptions()` builder for apps that still need to hand-wire their own `betterAuth()` instance.
+
+  `betterAuthOptions` is deep-merged onto the options `createAuth()` builds, applied last — a plain-object value merges recursively alongside sibling keys the stack already set (e.g. `session: { cookieCache }` doesn't clobber `session.expiresIn`), and wins on any genuine key collision:
+
+  ```typescript
+  authPlugin({
+    betterAuthOptions: {
+      databaseHooks: { user: { create: { after: syncDomainUser } } },
+      session: { cookieCache: { enabled: true, maxAge: 300 } },
+      verification: { storeIdentifier: 'hashed' },
+      baseURL: process.env.BETTER_AUTH_URL,
+    },
+  })
+  ```
+
+  `database`, `plugins`, and `additionalFields` under `user`/`session`/`account`/`verification` are rejected — they already have dedicated seams (`db` config, `betterAuthPlugins`), or have schema consequences a passthrough can't also apply to the generated Prisma schema.
+
+  `buildBetterAuthOptions(config, context)` returns the exact same options object `createAuth()` uses, for apps that need a resolved `betterAuth()` instance rather than `createAuth()`'s lazy proxy:
+
+  ```typescript
+  import { betterAuth } from 'better-auth'
+  import { buildBetterAuthOptions } from '@opensaas/stack-auth/server'
+
+  export const auth = betterAuth({
+    ...(await buildBetterAuthOptions(config, rawOpensaasContext)),
+    databaseHooks: { user: { create: { after: syncDomainUser } } },
+  })
+  ```
+
+- [#870](https://github.com/OpenSaasAU/stack/pull/870) [`7b6189f`](https://github.com/OpenSaasAU/stack/commit/7b6189fa60119a45082ba62dd71d915d93de529c) Thanks [@relationship({](https://github.com/relationship({)! - A relationship field's foreign key can now be declared non-nullable via `db.isNullable: false` — the generated FK column and its relation field lose their `?` together. Omitting the option leaves every existing relationship unchanged (still nullable by default).
+
+  ```typescript
+
+    ref: 'User.sessions',
+    db: { isNullable: false },
+  })
+  // Generates: userId String  (was String?)
+  //            user   User    @relation(...)  (was User?)
+  ```
+
+  `@opensaas/stack-auth`'s derived Auth lists now use this to match better-auth's own Prisma schema: `Session.expiresAt`, `Verification.expiresAt`, and the `Session.user`/`Account.user` foreign keys generate as required instead of nullable.
+
+  **Migration note:** this changes the generated schema for existing greenfield apps. Running `opensaas generate` followed by `prisma db push`/`prisma migrate dev` will produce a migration that adds `NOT NULL` to `Session.expiresAt`, `Verification.expiresAt`, `Session.userId`, and `Account.userId`. Since better-auth's own adapter always writes these columns, no existing row should violate the new constraint — but back up production data before applying, as with any schema migration.
+
+### Patch Changes
+
+- [#867](https://github.com/OpenSaasAU/stack/pull/867) [`43b4d17`](https://github.com/OpenSaasAU/stack/commit/43b4d1738340f05b1cf8bec3315927b3004816dd) Thanks [@borisno2](https://github.com/borisno2)! - Fix a better-auth plugin's schema extension of a base model (`user`/`session`/`account`/`verification`) silently dropping the derived Auth list's `db` (`map`/`schema`/`timestamps`) and `access` config.
+
 ## 0.36.0
 
 ## 0.35.0

package/CLAUDE.md

@@ -29,6 +29,7 @@ Auto-generated lists:
 ### Server (`src/server/index.ts`)
 
 - `createAuth(config, rawContext?)` - Creates Better-auth instance with MCP plugin support
+- `buildBetterAuthOptions(config, rawContext?)` - Returns the same `BetterAuthOptions` `createAuth()` builds, without constructing an instance — for apps that need to hand-wire their own `betterAuth()`
 - Returns `{ handler, signIn, signOut, ... }` - Better-auth methods
 
 ### Client (`src/client/index.ts`)
@@ -71,13 +72,16 @@ developer writes — not hardcoded. The pure derivation lives in
 `src/config/derive-auth-lists.ts` (`deriveAuthLists`), which `getAuthLists`
 and the plugin's add-vs-extend logic consume:
 
-- per-model `modelName` → list key + table `@@map`
+- per-model `modelName` → list key (and Prisma model name)
+- per-model `tableName` → table `@@map`, **independent of `modelName`**
+  (defaults to `modelName` when it differs from the better-auth default,
+  otherwise unset — i.e. unchanged output when `tableName` isn't set)
 - per-model `fields` (better-auth field → column) → field-level `@map`
 - the `userId` column override → the `user` relationship foreign-key `@map`
 - relationship refs between the Auth lists follow the derived keys
   (e.g. `Session.user → AuthUser.sessions`)
 
-With no `modelName`/`fields` overrides the output is unchanged
+With no `modelName`/`tableName`/`fields` overrides the output is unchanged
 (`User`/`Session`/`Account`/`Verification`, original field shapes, no `@@map`).
 
 ```typescript
@@ -89,6 +93,15 @@ authPlugin({
 // Adds AuthUser/AuthSession/... and leaves an app's own `User` untouched.
 ```
 
+```typescript
+// modelName sets the list key; tableName independently pins the live table —
+// e.g. a prefixed list key adopting better-auth's own default lowercase table.
+authPlugin({
+  user: { modelName: 'AuthUser', tableName: 'user' },
+  session: { modelName: 'AuthSession', tableName: 'session' },
+})
+```
+
 Because the plugin only ever adds/extends its **derived** keys, an app's own
 domain `User` (a different model from the better-auth user) is never extended
 or overwritten when the user model is renamed. The runtime `getUser`/
@@ -164,10 +177,10 @@ How it wires up (Postgres multi-schema):
 
 `adoptBetterAuthTables()` (`src/config/adopt-better-auth-tables.ts`) is a thin
 recipe that returns the `AuthConfig` adoption knobs — the plugin-level `schema`
-plus a per-model `modelName` (and optional column `fields` maps) — preset to the
-conventions of a standard separate-schema better-auth install. It ties together
-the keys/field derivation and schema placement so a migrator doesn't rebuild the
-config by hand. Spread it into `authPlugin`:
+plus a per-model `modelName` (and optional column `fields`/`tableName` maps) —
+preset to the conventions of a standard separate-schema better-auth install. It
+ties together the keys/field derivation and schema placement so a migrator
+doesn't rebuild the config by hand. Spread it into `authPlugin`:
 
 ```typescript
 import { authPlugin, adoptBetterAuthTables } from '@opensaas/stack-auth'
@@ -176,7 +189,23 @@ authPlugin({
   ...adoptBetterAuthTables(), // schema: 'auth', AuthUser/AuthSession/AuthAccount/AuthVerification
   emailAndPassword: { enabled: true },
 })
-// Options: adoptBetterAuthTables({ schema, modelNamePrefix, fields })
+// Options: adoptBetterAuthTables({ schema, modelNamePrefix, fields, useBetterAuthTableNames, tableNames })
+```
+
+The most common adoption shape is a project that ran better-auth **before**
+Stack, so its live tables are still better-auth's own default lowercase names
+(`user`/`session`/`account`/`verification`) even though the derived list keys
+need an `Auth` prefix to avoid colliding with the app's own domain `User`.
+`useBetterAuthTableNames: true` sets every model's `tableName` to that
+default; the per-model `tableNames` map is the escape hatch for a mix (it
+wins over `useBetterAuthTableNames` for any model it names):
+
+```typescript
+authPlugin({
+  ...adoptBetterAuthTables({ useBetterAuthTableNames: true }),
+  // → AuthUser/AuthSession/AuthAccount/AuthVerification list keys,
+  //   @@map("user")/@@map("session")/@@map("account")/@@map("verification")
+})
 ```
 
 It is pure config (no side effects): everything it sets can also be written
@@ -294,6 +323,74 @@ authPlugin({
 })
 ```
 
+### Escape hatch for unmodelled better-auth options (`betterAuthOptions`)
+
+`AuthConfig` models a deliberately closed set of better-auth options. For
+anything the stack doesn't model — database hooks, `session.cookieCache`,
+`baseURL`, `verification.storeIdentifier`, and so on — pass it through
+`betterAuthOptions`, typed as better-auth's own `BetterAuthOptions` so it
+tracks better-auth's surface without the stack re-declaring it:
+
+```typescript
+authPlugin({
+  betterAuthOptions: {
+    databaseHooks: { user: { create: { after: syncDomainUser } } },
+    session: { cookieCache: { enabled: true, maxAge: 300 } },
+    verification: { storeIdentifier: 'hashed' },
+    baseURL: process.env.BETTER_AUTH_URL,
+  },
+})
+```
+
+`createAuth()` (`src/server/index.ts`) deep-merges `betterAuthOptions` onto
+the options it builds from the rest of `AuthConfig`, applied **last**:
+plain-object values merge recursively per key (so `session: { cookieCache }`
+lands alongside the stack's own `session.expiresIn`/`updateAge` instead of
+replacing the whole `session` block), arrays and other value types replace
+outright, and `betterAuthOptions` wins on any genuine key collision. The
+merge and the option-building it merges onto both live in
+`buildBetterAuthOptions()`, the single place `createAuth()` and the exported
+builder share — they cannot drift from each other because `createAuth()`
+calls it directly rather than reimplementing it.
+
+`database` and `plugins` are rejected outright (`assertNoUnsupportedPassthroughKeys`
+in `src/server/index.ts`): they already have dedicated seams (`db` in the
+stack config, and `betterAuthPlugins` respectively), and accepting them here
+would create two unranked ways to set the same thing — worse for `plugins`,
+since the stack must append `nextCookies()` last (see "Auth forms submit
+through server actions" below). `additionalFields` under `user`/`session`/
+`account`/`verification` is rejected too — it adds columns with no
+corresponding change to the generated Prisma schema, which is exactly the
+silent-divergence failure mode this passthrough exists to avoid elsewhere.
+Add fields to the derived list instead: `extendUserList` for the user model,
+or declare the list yourself in your own `lists` config for the others (the
+auth plugin's `addList`-vs-`extendList` logic — see "Deriving Auth lists from
+better-auth config" above — merges in field additions for any list matching
+one of its derived keys).
+
+### Hand-wiring `betterAuth()` from the stack config (`buildBetterAuthOptions`)
+
+An app that needs a resolved `betterAuth()` instance at module-init time
+(rather than `createAuth()`'s lazy proxy) can derive its options from the
+stack config instead of duplicating them:
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { buildBetterAuthOptions } from '@opensaas/stack-auth/server'
+
+export const auth = betterAuth({
+  ...(await buildBetterAuthOptions(config, rawOpensaasContext)),
+  databaseHooks: { user: { create: { after: syncDomainUser } } }, // not yet in betterAuthOptions
+})
+```
+
+This is the same async-resolve-then-construct step `createAuth()` performs
+internally, exported standalone — see ADR-0014 and root `CLAUDE.md`'s
+"Getting the ORM client outside a request" for why `createAuth()` itself
+can't be synchronous. It gives an incremental path onto `createAuth()`: adopt
+the builder first, then fold options into `betterAuthOptions` above as the
+stack grows first-class config for them.
+
 ## Integration Points
 
 ### With @opensaas/stack-core

package/README.md

@@ -164,7 +164,15 @@ authPlugin({
   emailAndPassword: {
     enabled: true,
     minPasswordLength: 8,
-    requireConfirmation: true,
+    requireConfirmation: true, // UI-only — pass to <SignUpForm>/<ResetPasswordForm> directly
+    // Passed straight through to better-auth's own `emailAndPassword.sendResetPassword`
+    sendResetPassword: async ({ user, url }) => {
+      await yourEmailService.send({
+        to: user.email,
+        subject: 'Reset your password',
+        html: `<a href="${url}">Reset your password</a>`,
+      })
+    },
   },
 
   // Email verification
@@ -172,6 +180,14 @@ authPlugin({
     enabled: true,
     sendOnSignUp: true,
     tokenExpiration: 86400, // 24 hours in seconds
+    // Passed straight through to better-auth's own `emailVerification.sendVerificationEmail`
+    sendVerificationEmail: async ({ user, url }) => {
+      await yourEmailService.send({
+        to: user.email,
+        subject: 'Verify your email',
+        html: `<a href="${url}">Verify your email</a>`,
+      })
+    },
   },
 
   // Password reset
@@ -195,7 +211,7 @@ authPlugin({
   // Session configuration
   session: {
     expiresIn: 604800, // 7 days in seconds
-    updateAge: true, // Refresh session on each request
+    updateAge: 86400, // seconds between session refreshes; set `false` to disable
   },
 
   // Fields to include in session object
@@ -208,11 +224,6 @@ authPlugin({
       company: text(),
     },
   },
-
-  // Custom email sending function
-  sendEmail: async ({ to, subject, html }) => {
-    await yourEmailService.send({ to, subject, html })
-  },
 })
 ```
 

package/dist/config/adopt-better-auth-tables.d.ts

@@ -28,6 +28,22 @@
  * auth migration. The recipe never touches the application's own domain `User`:
  * its model names are `Auth`-prefixed by default and the plugin only ever
  * adds/extends its *derived* keys.
+ *
+ * The single most common adoption shape is a project that ran better-auth
+ * *before* adding Stack: its live tables are still better-auth's own default
+ * lowercase names (`user`/`session`/`account`/`verification`), even though the
+ * derived list keys need the `Auth` prefix to avoid colliding with the app's
+ * own domain `User`. Pass `useBetterAuthTableNames: true` to point every
+ * model's physical table at that default while keeping the prefixed list keys
+ * (or `tableNames` for an explicit per-model override):
+ *
+ * ```typescript
+ * authPlugin({
+ *   ...adoptBetterAuthTables({ useBetterAuthTableNames: true }),
+ *   // AuthUser/AuthSession/AuthAccount/AuthVerification list keys,
+ *   // @@map("user")/@@map("session")/@@map("account")/@@map("verification")
+ * })
+ * ```
  */
 import type { AuthConfig } from './types.js';
 /**
@@ -85,6 +101,37 @@ export type AdoptBetterAuthTablesOptions = {
         account?: Record<string, string>;
         verification?: Record<string, string>;
     };
+    /**
+     * Set every model's physical table name to better-auth's own default
+     * lowercase table name (`user`, `session`, `account`, `verification`) —
+     * independent of the prefixed list key/`modelName`.
+     *
+     * This is the single most common adoption shape: a project that ran
+     * better-auth before adding the stack has exactly these tables, and the
+     * default `modelNamePrefix: 'Auth'` alone would otherwise pin the table
+     * name to the prefixed model name (`AuthUser`, ...), which `prisma migrate
+     * diff` reads as a rename against the live `user` table.
+     *
+     * Ignored for a model with an explicit entry in {@link tableNames}.
+     *
+     * @default false
+     */
+    useBetterAuthTableNames?: boolean;
+    /**
+     * Per-model explicit table name overrides, keyed by model. Takes
+     * precedence over `useBetterAuthTableNames` for that model.
+     *
+     * @example
+     * ```typescript
+     * adoptBetterAuthTables({ tableNames: { user: 'users' } })
+     * ```
+     */
+    tableNames?: {
+        user?: string;
+        session?: string;
+        account?: string;
+        verification?: string;
+    };
 };
 /**
  * The adoption-relevant slice of {@link AuthConfig}: the plugin-level `schema`

package/dist/config/adopt-better-auth-tables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adopt-better-auth-tables.d.ts","sourceRoot":"","sources":["../../src/config/adopt-better-auth-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAA;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KACtC,CAAA;CACF,CAAA;AAUD;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,UAAU,EACV,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,CAC3D,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,2BAA2B,CAqB7B"}
+{"version":3,"file":"adopt-better-auth-tables.d.ts","sourceRoot":"","sources":["../../src/config/adopt-better-auth-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAA;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KACtC,CAAA;IAED;;;;;;;;;;;;;;OAcG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAA;IAEjC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF,CAAA;AAkBD;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,UAAU,EACV,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,CAC3D,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,2BAA2B,CAiC7B"}

package/dist/config/adopt-better-auth-tables.js

@@ -28,6 +28,22 @@
  * auth migration. The recipe never touches the application's own domain `User`:
  * its model names are `Auth`-prefixed by default and the plugin only ever
  * adds/extends its *derived* keys.
+ *
+ * The single most common adoption shape is a project that ran better-auth
+ * *before* adding Stack: its live tables are still better-auth's own default
+ * lowercase names (`user`/`session`/`account`/`verification`), even though the
+ * derived list keys need the `Auth` prefix to avoid colliding with the app's
+ * own domain `User`. Pass `useBetterAuthTableNames: true` to point every
+ * model's physical table at that default while keeping the prefixed list keys
+ * (or `tableNames` for an explicit per-model override):
+ *
+ * ```typescript
+ * authPlugin({
+ *   ...adoptBetterAuthTables({ useBetterAuthTableNames: true }),
+ *   // AuthUser/AuthSession/AuthAccount/AuthVerification list keys,
+ *   // @@map("user")/@@map("session")/@@map("account")/@@map("verification")
+ * })
+ * ```
  */
 /** The four better-auth models and their default (unprefixed) model names. */
 const MODEL_DEFAULT_NAMES = {
@@ -36,6 +52,13 @@ const MODEL_DEFAULT_NAMES = {
     account: 'Account',
     verification: 'Verification',
 };
+/** better-auth's own default lowercase table names, per model. */
+const BETTER_AUTH_DEFAULT_TABLE_NAMES = {
+    user: 'user',
+    session: 'session',
+    account: 'account',
+    verification: 'verification',
+};
 /**
  * Build the adoption {@link AuthConfig} fragment for a pre-existing better-auth
  * installation.
@@ -48,11 +71,16 @@ const MODEL_DEFAULT_NAMES = {
  *   (and any field column maps) set to match the live tables
  */
 export function adoptBetterAuthTables(options = {}) {
-    const { schema = 'auth', modelNamePrefix = 'Auth', fields = {} } = options;
+    const { schema = 'auth', modelNamePrefix = 'Auth', fields = {}, useBetterAuthTableNames = false, tableNames = {}, } = options;
     const buildModel = (model) => {
         const config = {
             modelName: `${modelNamePrefix}${MODEL_DEFAULT_NAMES[model]}`,
         };
+        const tableName = tableNames[model] ??
+            (useBetterAuthTableNames ? BETTER_AUTH_DEFAULT_TABLE_NAMES[model] : undefined);
+        if (tableName !== undefined) {
+            config.tableName = tableName;
+        }
         const fieldMap = fields[model];
         if (fieldMap && Object.keys(fieldMap).length > 0) {
             config.fields = fieldMap;

package/dist/config/adopt-better-auth-tables.js.map

@@ -1 +1 @@
-{"version":3,"file":"adopt-better-auth-tables.js","sourceRoot":"","sources":["../../src/config/adopt-better-auth-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA+DH,8EAA8E;AAC9E,MAAM,mBAAmB,GAAG;IAC1B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;CACpB,CAAA;AAYV;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAO,GAAiC,EAAE;IAE1C,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,eAAe,GAAG,MAAM,EAAE,MAAM,GAAG,EAAE,EAAE,GAAG,OAAO,CAAA;IAE1E,MAAM,UAAU,GAAG,CAAC,KAAuC,EAAmB,EAAE;QAC9E,MAAM,MAAM,GAAoB;YAC9B,SAAS,EAAE,GAAG,eAAe,GAAG,mBAAmB,CAAC,KAAK,CAAC,EAAE;SAC7D,CAAA;QACD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAC9B,IAAI,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjD,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAA;QAC1B,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,OAAO;QACL,MAAM;QACN,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC;QACxB,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC;QAC9B,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC;QAC9B,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC;KACzC,CAAA;AACH,CAAC"}
+{"version":3,"file":"adopt-better-auth-tables.js","sourceRoot":"","sources":["../../src/config/adopt-better-auth-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAgGH,8EAA8E;AAC9E,MAAM,mBAAmB,GAAG;IAC1B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;CACpB,CAAA;AAEV,kEAAkE;AAClE,MAAM,+BAA+B,GAAG;IACtC,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;CACpB,CAAA;AAYV;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAO,GAAiC,EAAE;IAE1C,MAAM,EACJ,MAAM,GAAG,MAAM,EACf,eAAe,GAAG,MAAM,EACxB,MAAM,GAAG,EAAE,EACX,uBAAuB,GAAG,KAAK,EAC/B,UAAU,GAAG,EAAE,GAChB,GAAG,OAAO,CAAA;IAEX,MAAM,UAAU,GAAG,CAAC,KAAuC,EAAmB,EAAE;QAC9E,MAAM,MAAM,GAAoB;YAC9B,SAAS,EAAE,GAAG,eAAe,GAAG,mBAAmB,CAAC,KAAK,CAAC,EAAE;SAC7D,CAAA;QACD,MAAM,SAAS,GACb,UAAU,CAAC,KAAK,CAAC;YACjB,CAAC,uBAAuB,CAAC,CAAC,CAAC,+BAA+B,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAChF,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,CAAC,SAAS,GAAG,SAAS,CAAA;QAC9B,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAC9B,IAAI,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjD,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAA;QAC1B,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,OAAO;QACL,MAAM;QACN,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC;QACxB,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC;QAC9B,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC;QAC9B,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC;KACzC,CAAA;AACH,CAAC"}

package/dist/config/derive-auth-lists.d.ts

@@ -2,13 +2,15 @@
  * 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:
+ * concerns: given the resolved better-auth model config (per-model `modelName`,
+ * `tableName`, 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
+ *  - a table `@@map` (list-level `db.map`) taken from each model's resolved
+ *    `tableName` — independent of `modelName`, so a renamed list key can still
+ *    adopt a differently-named live table
  *  - 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`)

package/dist/config/derive-auth-lists.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-auth-lists.d.ts","sourceRoot":"","sources":["../../src/config/derive-auth-lists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAA6B,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAanG;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oDAAoD;IACpD,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,kEAAkE;IAElE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;CACvC,CAAA;AAyMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,oBAAoB,EAC5B,UAAU,GAAE,oBAAyB,EACrC,YAAY,GAAE,gBAAqB,GAClC,gBAAgB,CAiBlB"}
+{"version":3,"file":"derive-auth-lists.d.ts","sourceRoot":"","sources":["../../src/config/derive-auth-lists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAA6B,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEnG;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oDAAoD;IACpD,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,kEAAkE;IAElE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;CACvC,CAAA;AAiND;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,oBAAoB,EAC5B,UAAU,GAAE,oBAAyB,EACrC,YAAY,GAAE,gBAAqB,GAClC,gBAAgB,CAiBlB"}

package/dist/config/derive-auth-lists.js

@@ -2,13 +2,15 @@
  * 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:
+ * concerns: given the resolved better-auth model config (per-model `modelName`,
+ * `tableName`, 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
+ *  - a table `@@map` (list-level `db.map`) taken from each model's resolved
+ *    `tableName` — independent of `modelName`, so a renamed list key can still
+ *    adopt a differently-named live table
  *  - 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`)
@@ -25,16 +27,6 @@
  */
 import { list } from '@opensaas/stack-core';
 import { text, timestamp, checkbox, relationship } from '@opensaas/stack-core/fields';
-/**
- * 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',
-};
 /**
  * Build the list-level `db` config (`timestamps` + `@@map` + `@@schema`) for a
  * derived list.
@@ -46,21 +38,20 @@ const DEFAULT_MODEL_NAMES = {
  * 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(...)`.
+ * The physical table name (`@@map`) comes from the model's resolved
+ * `tableName` — independent of the list key/`modelName` — so a renamed list
+ * key can still adopt a differently-named live table (e.g. better-auth's own
+ * default lowercase table names). 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`,
+ * With no `tableName`/`schema` overrides we emit only `timestamps: true`,
  * leaving the default `User`/`Session`/... table/schema output unchanged.
  */
-function listDb(model, defaultModelName) {
-    const map = model.modelName !== defaultModelName ? model.modelName : undefined;
+function listDb(model) {
     const schema = model.schema;
     return {
         timestamps: true,
-        ...(map !== undefined ? { map } : {}),
+        ...(model.tableName !== undefined ? { map: model.tableName } : {}),
         ...(schema !== undefined ? { schema } : {}),
     };
 }
@@ -80,14 +71,18 @@ function fieldDb(fieldName, fields) {
  * 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).
+ * — the index is applied at the field level via `isIndexed: false` —
+ * `onDelete: Cascade`, and a required (non-nullable) foreign key, since
+ * better-auth's adapter always writes a `userId` on every session/account row
+ * it creates. This means a generated Auth schema diffs clean against a live
+ * better-auth database on all three dimensions instead of showing a spurious
+ * index drop, a referential-action change, and a `DROP NOT NULL` (issues #679,
+ * #863).
  */
 function userRelationshipDb(fields) {
     const column = fields.userId;
     return {
+        isNullable: false,
         ...(column ? { foreignKey: { map: column } } : {}),
         extendPrismaSchema: ({ fkLine, relationLine }) => ({
             fkLine,
@@ -122,7 +117,7 @@ function createUserList(model, keys, userConfig, access) {
             // Custom fields from user config
             ...(userConfig.fields || {}),
         },
-        db: listDb(model, DEFAULT_MODEL_NAMES.user),
+        db: listDb(model),
         access: userConfig.access || access,
         hooks: userConfig.hooks,
     });
@@ -142,7 +137,9 @@ function createSessionList(model, keys, access) {
                 isIndexed: 'unique',
                 db: fieldDb('token', f),
             }),
-            expiresAt: timestamp({ db: fieldDb('expiresAt', f) }),
+            expiresAt: timestamp({
+                db: { isNullable: false, ...fieldDb('expiresAt', f) },
+            }),
             ipAddress: text({ db: fieldDb('ipAddress', f) }),
             userAgent: text({ db: fieldDb('userAgent', f) }),
             user: relationship({
@@ -151,7 +148,7 @@ function createSessionList(model, keys, access) {
                 db: userRelationshipDb(f),
             }),
         },
-        db: listDb(model, DEFAULT_MODEL_NAMES.session),
+        db: listDb(model),
         access,
     });
 }
@@ -180,7 +177,7 @@ function createAccountList(model, keys, access) {
             idToken: text({ db: fieldDb('idToken', f) }),
             password: text({ db: fieldDb('password', f) }),
         },
-        db: listDb(model, DEFAULT_MODEL_NAMES.account),
+        db: listDb(model),
         access,
     });
 }
@@ -196,9 +193,11 @@ function createVerificationList(model, access) {
         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) }),
+            expiresAt: timestamp({
+                db: { isNullable: false, ...fieldDb('expiresAt', f) },
+            }),
         },
-        db: listDb(model, DEFAULT_MODEL_NAMES.verification),
+        db: listDb(model),
         access,
     });
 }