@opensaas/stack-auth 0.36.0 → 0.38.0

package/dist/config/types.d.ts

@@ -1,5 +1,17 @@
 import type { ListConfig } from '@opensaas/stack-core';
+import type { BetterAuthOptions, BetterAuthPlugin, User } from 'better-auth';
 import type { ExtendUserListConfig } from '../lists/index.js';
+/**
+ * better-auth's own callback shape for `sendVerificationEmail`/
+ * `sendResetPassword` — `data` is exactly what better-auth passes (no stack
+ * abstraction layered on top), and `request` is the raw request that
+ * triggered it.
+ */
+export type SendAuthEmail = (data: {
+    user: User;
+    url: string;
+    token: string;
+}, request?: Request) => Promise<void>;
 /**
  * OAuth provider configuration
  */
@@ -29,10 +41,36 @@ export type EmailPasswordConfig = {
      */
     minPasswordLength?: number;
     /**
-     * Require password confirmation
+     * Require password confirmation (a second "confirm password" field).
+     *
+     * There is no better-auth server-side equivalent — this is purely a UI
+     * concern. `createAuth()` does not read it. Pass it directly to the
+     * pre-built forms instead: `<SignUpForm requirePasswordConfirmation={...} />`
+     * / `<ResetPasswordForm requirePasswordConfirmation={...} />` (both default
+     * to `true`). Setting it here has no effect and `createAuth()` warns if it
+     * is configured.
+     *
      * @default true
      */
     requireConfirmation?: boolean;
+    /**
+     * Send a password reset email. Passed straight through to better-auth's own
+     * `emailAndPassword.sendResetPassword` — the stack does not wrap or
+     * reshape it. If not provided, reset emails are logged to console instead
+     * of sent.
+     *
+     * @example
+     * ```typescript
+     * sendResetPassword: async ({ user, url }) => {
+     *   await resend.emails.send({
+     *     to: user.email,
+     *     subject: 'Reset your password',
+     *     html: `<a href="${url}">Reset your password</a>`,
+     *   })
+     * }
+     * ```
+     */
+    sendResetPassword?: SendAuthEmail;
 };
 /**
  * Email verification configuration
@@ -49,6 +87,24 @@ export type EmailVerificationConfig = {
      * @default 86400 (24 hours)
      */
     tokenExpiration?: number;
+    /**
+     * Send a verification email. Passed straight through to better-auth's own
+     * `emailVerification.sendVerificationEmail` — the stack does not wrap or
+     * reshape it. If not provided, verification emails are logged to console
+     * instead of sent.
+     *
+     * @example
+     * ```typescript
+     * sendVerificationEmail: async ({ user, url }) => {
+     *   await resend.emails.send({
+     *     to: user.email,
+     *     subject: 'Verify your email',
+     *     html: `<a href="${url}">Verify your email</a>`,
+     *   })
+     * }
+     * ```
+     */
+    sendVerificationEmail?: SendAuthEmail;
 };
 /**
  * Password reset configuration
@@ -71,10 +127,12 @@ export type SessionConfig = {
      */
     expiresIn?: number;
     /**
-     * Update session expiration on each request
-     * @default true
+     * How often the session should be refreshed, in seconds. Passed straight
+     * through to better-auth's own `session.updateAge`. Set `false` to disable
+     * refresh entirely (the session expiry is then fixed at creation time).
+     * @default 86400 (1 day, matching better-auth's own default)
      */
-    updateAge?: boolean;
+    updateAge?: number | false;
 };
 /**
  * Per-model better-auth configuration block.
@@ -138,10 +196,30 @@ export type AuthAccessConfig = {
 export type AuthModelConfig = {
     /**
      * The table/list name for this model.
-     * Becomes the OpenSaaS list key (and Prisma model name) and the table `@@map`.
+     * Becomes the OpenSaaS list key and Prisma model name.
      * @default the default better-auth model name (e.g. 'User', 'Session')
      */
     modelName?: string;
+    /**
+     * The physical database table name for this model, independent of
+     * `modelName`. Generates a `@@map("...")` on the derived list.
+     *
+     * Lets a renamed list key (e.g. `modelName: 'AuthUser'`, to avoid colliding
+     * with an app's own domain `User`) still adopt a live table under a
+     * different name — most commonly better-auth's own default lowercase
+     * table names (`user`, `session`, `account`, `verification`).
+     *
+     * @default `modelName` when it differs from the better-auth default model
+     *   name, otherwise unset (no `@@map`) — i.e. today's behaviour when this
+     *   option is not set.
+     *
+     * @example
+     * ```typescript
+     * // List key AuthUser, but the live table is still called `user`.
+     * user: { modelName: 'AuthUser', tableName: 'user' }
+     * ```
+     */
+    tableName?: string;
     /**
      * Map better-auth field names to database column names.
      * Each entry generates a `@map("column")` on the derived field.
@@ -243,8 +321,21 @@ export type AuthConfig = {
      */
     schema?: string;
     /**
-     * Which fields to include in the session object
-     * This determines what data is available in access control functions
+     * Which fields to include in the session object passed to access control
+     * functions — a **flattened projection** of the resolved better-auth
+     * session, not the session's own shape. `getSessionFromAuth` (the
+     * implementation the scaffolded `getSession()` calls) resolves each name
+     * against a fixed precedence: a top-level key on the resolved session
+     * object, then the `user` object, then the `session` sub-object.
+     * `userId` is special-cased to the authenticated user's `id`.
+     *
+     * A `customSession` better-auth plugin fully replaces the resolved shape
+     * (it can nest fields anywhere, e.g. under its own custom key) —
+     * reconciling that shape against `sessionFields` is the application's job.
+     * A listed name that can't be resolved is omitted and warns once per
+     * field per process, naming what was checked, rather than silently
+     * becoming `undefined` in an access control function.
+     *
      * @default ['userId', 'email', 'name']
      *
      * @example
@@ -284,22 +375,6 @@ export type AuthConfig = {
      * narrower, User-specific override.
      */
     access?: AuthAccessConfig;
-    /**
-     * Custom email sending function for verification and password reset
-     * If not provided, emails will be logged to console
-     *
-     * @example
-     * ```typescript
-     * sendEmail: async ({ to, subject, html }) => {
-     *   await resend.emails.send({ to, subject, html })
-     * }
-     * ```
-     */
-    sendEmail?: (params: {
-        to: string;
-        subject: string;
-        html: string;
-    }) => Promise<void>;
     /**
      * Additional Better Auth plugins to enable
      * Allows integrating any Better Auth plugin (MCP, 2FA, etc.)
@@ -313,7 +388,7 @@ export type AuthConfig = {
      * ]
      * ```
      */
-    betterAuthPlugins?: any[];
+    betterAuthPlugins?: BetterAuthPlugin[];
     /**
      * Rate limiting configuration
      * Controls rate limiting for authentication endpoints
@@ -346,16 +421,56 @@ export type AuthConfig = {
          */
         max?: number;
     };
+    /**
+     * Escape hatch for better-auth options the stack doesn't model — typed as
+     * better-auth's own `BetterAuthOptions` so it stays in step with
+     * better-auth's surface without the stack re-declaring it. Deep-merged into
+     * the options `createAuth()` builds, applied LAST: a plain-object value at a
+     * given key merges recursively with whatever the stack already set there
+     * (so e.g. `session: { cookieCache: {...} }` adds alongside the stack's own
+     * `session.expiresIn`/`updateAge` rather than clobbering them); any other
+     * value (including arrays) replaces the stack's value outright. On a genuine
+     * key collision, this option wins.
+     *
+     * `database` and `plugins` are rejected — they're already the dedicated
+     * seams (the stack's `db` config, and `betterAuthPlugins` respectively) and
+     * accepting them here would create two unranked ways to set the same thing.
+     * So is `additionalFields` under `user`/`session`/`account`/`verification` —
+     * it has schema consequences (new columns) that a passthrough can't also
+     * apply to the generated Prisma schema; add fields to the derived list
+     * instead (`extendUserList` for the user model, or declare the list
+     * yourself for the others — see `packages/auth/CLAUDE.md`).
+     *
+     * The same options object is available standalone via
+     * `buildBetterAuthOptions()` (`@opensaas/stack-auth/server`) for apps that
+     * still need to hand-wire their own `betterAuth()` instance.
+     *
+     * @example
+     * ```typescript
+     * authPlugin({
+     *   betterAuthOptions: {
+     *     databaseHooks: { user: { create: { after: syncDomainUser } } },
+     *     session: { cookieCache: { enabled: true, maxAge: 300 } },
+     *     verification: { storeIdentifier: 'hashed' },
+     *     baseURL: process.env.BETTER_AUTH_URL,
+     *   },
+     * })
+     * ```
+     */
+    betterAuthOptions?: Partial<BetterAuthOptions>;
 };
 /**
  * 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).
+ * better-auth default) and a (possibly empty) `fields` column map. `tableName`
+ * is the resolved physical table name — `undefined` means no `@@map` is
+ * emitted (the list key doubles as the table name). `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;
+    tableName?: string;
     fields: Record<string, string>;
     schema?: string;
 };
@@ -387,7 +502,7 @@ export type NormalizedAuthConfig = Required<Omit<AuthConfig, 'emailAndPassword'
      * default (used to wire the datasource `schemas` array during generation).
      */
     schema?: string;
-    betterAuthPlugins: any[];
+    betterAuthPlugins: BetterAuthPlugin[];
     rateLimit?: {
         enabled: boolean;
         window?: number;

package/dist/config/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAChD,OAAO,CAAC,EAAE,OAAO,KACd,OAAO,CAAC,IAAI,CAAC,CAAA;AAElB;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAA;CACzC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,aAAa,CAAA;CAClC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,EAAE,aAAa,CAAA;CACtC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CAC3B,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAE7B,IAAI,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;IAEhC,OAAO,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;IAEnC,OAAO,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;IAEnC,YAAY,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;CACzC,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;OAEG;IACH,gBAAgB,CAAC,EAAE,mBAAmB,GAAG;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,CAAA;IAE1D;;OAEG;IACH,iBAAiB,CAAC,EAAE,uBAAuB,GAAG;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,CAAA;IAE/D;;OAEG;IACH,aAAa,CAAC,EAAE,mBAAmB,GAAG;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,CAAA;IAEvD;;OAEG;IACH,eAAe,CAAC,EAAE,qBAAqB,CAAA;IAEvC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,aAAa,GAAG,eAAe,CAAA;IAEzC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,eAAe,CAAA;IAEtB;;OAEG;IACH,OAAO,CAAC,EAAE,eAAe,CAAA;IAEzB;;OAEG;IACH,YAAY,CAAC,EAAE,eAAe,CAAA;IAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IAExB;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAA;IAErC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAA;IAEzB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAEtC;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,EAAE;QACV,OAAO,EAAE,OAAO,CAAA;QAChB;;;WAGG;QACH,MAAM,CAAC,EAAE,MAAM,CAAA;QACf;;;WAGG;QACH,GAAG,CAAC,EAAE,MAAM,CAAA;KACb,CAAA;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;CAC/C,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,yBAAyB,CAAA;IAC/B,OAAO,EAAE,yBAAyB,CAAA;IAClC,OAAO,EAAE,yBAAyB,CAAA;IAClC,YAAY,EAAE,yBAAyB,CAAA;CACxC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CACzC,IAAI,CACF,UAAU,EACR,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,GACf,mBAAmB,GACnB,WAAW,GACX,SAAS,GACT,MAAM,GACN,SAAS,GACT,cAAc,GACd,QAAQ,CACX,CACF,GAAG;IACF,gBAAgB,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAA;IAC/C,iBAAiB,EAAE,QAAQ,CAAC,uBAAuB,CAAC,CAAA;IACpD,aAAa,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAA;IAC5C,oFAAoF;IACpF,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAA;IAChC,sGAAsG;IACtG,MAAM,EAAE,oBAAoB,CAAA;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iBAAiB,EAAE,gBAAgB,EAAE,CAAA;IACrC,SAAS,CAAC,EAAE;QACV,OAAO,EAAE,OAAO,CAAA;QAChB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,GAAG,CAAC,EAAE,MAAM,CAAA;KACb,CAAA;CACF,CAAA"}

package/dist/server/build-better-auth-options.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=build-better-auth-options.test.d.ts.map

package/dist/server/build-better-auth-options.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-better-auth-options.test.d.ts","sourceRoot":"","sources":["../../src/server/build-better-auth-options.test.ts"],"names":[],"mappings":""}

package/dist/server/build-better-auth-options.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import { buildBetterAuthOptions } from './index.js';
+// `ReturnType<typeof buildBetterAuthOptions>` on the overloaded export itself
+// resolves against its last (generic) signature, not the call-site-selected
+// one — wrapping each call shape in its own ordinary function and reading
+// `ReturnType<typeof wrapper>` instead forces TS to resolve overloads exactly
+// as a real call site would.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced only via `typeof` below
+function callWithNoPlugins(config, context) {
+    return buildBetterAuthOptions(config, context);
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced only via `typeof` below
+function callWithPlugins(config, context, plugins) {
+    return buildBetterAuthOptions(config, context, plugins);
+}
+describe('buildBetterAuthOptions plugin-tuple typing', () => {
+    it('back-compat: the no-argument call still returns the widened BetterAuthOptions', () => {
+        expectTypeOf().toEqualTypeOf();
+    });
+    it('preserves plugin-derived auth.api.* endpoints and a customSession shape', () => {
+        // emailOTP() endpoints exist on the constructed Auth's `api` — erased entirely
+        // when constructed from the widened `BetterAuthOptions` (see #876).
+        expectTypeOf().not.toBeNever();
+        expectTypeOf().not.toBeNever();
+        expectTypeOf().not.toBeNever();
+        expectTypeOf().toEqualTypeOf();
+    });
+});
+//# sourceMappingURL=build-better-auth-options.test.js.map

package/dist/server/build-better-auth-options.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-better-auth-options.test.js","sourceRoot":"","sources":["../../src/server/build-better-auth-options.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAKnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAWnD,8EAA8E;AAC9E,4EAA4E;AAC5E,0EAA0E;AAC1E,8EAA8E;AAC9E,6BAA6B;AAC7B,mGAAmG;AACnG,SAAS,iBAAiB,CACxB,MAAgD,EAChD,OAA+C;IAE/C,OAAO,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAChD,CAAC;AAED,mGAAmG;AACnG,SAAS,eAAe,CACtB,MAAgD,EAChD,OAA+C,EAC/C,OAAoB;IAEpB,OAAO,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AACzD,CAAC;AAMD,QAAQ,CAAC,4CAA4C,EAAE,GAAG,EAAE;IAC1D,EAAE,CAAC,+EAA+E,EAAE,GAAG,EAAE;QACvF,YAAY,EAAe,CAAC,aAAa,EAAqB,CAAA;IAChE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,yEAAyE,EAAE,GAAG,EAAE;QACjF,+EAA+E;QAC/E,oEAAoE;QACpE,YAAY,EAA4C,CAAC,GAAG,CAAC,SAAS,EAAE,CAAA;QACxE,YAAY,EAAiD,CAAC,GAAG,CAAC,SAAS,EAAE,CAAA;QAC7E,YAAY,EAAkD,CAAC,GAAG,CAAC,SAAS,EAAE,CAAA;QAI9E,YAAY,EAAoB,CAAC,aAAa,EAAqB,CAAA;IACrE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/server/index.d.ts

@@ -1,25 +1,129 @@
 import { betterAuth } from 'better-auth';
-import type { BetterAuthOptions } from 'better-auth';
-import type { OpenSaasConfig, AccessContext } from '@opensaas/stack-core';
+import { nextCookies } from 'better-auth/next-js';
+import type { Auth, BetterAuthOptions, BetterAuthPlugin } from 'better-auth';
+import type { OpenSaasConfig, AccessContext, Session } from '@opensaas/stack-core';
+/**
+ * The `BetterAuthOptions` shape produced when an app's own plugin tuple is
+ * passed to `buildBetterAuthOptions()`/`createAuth()` — the tuple plus the
+ * `nextCookies()` plugin the stack always appends last. Carrying the literal
+ * tuple type (rather than the widened `BetterAuthPlugin[]`) is what lets
+ * `betterAuth()` re-infer plugin endpoints (e.g. `emailOTP()`'s
+ * `api.signInEmailOTP`) and a `customSession()` plugin's replaced session
+ * shape from the resulting options object.
+ */
+type ResolvedBetterAuthOptions<TPlugins extends readonly BetterAuthPlugin[]> = Omit<BetterAuthOptions, 'plugins'> & {
+    plugins: [...TPlugins, ReturnType<typeof nextCookies>];
+};
+/**
+ * Build the `BetterAuthOptions` a better-auth instance for this OpenSaas
+ * config should be constructed with — the same options `createAuth()` uses
+ * internally, available standalone for an app that still needs to hand-wire
+ * its own `betterAuth()` instance (e.g. a third-party contract that requires
+ * a resolved instance at module-init time). Keeps the auth plugin
+ * authoritative for everything it models; the app's additions on top become
+ * an explicit, reviewable diff instead of a parallel, hand-duplicated config.
+ *
+ * Called with just `(config, context)`, the return type is the widened
+ * `BetterAuthOptions` — `betterAuth()` infers its plugin/session types from
+ * the *literal* type of the options object, so constructing from this
+ * widened return erases plugin endpoints (e.g. `emailOTP()`'s
+ * `api.signInEmailOTP`) and a `customSession()` plugin's replaced session
+ * shape. **If your app reads `auth.api.*` in typed code and uses either of
+ * those, pass its plugin tuple as the third argument** — the exact same
+ * array already passed to `authPlugin({ betterAuthPlugins })` — so the
+ * return type carries the literal tuple instead:
+ *
+ * ```typescript
+ * import { betterAuth } from 'better-auth'
+ * import { emailOTP } from 'better-auth/plugins'
+ * import { buildBetterAuthOptions } from '@opensaas/stack-auth/server'
+ *
+ * export const appBetterAuthPlugins = [emailOTP()] // same array passed to authPlugin({ betterAuthPlugins })
+ *
+ * export const auth = betterAuth({
+ *   ...(await buildBetterAuthOptions(config, context, appBetterAuthPlugins)),
+ *   databaseHooks: { user: { create: { after: syncDomainUser } } },
+ * })
+ * // auth.api.signInEmailOTP / auth.api.getSession()'s customSession shape are now typed.
+ * ```
+ *
+ * The supplied tuple is for typing only — the array actually used at runtime
+ * is always the one resolved from `authPlugin({ betterAuthPlugins })`, with
+ * exactly one `nextCookies()` appended last. Passing a tuple that isn't the
+ * same plugin instances in the same order throws, so the two can't silently
+ * drift apart.
+ *
+ * Note `createAuth()`'s lazy Proxy does not behave identically to a real
+ * `Auth` instance for every property (see its own doc comment) — reach for
+ * this builder plus `betterAuth()` instead when the app reads `auth.api.*`
+ * in typed code.
+ */
+export declare function buildBetterAuthOptions(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>): Promise<BetterAuthOptions>;
+export declare function buildBetterAuthOptions<const TPlugins extends readonly BetterAuthPlugin[]>(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>, plugins: TPlugins): Promise<ResolvedBetterAuthOptions<TPlugins>>;
 /**
  * Create a better-auth instance from OpenSaas config
  * This should be called once at app startup
  *
- * @example
+ * Returns a lazy `Proxy` (see the caveat below), typed as `Auth<BetterAuthOptions>`
+ * when called with just `(config, context)` — the widened type, same erasure
+ * caveat as {@link buildBetterAuthOptions}'s no-argument form. **If your app
+ * reads `auth.api.*` in typed code and relies on a plugin's endpoints (e.g.
+ * `emailOTP()`) or a `customSession()`'s replaced session shape, pass its
+ * plugin tuple as the third argument** — the exact same array already passed
+ * to `authPlugin({ betterAuthPlugins })` — so the declared type carries the
+ * literal tuple instead:
+ *
  * ```typescript
  * // lib/auth.ts
  * import { createAuth } from '@opensaas/stack-auth/server'
  * import config from '../opensaas.config'
  * import { rawOpensaasContext } from '@/.opensaas/context'
  *
- * export const auth = createAuth(config, rawOpensaasContext)
+ * export const appBetterAuthPlugins = [emailOTP()] // same array passed to authPlugin({ betterAuthPlugins })
+ *
+ * export const auth = createAuth(config, rawOpensaasContext, appBetterAuthPlugins)
  * ```
+ *
+ * As with the builder, the supplied tuple is for typing only, and a tuple
+ * that isn't the same plugin instances in the same order throws.
+ *
+ * **Proxy caveat:** the lazy `Proxy` this returns does not behave identically
+ * to a real `Auth` instance for every property — every access, including a
+ * non-function property, is surfaced through an `async` wrapper (so e.g.
+ * `auth.options` reads back as a `Promise`, not the plain object a real
+ * instance would return synchronously). The declared type does not model
+ * this difference; where it matters, reach for {@link buildBetterAuthOptions}
+ * plus `betterAuth()` instead, which constructs a real instance.
  */
-export declare function createAuth(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>): import("better-auth").Auth<BetterAuthOptions>;
+export declare function createAuth(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>): Auth<BetterAuthOptions>;
+export declare function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>, plugins: TPlugins): Auth<ResolvedBetterAuthOptions<TPlugins>>;
 /**
- * Get session from better-auth and transform it to OpenSaas session format
- * This is used internally by the generated context
+ * Get session from better-auth and transform it to OpenSaas session format —
+ * a flattened projection of `sessionFields` off the *resolved* session
+ * object, not just its `user` sub-object. This is what makes a
+ * `customSession` plugin's fields (added at the top level, or a
+ * session-only field like the admin plugin's `impersonatedBy`) reachable.
+ * See the `sessionFields` reference for the resolution precedence.
+ *
+ * Returns `null` only when there is genuinely no session — a resolved
+ * session with no `user` key (a `customSession` plugin that dropped it) is
+ * still a session and still gets projected, never misreported as anonymous.
+ * A listed field that can't be resolved from the session shape is omitted
+ * and warns once per field per process (see `warnUnresolvedSessionField`)
+ * instead of silently vanishing into an access-control function reading
+ * `undefined`.
+ *
+ * Errors from the underlying `auth.api.getSession()` call propagate rather
+ * than becoming `null` — collapsing a lookup failure (e.g. a session-store
+ * outage) into "anonymous" is indistinguishable from a mass sign-out under
+ * fail-closed access control, so the caller must see it.
+ *
+ * Not called by any generated code before this helper existed — apps used to
+ * hand-roll this same transform against `auth.api.getSession({ headers:
+ * await headers() })`. Exported as the single reusable implementation; pass
+ * the caller's request headers (e.g. Next.js `await headers()` in a Server
+ * Component/action) so a session cookie can actually be resolved.
  */
-export declare function getSessionFromAuth(auth: ReturnType<typeof betterAuth>, sessionFields: string[]): Promise<Record<string, unknown> | null>;
+export declare function getSessionFromAuth(auth: ReturnType<typeof betterAuth>, sessionFields: string[], headers: Headers): Promise<Session | null>;
 export type { BetterAuthOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAgCzE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,iDA8IhD;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,EACnC,aAAa,EAAE,MAAM,EAAE,2CA0BxB;AAED,YAAY,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAIlF;;;;;;;;GAQG;AACH,KAAK,yBAAyB,CAAC,QAAQ,SAAS,SAAS,gBAAgB,EAAE,IAAI,IAAI,CACjF,iBAAiB,EACjB,SAAS,CACV,GAAG;IACF,OAAO,EAAE,CAAC,GAAG,QAAQ,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAA;CACvD,CAAA;AA+ID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,sBAAsB,CAC1C,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAC9C,OAAO,CAAC,iBAAiB,CAAC,CAAA;AAC7B,wBAAsB,sBAAsB,CAAC,KAAK,CAAC,QAAQ,SAAS,SAAS,gBAAgB,EAAE,EAC7F,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,EAC/C,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,yBAAyB,CAAC,QAAQ,CAAC,CAAC,CAAA;AA2I/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,UAAU,CACxB,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAC9C,IAAI,CAAC,iBAAiB,CAAC,CAAA;AAC1B,wBAAgB,UAAU,CAAC,KAAK,CAAC,QAAQ,SAAS,SAAS,gBAAgB,EAAE,EAC3E,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,EAC/C,OAAO,EAAE,QAAQ,GAChB,IAAI,CAAC,yBAAyB,CAAC,QAAQ,CAAC,CAAC,CAAA;AA8I5C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,EACnC,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAoBzB;AAED,YAAY,EAAE,iBAAiB,EAAE,CAAA"}