@mastra/auth-studio 1.3.1-alpha.0 → 1.3.2-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/auth-studio
 
+## 1.3.2-alpha.0
+
+### Patch Changes
+
+- `MastraAuthStudio` now automatically creates a personal organization for users who don't belong to one yet, and can check whether a user is an organization admin — matching the behavior already available in `MastraAuthWorkos` and `MastraAuthBetterAuth`. This lets hosts like a self-hosted MastraCode deployment authorize organization-level actions without users needing to manually set up an organization first. ([#19858](https://github.com/mastra-ai/mastra/pull/19858))
+
+- `MastraAuthStudio.ensureOrganization` now dedupes concurrent bootstraps for the same user, so parallel tabs or requests for a brand-new sign-in no longer end up creating duplicate personal organizations. ([#19858](https://github.com/mastra-ai/mastra/pull/19858))
+
+## 1.3.1
+
+### Patch Changes
+
+- Improved auth package builds by removing the direct core dependency from auth providers while preserving the existing public auth APIs. ([#17142](https://github.com/mastra-ai/mastra/pull/17142))
+
 ## 1.3.1-alpha.0
 
 ### 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/ee/interfaces/permissions.generated.d.ts

@@ -10,7 +10,7 @@
  * All known API resources.
  * Derived from SERVER_ROUTES paths in @mastra/server.
  */
-export declare const RESOURCES: readonly ["a2a", "agent-builder", "agents", "auth", "background-tasks", "channels", "datasets", "embedders", "experiments", "harness", "infrastructure", "logs", "mcp", "memory", "observability", "processor-providers", "processors", "schedules", "scores", "stored-agents", "stored-mcp-clients", "stored-prompt-blocks", "stored-scorers", "stored-skills", "stored-workspaces", "system", "tool-providers", "tools", "vector", "vectors", "workflows", "workspaces"];
+export declare const RESOURCES: readonly ["a2a", "agent-builder", "agent-controller", "agents", "auth", "background-tasks", "channels", "datasets", "embedders", "experiments", "infrastructure", "logs", "mcp", "memory", "observability", "processor-providers", "processors", "schedules", "scores", "stored-agents", "stored-mcp-clients", "stored-prompt-blocks", "stored-scorers", "stored-skills", "stored-workspaces", "system", "tool-providers", "tools", "vector", "vectors", "workflows", "workspaces"];
 /**
  * Resource type union.
  */
@@ -54,6 +54,8 @@ export declare const PERMISSION_PATTERNS: {
     readonly 'a2a:*': "a2a:*";
     /** Full access to agent builder */
     readonly 'agent-builder:*': "agent-builder:*";
+    /** Full access to agent controller sessions */
+    readonly 'agent-controller:*': "agent-controller:*";
     /** Full access to agents */
     readonly 'agents:*': "agents:*";
     /** Full access to auth */
@@ -68,8 +70,6 @@ export declare const PERMISSION_PATTERNS: {
     readonly 'embedders:*': "embedders:*";
     /** Full access to experiments */
     readonly 'experiments:*': "experiments:*";
-    /** Full access to harness sessions */
-    readonly 'harness:*': "harness:*";
     /** Full access to infrastructure */
     readonly 'infrastructure:*': "infrastructure:*";
     /** Full access to logs */
@@ -124,6 +124,10 @@ export declare const PERMISSION_PATTERNS: {
     readonly 'agent-builder:read': "agent-builder:read";
     /** Create and modify agent builder */
     readonly 'agent-builder:write': "agent-builder:write";
+    /** Execute agent controller sessions */
+    readonly 'agent-controller:execute': "agent-controller:execute";
+    /** View agent controller sessions */
+    readonly 'agent-controller:read': "agent-controller:read";
     /** Create agents */
     readonly 'agents:create': "agents:create";
     /** Delete agents */
@@ -154,10 +158,6 @@ export declare const PERMISSION_PATTERNS: {
     readonly 'embedders:read': "embedders:read";
     /** View experiments */
     readonly 'experiments:read': "experiments:read";
-    /** Execute harness sessions */
-    readonly 'harness:execute': "harness:execute";
-    /** View harness sessions */
-    readonly 'harness:read': "harness:read";
     /** View infrastructure */
     readonly 'infrastructure:read': "infrastructure:read";
     /** View logs */
@@ -186,6 +186,8 @@ export declare const PERMISSION_PATTERNS: {
     readonly 'processors:execute': "processors:execute";
     /** View processors */
     readonly 'processors:read': "processors:read";
+    /** Delete schedules */
+    readonly 'schedules:delete': "schedules:delete";
     /** Execute schedules */
     readonly 'schedules:execute': "schedules:execute";
     /** View schedules */
@@ -303,7 +305,7 @@ export type PermissionPattern = keyof typeof PERMISSION_PATTERNS;
 /**
  * All valid resource:action permission combinations (excludes wildcards).
  */
-export declare const PERMISSIONS: readonly ["a2a:read", "a2a:write", "agent-builder:execute", "agent-builder:read", "agent-builder:write", "agents:create", "agents:delete", "agents:execute", "agents:read", "agents:write", "auth:read", "background-tasks:read", "channels:read", "channels:write", "datasets:delete", "datasets:execute", "datasets:read", "datasets:write", "embedders:read", "experiments:read", "harness:execute", "harness:read", "infrastructure:read", "logs:read", "mcp:execute", "mcp:read", "mcp:write", "memory:delete", "memory:execute", "memory:read", "memory:write", "observability:read", "observability:write", "processor-providers:read", "processors:execute", "processors:read", "schedules:execute", "schedules:read", "schedules:write", "scores:read", "scores:write", "stored-agents:delete", "stored-agents:publish", "stored-agents:read", "stored-agents:write", "stored-mcp-clients:delete", "stored-mcp-clients:publish", "stored-mcp-clients:read", "stored-mcp-clients:write", "stored-prompt-blocks:delete", "stored-prompt-blocks:publish", "stored-prompt-blocks:read", "stored-prompt-blocks:write", "stored-scorers:delete", "stored-scorers:publish", "stored-scorers:read", "stored-scorers:write", "stored-skills:delete", "stored-skills:publish", "stored-skills:read", "stored-skills:write", "stored-workspaces:delete", "stored-workspaces:read", "stored-workspaces:write", "system:read", "tool-providers:delete", "tool-providers:read", "tool-providers:write", "tools:execute", "tools:read", "vector:delete", "vector:execute", "vector:read", "vector:write", "vectors:read", "workflows:delete", "workflows:execute", "workflows:read", "workflows:write", "workspaces:delete", "workspaces:read", "workspaces:write"];
+export declare const PERMISSIONS: readonly ["a2a:read", "a2a:write", "agent-builder:execute", "agent-builder:read", "agent-builder:write", "agent-controller:execute", "agent-controller:read", "agents:create", "agents:delete", "agents:execute", "agents:read", "agents:write", "auth:read", "background-tasks:read", "channels:read", "channels:write", "datasets:delete", "datasets:execute", "datasets:read", "datasets:write", "embedders:read", "experiments:read", "infrastructure:read", "logs:read", "mcp:execute", "mcp:read", "mcp:write", "memory:delete", "memory:execute", "memory:read", "memory:write", "observability:read", "observability:write", "processor-providers:read", "processors:execute", "processors:read", "schedules:delete", "schedules:execute", "schedules:read", "schedules:write", "scores:read", "scores:write", "stored-agents:delete", "stored-agents:publish", "stored-agents:read", "stored-agents:write", "stored-mcp-clients:delete", "stored-mcp-clients:publish", "stored-mcp-clients:read", "stored-mcp-clients:write", "stored-prompt-blocks:delete", "stored-prompt-blocks:publish", "stored-prompt-blocks:read", "stored-prompt-blocks:write", "stored-scorers:delete", "stored-scorers:publish", "stored-scorers:read", "stored-scorers:write", "stored-skills:delete", "stored-skills:publish", "stored-skills:read", "stored-skills:write", "stored-workspaces:delete", "stored-workspaces:read", "stored-workspaces:write", "system:read", "tool-providers:delete", "tool-providers:read", "tool-providers:write", "tools:execute", "tools:read", "vector:delete", "vector:execute", "vector:read", "vector:write", "vectors:read", "workflows:delete", "workflows:execute", "workflows:read", "workflows:write", "workspaces:delete", "workspaces:read", "workspaces:write"];
 /**
  * Specific permission type (e.g., 'agents:read', 'workflows:execute').
  */
@@ -325,6 +327,10 @@ export declare const MastraFGAPermissions: {
     readonly AGENT_BUILDER_READ: "agent-builder:read";
     /** Create and modify agent builder */
     readonly AGENT_BUILDER_WRITE: "agent-builder:write";
+    /** Execute agent controller sessions */
+    readonly AGENT_CONTROLLER_EXECUTE: "agent-controller:execute";
+    /** View agent controller sessions */
+    readonly AGENT_CONTROLLER_READ: "agent-controller:read";
     /** Create agents */
     readonly AGENTS_CREATE: "agents:create";
     /** Delete agents */
@@ -355,10 +361,6 @@ export declare const MastraFGAPermissions: {
     readonly EMBEDDERS_READ: "embedders:read";
     /** View experiments */
     readonly EXPERIMENTS_READ: "experiments:read";
-    /** Execute harness sessions */
-    readonly HARNESS_EXECUTE: "harness:execute";
-    /** View harness sessions */
-    readonly HARNESS_READ: "harness:read";
     /** View infrastructure */
     readonly INFRASTRUCTURE_READ: "infrastructure:read";
     /** View logs */
@@ -387,6 +389,8 @@ export declare const MastraFGAPermissions: {
     readonly PROCESSORS_EXECUTE: "processors:execute";
     /** View processors */
     readonly PROCESSORS_READ: "processors:read";
+    /** Delete schedules */
+    readonly SCHEDULES_DELETE: "schedules:delete";
     /** Execute schedules */
     readonly SCHEDULES_EXECUTE: "schedules:execute";
     /** View schedules */

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;
@@ -14,7 +14,44 @@ export interface MastraAuthProviderOptions<TUser = unknown> {
      */
     public?: MastraAuthConfig['public'];
 }
-export declare abstract class MastraAuthProvider<TUser = unknown> extends MastraBase {
+/**
+ * Structural description of the public surface of a `MastraAuthProvider`.
+ *
+ * Auth provider packages bundle their own copy of the `MastraAuthProvider`
+ * declaration, so provider class types cannot be compared nominally across
+ * package boundaries — `#private`/`protected` members would make otherwise
+ * identical copies mutually unassignable. Positions that accept user-supplied
+ * providers (e.g. `server.auth`, `CompositeAuth`) accept this interface
+ * instead of the class.
+ *
+ * Note: methods intentionally use method syntax (not property syntax) so they
+ * are checked bivariantly — providers with a narrower `TUser` must remain
+ * assignable to `IMastraAuthProvider<unknown>`.
+ */
+export interface IMastraAuthProvider<TUser = unknown> {
+    name?: string;
+    /**
+     * Protected paths for the auth provider
+     */
+    protected?: MastraAuthConfig['protected'];
+    /**
+     * Public paths for the auth provider
+     */
+    public?: MastraAuthConfig['public'];
+    /**
+     * Authenticate a token and return the payload
+     */
+    authenticateToken(token: string, request: MastraAuthRequest): Promise<TUser | null>;
+    /**
+     * Authorize a user for a path and method
+     */
+    authorizeUser(user: TUser, request: MastraAuthRequest): Promise<boolean> | boolean;
+    /**
+     * Map an authenticated user to a memory resource id
+     */
+    mapUserToResourceId?(user: TUser): string | undefined | null;
+}
+export declare abstract class MastraAuthProvider<TUser = unknown> extends MastraBase implements IMastraAuthProvider<TUser> {
     protected?: MastraAuthConfig['protected'];
     public?: MastraAuthConfig['public'];
     mapUserToResourceId?(user: TUser): string | undefined | null;
@@ -35,11 +72,18 @@ 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;
     private authenticatedProviderByPrimitive;
-    constructor(providers: MastraAuthProvider[]);
+    constructor(providers: IMastraAuthProvider[]);
     private findProvider;
     private rememberAuthenticatedProvider;
     private takeAuthenticatedProvider;

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-// ../../packages/_internals/auth/dist/chunk-JCX4XB6F.js
+// ../../packages/_internals/auth/dist/chunk-LZCWL5CT.js
 var RESOURCE_EXPANSIONS = {
   stored: [
     "stored-agents",
@@ -229,7 +229,7 @@ var MastraBase = class {
   }
 };
 
-// ../../packages/_internals/auth/dist/chunk-XG6GH2VJ.js
+// ../../packages/_internals/auth/dist/chunk-NJOKT6V5.js
 var MastraAuthProvider = class extends MastraBase {
   protected;
   public;
@@ -272,6 +272,23 @@ var MastraAuthStudio = class extends MastraAuthProvider {
   organizationId;
   useProductionCookies;
   cookieDomain;
+  /**
+   * `userId → sealed session cookie` cache. The `IOrganizationsProvider`
+   * interface only hands us a `userId`, but the shared API's org endpoints are
+   * cookie-authenticated — so we remember the cookie last seen for a user
+   * inside `verifySessionCookie` and reuse it here. Kept small: bounded to
+   * the last 1000 users, LRU-evicted on insert.
+   */
+  userSessionCookies = /* @__PURE__ */ new Map();
+  maxCachedSessions = 1e3;
+  /**
+   * In-flight `ensureOrganization` promises keyed by userId. Concurrent calls
+   * for the same brand-new user (multiple tabs, parallel requests) would
+   * otherwise all see "no org" from `GET /auth/me` and each fire
+   * `POST /auth/orgs`, creating duplicate personal organizations. The first
+   * caller's promise is reused by every follower until it settles.
+   */
+  organizationBootstrapInFlight = /* @__PURE__ */ new Map();
   constructor(options) {
     super({ name: "mastra-studio", ...options });
     this.sharedApiUrl = options?.sharedApiUrl || process.env.MASTRA_SHARED_API_URL || "http://localhost:3010/v1";
@@ -510,8 +527,127 @@ var MastraAuthStudio = class extends MastraAuthProvider {
     return null;
   }
   // ---------------------------------------------------------------------------
+  // IOrganizationsProvider
+  // ---------------------------------------------------------------------------
+  /**
+   * Ensure the user belongs to an organization, bootstrapping a personal org
+   * on first use when they have none.
+   *
+   * Because the shared API's org endpoints are cookie-authenticated but this
+   * method only receives a userId, we look up the user's sealed session cookie
+   * from the {@link userSessionCookies} cache populated by
+   * {@link verifySessionCookie}. If we have never seen a cookie for this user
+   * (e.g. bearer-token flow, or the cache was evicted), we skip bootstrap and
+   * return `undefined` — the caller keeps the user in their current no-org
+   * state and the next authenticated request retries.
+   *
+   * Best-effort: any shared-API failure returns `undefined` rather than
+   * throwing, mirroring `MastraAuthWorkos.ensureOrganization`.
+   */
+  async ensureOrganization(userId) {
+    const inFlight = this.organizationBootstrapInFlight.get(userId);
+    if (inFlight) return inFlight;
+    const bootstrap = this.doEnsureOrganization(userId).finally(() => {
+      this.organizationBootstrapInFlight.delete(userId);
+    });
+    this.organizationBootstrapInFlight.set(userId, bootstrap);
+    return bootstrap;
+  }
+  async doEnsureOrganization(userId) {
+    const sessionCookie = this.userSessionCookies.get(userId);
+    if (!sessionCookie) {
+      this.logger.debug("ensureOrganization: no cached session cookie for user; skipping bootstrap", { userId });
+      return void 0;
+    }
+    try {
+      const me = await this.fetchMe(sessionCookie);
+      if (me?.organizationId) return me.organizationId;
+      if (me?.memberOrgIds && me.memberOrgIds.length > 0) return me.memberOrgIds[0];
+      const orgName = me?.user?.email ? `${me.user.email}'s org` : `Personal (${userId})`;
+      const res = await fetch(`${this.sharedApiUrl}/auth/orgs`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Cookie: `${COOKIE_NAME}=${sessionCookie}`
+        },
+        body: JSON.stringify({ name: orgName })
+      });
+      if (!res.ok) {
+        this.logger.warn("ensureOrganization: shared API POST /auth/orgs returned non-OK", {
+          status: res.status,
+          userId
+        });
+        return void 0;
+      }
+      const data = await res.json();
+      return data.organization?.id;
+    } catch (error) {
+      this.logger.error("ensureOrganization: fetch to shared API failed", {
+        userId,
+        error: error instanceof Error ? { message: error.message, stack: error.stack } : String(error)
+      });
+      return void 0;
+    }
+  }
+  /**
+   * Whether the user holds an admin-equivalent role in the organization.
+   *
+   * Fast path: if the org matches the user's currently-active session org, we
+   * read the role directly from `/auth/me`. Cross-org path: we call
+   * `/auth/orgs` (which returns per-membership roles) and look up the target
+   * org. Any shared-API failure resolves to `false`.
+   */
+  async isOrganizationAdmin(organizationId, userId) {
+    const sessionCookie = this.userSessionCookies.get(userId);
+    if (!sessionCookie) return false;
+    try {
+      const me = await this.fetchMe(sessionCookie);
+      if (me?.organizationId === organizationId) {
+        return isAdminRole(me.role);
+      }
+      const res = await fetch(`${this.sharedApiUrl}/auth/orgs`, {
+        headers: { Cookie: `${COOKIE_NAME}=${sessionCookie}` }
+      });
+      if (!res.ok) return false;
+      const data = await res.json();
+      const membership = data.organizations?.find((o) => o.id === organizationId);
+      return isAdminRole(membership?.role ?? void 0);
+    } catch {
+      return false;
+    }
+  }
+  // ---------------------------------------------------------------------------
   // Internal helpers
   // ---------------------------------------------------------------------------
+  /**
+   * Record the sealed session cookie last seen for a user so
+   * {@link ensureOrganization} / {@link isOrganizationAdmin} can act on their
+   * behalf. LRU-evicted at {@link maxCachedSessions} entries.
+   */
+  rememberUserSession(userId, sessionCookie) {
+    this.userSessionCookies.delete(userId);
+    this.userSessionCookies.set(userId, sessionCookie);
+    if (this.userSessionCookies.size > this.maxCachedSessions) {
+      const oldest = this.userSessionCookies.keys().next().value;
+      if (oldest !== void 0) this.userSessionCookies.delete(oldest);
+    }
+  }
+  /**
+   * Fetch the shared API's `/auth/me` and return the raw response body, or
+   * `null` on any non-OK / network error. Split out so `ensureOrganization`
+   * and `isOrganizationAdmin` can reuse it without duplicating the shape.
+   */
+  async fetchMe(sessionCookie) {
+    try {
+      const res = await fetch(`${this.sharedApiUrl}/auth/me`, {
+        headers: { Cookie: `${COOKIE_NAME}=${sessionCookie}` }
+      });
+      if (!res.ok) return null;
+      return await res.json();
+    } catch {
+      return null;
+    }
+  }
   /**
    * Forward a sealed session cookie to the shared API's /auth/me endpoint
    * to validate it and get user info.
@@ -532,6 +668,7 @@ var MastraAuthStudio = class extends MastraAuthProvider {
         return null;
       }
       const data = await res.json();
+      this.rememberUserSession(data.user.id, sessionCookie);
       return {
         id: data.user.id,
         email: data.user.email,
@@ -591,6 +728,9 @@ function parseCookie(cookieHeader, name) {
   const match = cookieHeader.match(new RegExp(`${name}=([^;]+)`));
   return match?.[1] ?? null;
 }
+function isAdminRole(role) {
+  return role === "admin" || role === "owner";
+}
 function parseCookieFromHeader(setCookieHeader, name) {
   const parts = setCookieHeader.split(";");
   if (parts.length === 0) return null;