@mastra/auth-better-auth 1.1.2-alpha.1 → 1.1.2-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @mastra/auth-better-auth
 
+## 1.1.2-alpha.2
+
+### Patch Changes
+
+- Added a deferred instance mode and organization management to MastraAuthBetterAuth so it can be passed directly to a server host without a wrapper adapter. The provider can now be constructed with just a secret and will build its Better Auth instance (including running migrations) against the host database during init. It also bootstraps a personal organization for new users (ensureOrganization), checks organization admin roles (isOrganizationAdmin), and exposes the Better Auth HTTP handler (handleAuthRequest) so hosts can mount it under /auth/api/*. ([#19765](https://github.com/mastra-ai/mastra/pull/19765))
+
+  **Before**
+
+  ```ts
+  import { betterAuth } from 'better-auth';
+  import { MastraAuthBetterAuth } from '@mastra/auth-better-auth';
+
+  const auth = new MastraAuthBetterAuth({ auth: betterAuth({/* ... */}) });
+  ```
+
+  **After** (bring-your-own instance still works)
+
+  ```ts
+  import { MastraAuthBetterAuth } from '@mastra/auth-better-auth';
+
+  const auth = new MastraAuthBetterAuth({ secret: process.env.BETTER_AUTH_SECRET! });
+  // host calls auth.init({ database, publicUrl, allowedOrigins }) during startup
+  ```
+
 ## 1.1.2-alpha.1
 
 ### Patch Changes

package/dist/_types/@internal_auth/dist/ee/fga-check.d.ts

@@ -3,12 +3,9 @@
  *
  * @license Mastra Enterprise License - see ee/LICENSE
  */
-import type { FGACheckContext, IFGAProvider } from './interfaces/fga.js';
+import type { ActorSignal, FGACheckContext, IFGAProvider } from './interfaces/fga.js';
 import type { MastraFGAPermissionInput } from './interfaces/permissions.generated.js';
-export type ActorSignal = true | {
-    actorKind: 'system';
-    sourceWorkflow?: string;
-};
+export type { ActorSignal };
 export interface CheckFGAOptions {
     fgaProvider: IFGAProvider | undefined;
     user: any;

package/dist/_types/@internal_auth/dist/ee/interfaces/fga.d.ts

@@ -8,6 +8,34 @@
  * @license Mastra Enterprise License - see ee/LICENSE
  */
 import type { MastraFGAPermissionInput } from './permissions.generated.js';
+/**
+ * Signals that a call is made by a trusted non-user actor rather than an
+ * authenticated end user.
+ *
+ * - `true` is the anonymous system shorthand.
+ * - The object form additionally names the acting agent (`agentId`) and carries
+ *   the permission grants / scope a provider can enforce for least privilege.
+ */
+export type ActorSignal = true | {
+    actorKind: 'system';
+    sourceWorkflow?: string;
+    /**
+     * Identity of the acting system agent. Unlike the check `resource` (the
+     * target), this names the actor itself so a provider can enforce
+     * per-agent least privilege.
+     */
+    agentId?: string;
+    /**
+     * Permission grants *claimed* for this actor — the actor analog of a
+     * user's resolved permissions. This is an untrusted, self-asserted hint:
+     * a provider enforcing real least privilege should resolve the actor's
+     * authoritative grants from a trusted source (e.g. a manifest or FGA,
+     * keyed by `agentId`) rather than trusting these values directly.
+     */
+    permissions?: MastraFGAPermissionInput[];
+    /** Additional provider-specific scope for the actor (e.g. tenant, environment). */
+    scope?: Record<string, string>;
+};
 /**
  * Optional context for an authorization check.
  */
@@ -306,6 +334,25 @@ export interface IFGAProvider<TUser = unknown> {
     filterAccessible<T extends {
         id: string;
     }>(user: TUser, resources: T[], resourceType: string, permission: MastraFGAPermissionInput): Promise<T[]>;
+    /**
+     * Authorize a non-user (system / autonomous agent) actor.
+     *
+     * System actors bypass the user-centric `require()` path. Implement this
+     * method to opt in to provider-driven least privilege for those actors:
+     * decide whether the actor (identified by `actor.agentId` and constrained by
+     * `actor.permissions` / `actor.scope`) may perform `permission` on
+     * `resource`, and throw {@link FGADeniedError} to deny.
+     *
+     * When this method is not implemented, Mastra preserves the legacy
+     * trusted-actor bypass (allow after the tenant-scope check). Adding it is
+     * therefore fully backward compatible.
+     *
+     * @param actor - The system actor signal (`true` shorthand, or an object with
+     *   `agentId`, `permissions`, `scope`).
+     * @param params - The resource and permission being attempted.
+     * @throws FGADeniedError if the actor may not perform the action.
+     */
+    requireActor?(actor: ActorSignal, params: FGACheckParams): Promise<void>;
 }
 /**
  * Extended FGA interface with write operations for managing resources and role assignments.

package/dist/_types/@internal_auth/dist/index.d.ts

@@ -270,6 +270,72 @@ export interface ICredentialsProvider<TUser extends User = User> {
      */
     isSignUpEnabled?(): boolean;
 }
+/**
+ * Provider interface for organization membership management.
+ *
+ * Implement this interface to enable multi-tenant hosts (e.g. the Mastra Code
+ * web factory) to bootstrap a personal organization for new users and to
+ * authorize organization-level administrative mutations.
+ */
+export interface IOrganizationsProvider {
+    /**
+     * Ensure the user belongs to an organization, bootstrapping a personal org
+     * on first use when they have none. Must be idempotent under
+     * concurrent/retried first logins.
+     *
+     * @param userId - Stable provider user id
+     * @returns The organization id, or `undefined` when the user genuinely
+     * stays no-org (bootstrap is best-effort)
+     */
+    ensureOrganization(userId: string): Promise<string | undefined>;
+    /**
+     * Whether the user holds an admin-equivalent role in the organization.
+     * Provider errors should resolve to `false` rather than throw.
+     *
+     * @param organizationId - Organization id
+     * @param userId - Stable provider user id
+     */
+    isOrganizationAdmin(organizationId: string, userId: string): Promise<boolean>;
+}
+/**
+ * Host-level context handed to {@link IAuthInit.init} once during server
+ * preparation. Storage-agnostic: hosts pass whatever database handle their
+ * storage backend exposes.
+ */
+export interface AuthInitContext {
+    /**
+     * Database handle for providers that persist their own auth tables
+     * (e.g. better-auth). Shape is provider-defined; hosts pass their storage
+     * backend's auth database as-is.
+     */
+    database?: unknown;
+    /** Browser-facing origin (no trailing slash), e.g. `https://factory.acme.com`. */
+    publicUrl?: string;
+    /**
+     * Extra browser origins allowed to talk to the API (cross-origin SPA
+     * deploys). Providers that enforce their own origin allow-list (e.g.
+     * better-auth `trustedOrigins`) must honor these.
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * Optional one-time initialization hook for auth providers. Hosts call
+ * `init()` once during preparation with host-level context (database, public
+ * origin) so providers can consume it without the deploy entry passing it
+ * twice. Providers should fail fast here for requirements only satisfiable at
+ * prepare time.
+ */
+export interface IAuthInit {
+    init(ctx: AuthInitContext): Promise<void>;
+}
+/**
+ * Provider interface for handling raw auth HTTP requests. Providers that ship
+ * their own HTTP API surface (e.g. better-auth's `/api/auth/*` handler)
+ * implement this so hosts can mount it (typically under `/auth/api/*`).
+ */
+export interface IAuthHttpHandler {
+    handleAuthRequest(request: Request): Promise<Response>;
+}
 export * from './session/index.js';
 export * from './provider/index.js';
 export * from './types/index.js';

package/dist/_types/@internal_auth/dist/provider/index.d.ts

@@ -1,5 +1,5 @@
 import { MastraBase } from '../_types/@internal_core/dist/base/index.d.ts';
-import type { CredentialsResult, ISSOProvider, ISessionProvider, IUserProvider, Session, SSOCallbackResult, SSOLoginConfig, User } from '..';
+import type { CredentialsResult, IAuthHttpHandler, IAuthInit, ICredentialsProvider, IOrganizationsProvider, ISSOProvider, ISessionProvider, IUserProvider, Session, SSOCallbackResult, SSOLoginConfig, User } from '..';
 import type { AuthorizeUserFn, MastraAuthConfig, MastraAuthRequest } from '../types/index.js';
 export interface MastraAuthProviderOptions<TUser = unknown> {
     name?: string;
@@ -72,6 +72,13 @@ export declare abstract class MastraAuthProvider<TUser = unknown> extends Mastra
     abstract authorizeUser(user: TUser, request: MastraAuthRequest): Promise<boolean> | boolean;
     protected registerOptions(opts?: MastraAuthProviderOptions<TUser>): void;
 }
+export declare function isSSOProvider(p: unknown): p is ISSOProvider;
+export declare function isSessionProvider(p: unknown): p is ISessionProvider;
+export declare function isUserProvider(p: unknown): p is IUserProvider;
+export declare function isCredentialsProvider(p: unknown): p is ICredentialsProvider;
+export declare function isOrganizationsProvider(p: unknown): p is IOrganizationsProvider;
+export declare function isAuthHttpHandler(p: unknown): p is IAuthHttpHandler;
+export declare function hasAuthInit(p: unknown): p is IAuthInit;
 export declare class CompositeAuth extends MastraAuthProvider implements ISSOProvider<User>, ISessionProvider<Session>, IUserProvider<User> {
     private providers;
     private authenticatedProviderByObject;

package/dist/index.cjs

@@ -1,6 +1,10 @@
 'use strict';
 
-var crypto = require('better-auth/crypto');
+var kyselyLibsql = require('@libsql/kysely-libsql');
+var betterAuth = require('better-auth');
+var crypto$1 = require('better-auth/crypto');
+var migration = require('better-auth/db/migration');
+var plugins = require('better-auth/plugins');
 
 // ../../packages/_internal-core/dist/chunk-3M4SEWMI.js
 var RegisteredLogger = {
@@ -154,7 +158,7 @@ var MastraBase = class {
   }
 };
 
-// ../../packages/_internals/auth/dist/chunk-7GLKLOU3.js
+// ../../packages/_internals/auth/dist/chunk-NJOKT6V5.js
 var MastraAuthProvider = class extends MastraBase {
   protected;
   public;
@@ -209,23 +213,253 @@ function mapBetterAuthUserToEEUser(user) {
   };
 }
 var MastraAuthBetterAuth = class extends MastraAuthProvider {
-  auth;
+  #auth;
+  #secret;
+  /** True when `init()` built the instance — then we also own its migrations. */
+  #ownsInstance = false;
+  /** Once-per-process migration latch; reset on failure so a later call retries. */
+  #migrated;
+  /** In-process `userId → orgId` cache so hosts can call `ensureOrganization` per request. */
+  #orgCache = /* @__PURE__ */ new Map();
+  /** Set from `init()`: cross-origin SPA deploys need SameSite=None; Secure cookies. */
+  #crossSite = false;
   signUpEnabledConfig;
-  sessionCookieName;
   constructor(options) {
     super({ name: options?.name ?? "better-auth" });
-    if (!options.auth) {
+    if (!options.auth && !options.secret) {
       throw new Error(
-        "Better Auth instance is required. Please provide the auth option with your Better Auth instance created via betterAuth({ ... })"
+        "Better Auth instance is required. Please provide the auth option with your Better Auth instance created via betterAuth({ ... }), or provide `secret` so the provider can build its own instance in init() on the host database."
       );
     }
-    this.auth = options.auth;
+    this.#auth = options.auth;
+    this.#secret = options.secret;
     this.signUpEnabledConfig = options.signUpEnabled ?? true;
-    const authWithOptions = this.auth;
-    const prefix = authWithOptions.options?.advanced?.cookiePrefix ?? "better-auth";
-    this.sessionCookieName = `${prefix}.session_token`;
     this.registerOptions(options);
   }
+  /**
+   * The active Better Auth instance. Throws before `init()` in deferred
+   * instance mode (constructed with `secret` instead of `auth`).
+   */
+  get auth() {
+    if (!this.#auth) {
+      throw new Error(
+        "MastraAuthBetterAuth is not initialized \u2014 init() must run first (or pass a configured `auth` instance)."
+      );
+    }
+    return this.#auth;
+  }
+  /**
+   * Session cookie name, honoring Better Auth's `cookiePrefix`, a caller
+   * override via `advanced.cookies.session_token.name`, and the `__Secure-`
+   * prefix Better Auth applies when secure cookies are active.
+   */
+  get sessionCookieName() {
+    const options = this.#auth?.options;
+    const advanced = options?.advanced;
+    const prefix = advanced?.cookiePrefix ?? "better-auth";
+    const secure = advanced?.useSecureCookies ?? options?.baseURL?.startsWith("https://") ?? false;
+    const baseName = advanced?.cookies?.session_token?.name ?? `${prefix}.session_token`;
+    return `${secure ? "__Secure-" : ""}${baseName}`;
+  }
+  // ============================================
+  // IAuthInit implementation
+  // ============================================
+  /**
+   * One-time host initialization. In deferred instance mode (no `auth` in the
+   * options) this builds the provider-owned `betterAuth()` instance on the
+   * host's auth database; schema migrations then run lazily behind a
+   * once-per-process latch on first use.
+   *
+   * Bring-your-own `auth` instances skip construction entirely — the caller
+   * owns their database and migrations.
+   */
+  async init(ctx) {
+    this.#crossSite = (ctx.allowedOrigins?.length ?? 0) > 0;
+    if (this.#auth) return;
+    const authDb = ctx.database;
+    if (!authDb) {
+      throw new Error(
+        "MastraAuthBetterAuth needs a database to build its own better-auth instance, but the host passed none. Use a storage backend that exposes an auth database, or pass your own configured `auth` instance."
+      );
+    }
+    const database = authDb.dialect === "postgres" ? authDb.pool : authDb.dialect === "libsql" ? {
+      dialect: new kyselyLibsql.LibsqlDialect({ client: authDb.client }),
+      type: "sqlite"
+    } : authDb.database;
+    const allowedOrigins = ctx.allowedOrigins ?? [];
+    const options = {
+      database,
+      secret: this.#secret,
+      // All provider endpoints (sign-in/up/out/session) live under /auth/api/*,
+      // where hosts mount handleAuthRequest.
+      basePath: "/auth/api",
+      ...ctx.publicUrl ? { baseURL: ctx.publicUrl } : {},
+      // Cross-origin SPA deploys: SameSite=None only lets the browser SEND the
+      // cookie — better-auth still rejects requests from origins outside its
+      // own allow-list, so the SPA origins must be trusted too.
+      ...allowedOrigins.length ? { trustedOrigins: allowedOrigins } : {},
+      emailAndPassword: { enabled: true, disableSignUp: !this.signUpEnabledConfig },
+      plugins: [plugins.organization()],
+      // Cross-origin SPA deploys need SameSite=None; Secure for the browser to
+      // send the session cookie.
+      ...this.#crossSite ? { advanced: { defaultCookieAttributes: { sameSite: "none", secure: true } } } : {}
+    };
+    this.#auth = betterAuth.betterAuth(options);
+    this.#ownsInstance = true;
+  }
+  /**
+   * Ensure better-auth's tables exist in the host database. Only for instances
+   * this provider built — bring-your-own instances manage their own migrations.
+   */
+  async #ensureDbReady() {
+    if (!this.#ownsInstance) return;
+    this.#migrated ??= (async () => {
+      const { runMigrations } = await migration.getMigrations(this.auth.options);
+      await runMigrations();
+    })();
+    try {
+      await this.#migrated;
+    } catch (error) {
+      this.#migrated = void 0;
+      console.warn("[BetterAuth] Failed to run auth schema migrations; auth stays unavailable until this succeeds.");
+      throw error;
+    }
+  }
+  // ============================================
+  // IAuthHttpHandler implementation
+  // ============================================
+  /**
+   * Proxy a raw HTTP request to Better Auth's own API surface
+   * (sign-in/up/out/session). Hosts mount this under `/auth/api/*`.
+   */
+  async handleAuthRequest(request) {
+    try {
+      await this.#ensureDbReady();
+    } catch {
+      return new Response(JSON.stringify({ error: "auth_unavailable" }), {
+        status: 503,
+        headers: { "content-type": "application/json" }
+      });
+    }
+    return this.auth.handler(request);
+  }
+  // ============================================
+  // IOrganizationsProvider implementation
+  // ============================================
+  /**
+   * Ensure the user belongs to an organization, mirroring the WorkOS
+   * personal-org bootstrap on better-auth's organization tables:
+   * ≥1 membership → first org id; 0 → create a personal org with an
+   * idempotent slug derived from the user id.
+   *
+   * Concurrent/retried first logins recover via the unique slug instead of
+   * creating duplicates. Slug alone is NOT proof of ownership though: the
+   * organization API is reachable by any authenticated user, so an attacker
+   * could squat `personal-<victimId>`. The slug-matched org is only adopted
+   * when nobody else is a member; otherwise a fresh org with an unguessable
+   * slug is created instead.
+   *
+   * Best-effort: any failure is swallowed and leaves the user no-org.
+   */
+  async ensureOrganization(userId) {
+    const cached = this.#orgCache.get(userId);
+    if (cached) return cached;
+    try {
+      await this.#ensureDbReady();
+      const ctx = await this.getAuthContext();
+      if (!ctx) return void 0;
+      const memberships = await ctx.adapter.findMany({
+        model: "member",
+        where: [{ field: "userId", value: userId }]
+      });
+      const firstExisting = memberships.find((m) => m.organizationId)?.organizationId;
+      if (firstExisting) {
+        this.#orgCache.set(userId, firstExisting);
+        return firstExisting;
+      }
+      const userRecord = await ctx.internalAdapter.findUserById(userId).catch(() => null);
+      const label = userRecord?.email ?? userRecord?.name ?? userId;
+      const orgName = `${label}'s org`;
+      const orgData = () => ({
+        name: orgName,
+        createdAt: /* @__PURE__ */ new Date(),
+        metadata: JSON.stringify({ mastraPersonalOrg: "true" })
+      });
+      const slug = `personal-${userId}`;
+      let organizationId;
+      try {
+        const created = await ctx.adapter.create({
+          model: "organization",
+          data: { ...orgData(), slug }
+        });
+        organizationId = created.id;
+      } catch (error) {
+        const existing = await ctx.adapter.findOne({
+          model: "organization",
+          where: [{ field: "slug", value: slug }]
+        });
+        if (!existing) throw error;
+        const existingMembers = await ctx.adapter.findMany({
+          model: "member",
+          where: [{ field: "organizationId", value: existing.id }]
+        });
+        const foreignMember = existingMembers.some((m) => m.userId !== userId);
+        if (foreignMember) {
+          const fallback = await ctx.adapter.create({
+            model: "organization",
+            data: { ...orgData(), slug: `personal-${userId}-${crypto.randomUUID()}` }
+          });
+          organizationId = fallback.id;
+        } else {
+          organizationId = existing.id;
+        }
+      }
+      try {
+        await ctx.adapter.create({
+          model: "member",
+          data: { organizationId, userId, role: "owner", createdAt: /* @__PURE__ */ new Date() }
+        });
+      } catch (error) {
+        const member = await ctx.adapter.findOne({
+          model: "member",
+          where: [
+            { field: "organizationId", value: organizationId },
+            { field: "userId", value: userId }
+          ]
+        });
+        if (!member) throw error;
+      }
+      this.#orgCache.set(userId, organizationId);
+      return organizationId;
+    } catch (error) {
+      console.warn(
+        `[BetterAuth] Failed to bootstrap personal organization for user ${userId}. The user will see organization_required until this succeeds.`,
+        error
+      );
+      return void 0;
+    }
+  }
+  /**
+   * Whether the user holds an admin-equivalent role (`owner` or `admin`) in
+   * the organization. Provider errors resolve to `false`.
+   */
+  async isOrganizationAdmin(organizationId, userId) {
+    try {
+      await this.#ensureDbReady();
+      const ctx = await this.getAuthContext();
+      if (!ctx) return false;
+      const membership = await ctx.adapter.findOne({
+        model: "member",
+        where: [
+          { field: "organizationId", value: organizationId },
+          { field: "userId", value: userId }
+        ]
+      });
+      return membership?.role === "owner" || membership?.role === "admin";
+    } catch {
+      return false;
+    }
+  }
   /**
    * Check if sign-up is enabled.
    * Implements ICredentialsProvider.isSignUpEnabled.
@@ -249,6 +483,7 @@ var MastraAuthBetterAuth = class extends MastraAuthProvider {
    */
   async getCurrentUser(request) {
     try {
+      await this.#ensureDbReady();
       const headers = new Headers(request.headers);
       const authHeader = headers.get("Authorization");
       const bearerToken = authHeader && authHeader.slice(0, 7).toLowerCase() === "bearer " ? authHeader.slice(7).trim() : void 0;
@@ -333,7 +568,7 @@ var MastraAuthBetterAuth = class extends MastraAuthProvider {
     if (hasSessionCookie) return;
     let cookieValue = token.includes(".") ? token.includes("%") ? tryDecode(token) : token : token;
     if (!token.includes(".") && secret) {
-      cookieValue = `${token}.${await crypto.makeSignature(token, secret)}`;
+      cookieValue = `${token}.${await crypto$1.makeSignature(token, secret)}`;
     }
     const existingCookies = cookieHeader ? `${cookieHeader}; ` : "";
     headers.set("Cookie", `${existingCookies}${cookieName}=${encodeURIComponent(cookieValue)}`);
@@ -352,6 +587,7 @@ var MastraAuthBetterAuth = class extends MastraAuthProvider {
    */
   async authenticateToken(token, request) {
     try {
+      await this.#ensureDbReady();
       const headers = new Headers();
       const cookieHeader = getRequestHeader2(request, "Cookie");
       if (cookieHeader) {
@@ -477,9 +713,10 @@ var MastraAuthBetterAuth = class extends MastraAuthProvider {
    * Clears Better Auth's default session cookies.
    */
   getClearSessionHeaders() {
+    const sameSite = this.#crossSite ? "None; Secure" : "Lax";
     const cookies = [
-      `${this.sessionCookieName}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`,
-      `${this.sessionCookieName}_sig=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`
+      `${this.sessionCookieName}=; Path=/; HttpOnly; SameSite=${sameSite}; Max-Age=0`,
+      `${this.sessionCookieName}_sig=; Path=/; HttpOnly; SameSite=${sameSite}; Max-Age=0`
     ];
     return {
       "Set-Cookie": cookies.join(", ")