@mastra/auth-cloud 1.2.0 → 1.2.1

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

@@ -0,0 +1,207 @@
+/**
+ * RBAC provider interface for EE authentication.
+ * Enables role-based access control in Studio.
+ *
+ * RBAC is designed to be separate from authentication.
+ * This allows users to mix auth providers with RBAC providers:
+ * - Use Better Auth for authentication + StaticRBACProvider for RBAC
+ * - Use Clerk for both auth and RBAC via MastraRBACClerk
+ * - Use Auth0 for auth + custom RBAC provider
+ */
+import type { PermissionPattern } from './permissions.generated.js';
+/**
+ * Definition of a role with its permissions.
+ * Uses type-safe permission patterns derived from SERVER_ROUTES.
+ */
+export interface RoleDefinition {
+    /** Unique role identifier */
+    id: string;
+    /** Human-readable role name */
+    name: string;
+    /** Role description */
+    description?: string;
+    /** Permissions granted by this role (type-safe) */
+    permissions: PermissionPattern[];
+    /** Role IDs this role inherits from */
+    inherits?: string[];
+}
+/**
+ * Role mapping configuration for translating provider roles to Mastra permissions.
+ * Uses type-safe permission patterns derived from SERVER_ROUTES.
+ *
+ * Use this when your identity provider (WorkOS, Okta, Azure AD, etc.) has its own
+ * roles that need to be translated to Mastra's permission model.
+ *
+ * Special keys:
+ * - `_default`: Permissions for roles not explicitly mapped
+ *
+ * @example
+ * ```typescript
+ * const roleMapping: RoleMapping = {
+ *   "Engineering": ["agents:*", "workflows:*"],
+ *   "Product": ["agents:read", "workflows:read"],
+ *   "Admin": ["*"],
+ *   "_default": [],  // unmapped roles get no permissions
+ * };
+ * ```
+ */
+export type RoleMapping = {
+    /** Map role name to array of permission patterns */
+    [role: string]: PermissionPattern[];
+};
+/**
+ * Provider interface for role-based access control (read-only).
+ *
+ * Implement this interface to enable:
+ * - Permission-based UI gating
+ * - Role display in user menu
+ * - Access control checks
+ *
+ * RBAC providers can be used independently of auth providers:
+ *
+ * @example Using StaticRBACProvider with Better Auth
+ * ```typescript
+ * // Better Auth handles authentication only
+ * const auth = new MastraAuthBetterAuth({ betterAuth });
+ *
+ * // Static RBAC handles authorization
+ * const rbac = new StaticRBACProvider({
+ *   roles: DEFAULT_ROLES,
+ *   getUserRoles: (user) => [user.role],
+ * });
+ *
+ * const mastra = new Mastra({
+ *   server: {
+ *     auth,
+ *     rbac,
+ *   },
+ * });
+ * ```
+ *
+ * @example Using MastraRBACClerk with role mapping
+ * ```typescript
+ * const mastra = new Mastra({
+ *   server: {
+ *     auth: new MastraAuthClerk({ clerk }),
+ *     rbac: new MastraRBACClerk({
+ *       clerk,
+ *       roleMapping: {
+ *         "org:admin": ["*"],
+ *         "org:member": ["agents:read", "workflows:read"],
+ *       },
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export interface IRBACProvider<TUser = unknown> {
+    /**
+     * Optional role mapping for translating provider roles to Mastra permissions.
+     * If provided, permissions are resolved using this mapping instead of getPermissions().
+     */
+    roleMapping?: RoleMapping;
+    /**
+     * Get all roles for a user.
+     *
+     * @param user - User to get roles for
+     * @returns Array of role IDs
+     */
+    getRoles(user: TUser): Promise<string[]>;
+    /**
+     * Check if user has a specific role.
+     *
+     * @param user - User to check
+     * @param role - Role ID to check for
+     * @returns True if user has the role
+     */
+    hasRole(user: TUser, role: string): Promise<boolean>;
+    /**
+     * Get all permissions for a user (resolved from roles).
+     *
+     * @param user - User to get permissions for
+     * @returns Array of permission strings
+     */
+    getPermissions(user: TUser): Promise<string[]>;
+    /**
+     * Check if user has a specific permission.
+     *
+     * @param user - User to check
+     * @param permission - Permission to check for
+     * @returns True if user has the permission
+     */
+    hasPermission(user: TUser, permission: string): Promise<boolean>;
+    /**
+     * Check if user has ALL of the specified permissions.
+     *
+     * @param user - User to check
+     * @param permissions - Permissions to check for
+     * @returns True if user has all permissions
+     */
+    hasAllPermissions(user: TUser, permissions: string[]): Promise<boolean>;
+    /**
+     * Check if user has ANY of the specified permissions.
+     *
+     * @param user - User to check
+     * @param permissions - Permissions to check for
+     * @returns True if user has at least one permission
+     */
+    hasAnyPermission(user: TUser, permissions: string[]): Promise<boolean>;
+    /**
+     * Get all available roles in the system.
+     * Used by the "View as role" feature to list roles an admin can impersonate.
+     *
+     * @returns Array of role descriptors
+     */
+    getAvailableRoles?(): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    /**
+     * Get the resolved permissions for a specific role.
+     * Used by the "View as role" feature to override client-side permissions.
+     *
+     * @param roleId - Role ID to resolve permissions for
+     * @returns Array of permission strings
+     */
+    getPermissionsForRole?(roleId: string): Promise<string[]>;
+}
+/**
+ * Extended interface for managing roles (write operations).
+ *
+ * Implement this in addition to IRBACProvider to enable role management.
+ */
+export interface IRBACManager<TUser = unknown> extends IRBACProvider<TUser> {
+    /**
+     * Assign a role to a user.
+     *
+     * @param userId - User to assign role to
+     * @param roleId - Role to assign
+     */
+    assignRole(userId: string, roleId: string): Promise<void>;
+    /**
+     * Remove a role from a user.
+     *
+     * @param userId - User to remove role from
+     * @param roleId - Role to remove
+     */
+    removeRole(userId: string, roleId: string): Promise<void>;
+    /**
+     * List all available roles.
+     *
+     * @returns Array of role definitions
+     */
+    listRoles(): Promise<RoleDefinition[]>;
+    /**
+     * Optional: Create a new role.
+     *
+     * @param role - Role definition to create
+     */
+    createRole?(role: RoleDefinition): Promise<void>;
+    /**
+     * Optional: Delete a role.
+     *
+     * @param roleId - Role ID to delete
+     */
+    deleteRole?(roleId: string): Promise<void>;
+}
+//# sourceMappingURL=rbac.d.ts.map

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

@@ -0,0 +1,18 @@
+/**
+ * Enterprise user type for EE authentication.
+ * Extends the base User type with enterprise-specific fields.
+ *
+ * @license Mastra Enterprise License - see ee/LICENSE
+ */
+import type { User } from '../../index.js';
+/**
+ * Enterprise user type with additional metadata.
+ *
+ * Extends the base `User` type with fields commonly needed
+ * for RBAC, ACL, and organizational features.
+ */
+export interface EEUser extends User {
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=user.d.ts.map

package/dist/_types/@internal_auth/dist/ee/license.d.ts

@@ -0,0 +1,171 @@
+/**
+ * License validation for EE features.
+ *
+ * Validation is delegated to the Mastra license server via `LicenseClient`
+ * (POST {MASTRA_LICENSE_URL}/validate). The client validates in the
+ * background and caches the result; the synchronous helpers in this module
+ * read the cached state:
+ *
+ * - No license key configured → EE features disabled.
+ * - Key configured, validation pending → fail open (features enabled) until
+ *   the first server response settles the state.
+ * - Server says invalid/revoked/expired → EE features disabled.
+ * - Server unreachable → fail open with a 72h grace period for previously
+ *   validated licenses.
+ *
+ * `MASTRA_LICENSE_KEY` is the primary env var; `MASTRA_EE_LICENSE` is a
+ * supported legacy alias.
+ */
+interface IMastraLogger {
+    warn(message: string): void;
+    info(message: string): void;
+    error(message: string): void;
+}
+export interface LicenseValidationSuccess {
+    valid: true;
+    /** Feature entitlements granted by the license (e.g. 'rbac', 'sso', 'fga') */
+    entitlements: string[];
+    /** Plan tier the license was issued for (e.g. 'teams', 'enterprise') */
+    planTier: string;
+    expiresAt: string | null;
+    leaseTtlSeconds: number;
+}
+export interface LicenseValidationError {
+    valid: false;
+    code: 'INVALID_KEY' | 'LICENSE_EXPIRED' | 'LICENSE_REVOKED' | 'RATE_LIMITED';
+    reason: string;
+}
+export type LicenseValidationResponse = LicenseValidationSuccess | LicenseValidationError;
+export type LicenseMode = 'enterprise' | 'open-source';
+export type LicenseStatus = 'pending' | 'valid' | 'invalid';
+export interface LicenseSnapshot {
+    mode: LicenseMode;
+    status: LicenseStatus;
+    entitlements: string[] | null;
+    planTier: string | null;
+    expiresAt: string | null;
+}
+export declare class LicenseClient {
+    private static instance;
+    private logger?;
+    private licenseKey?;
+    private licenseUrl?;
+    private mode;
+    private status;
+    private cachedResult;
+    private cacheExpiry;
+    private gracePeriodEnd;
+    private revalidationTimeout;
+    private readonly GRACE_PERIOD_MS;
+    private readonly DEFAULT_TTL_MS;
+    private constructor();
+    static getInstance(logger?: IMastraLogger): LicenseClient;
+    /**
+     * Reset the singleton so the next getInstance() re-reads env vars.
+     * Intended for tests.
+     */
+    static resetInstance(): void;
+    private readonly REQUEST_TIMEOUT_MS;
+    private fetchWithRetry;
+    private validationPromise;
+    validate(): Promise<boolean>;
+    /**
+     * Contact the server regardless of cache freshness, coalescing concurrent
+     * callers (e.g. the Mastra constructor and the auth/ee helpers both kicking
+     * off validation at startup) into a single in-flight request so the server
+     * is contacted — and the outcome logged — only once. Used directly by the
+     * background revalidation timer, which must bypass the cache check.
+     */
+    private revalidate;
+    private performValidation;
+    private scheduleRevalidation;
+    private clearCache;
+    hasFeature(featureName: string): boolean;
+    getEntitlements(): string[] | null;
+    getSnapshot(): LicenseSnapshot;
+}
+/**
+ * License information.
+ */
+export interface LicenseInfo {
+    /** Whether the license is valid */
+    valid: boolean;
+    /** License expiration date */
+    expiresAt?: Date;
+    /** Features enabled by this license */
+    features?: string[];
+    /** Organization name */
+    organization?: string;
+    /** License plan tier (e.g. 'teams', 'enterprise') */
+    tier?: string;
+}
+export interface SafeLicenseSummary {
+    valid: boolean;
+    isDevEnvironment: boolean;
+    licenseHash?: string;
+    anonymousId?: string;
+    features?: string[];
+    tier?: string;
+}
+/**
+ * Start license validation against the license server.
+ *
+ * Safe to call multiple times — the underlying client caches results and
+ * schedules its own background revalidation. Resolves to whether the license
+ * is currently considered valid.
+ */
+export declare function startLicenseValidation(): Promise<boolean>;
+/**
+ * Validate the configured license and return license information.
+ *
+ * Reflects the current server-backed validation state. The actual network
+ * validation happens in the background via `LicenseClient`, and only the
+ * configured key (env var) is ever validated — passing any other key
+ * returns invalid.
+ *
+ * @param licenseKey - Optional key to check; must match the configured key.
+ * @returns License information
+ */
+export declare function validateLicense(licenseKey?: string): LicenseInfo;
+/**
+ * Check if EE features are enabled (valid or pending server validation).
+ *
+ * @returns True if EE features should be enabled
+ */
+export declare function isLicenseValid(): boolean;
+/**
+ * @deprecated Use `isLicenseValid()` instead. This alias is provided for backward compatibility.
+ */
+export declare const isEELicenseValid: typeof isLicenseValid;
+/**
+ * Check if a specific EE feature is enabled by the license entitlements.
+ *
+ * @param feature - Feature name to check (e.g. 'rbac', 'fga', 'sso')
+ * @returns True if the feature is enabled
+ */
+export declare function isFeatureEnabled(feature: string): boolean;
+/**
+ * Get the current license information.
+ *
+ * @returns License info or null if no license key is configured
+ */
+export declare function getLicenseInfo(): LicenseInfo | null;
+export declare function getSafeLicenseSummary(): SafeLicenseSummary;
+export declare function warnIfDevEENeedsLicense(): void;
+/**
+ * Clear the license cache (useful for testing).
+ * Resets the shared client so the next check re-reads env vars.
+ */
+export declare function clearLicenseCache(): void;
+/**
+ * Check if running in a development/testing environment.
+ * In dev, EE features work without a license per the ee/LICENSE terms.
+ */
+export declare function isDevEnvironment(): boolean;
+/**
+ * Check if EE features should be active.
+ * Returns true if running in dev/test environment (always allowed) or if a valid license is present.
+ */
+export declare function isEEEnabled(): boolean;
+export {};
+//# sourceMappingURL=license.d.ts.map

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

@@ -0,0 +1,277 @@
+/**
+ * User provider interface for authentication.
+ * Enables user awareness in Studio.
+ */
+/**
+ * Base user type for authentication.
+ */
+export interface User {
+    /** Unique user identifier */
+    id: string;
+    /** User email address */
+    email?: string;
+    /** Display name */
+    name?: string;
+    /** Avatar URL */
+    avatarUrl?: string;
+}
+/**
+ * Provider interface for user awareness in Studio.
+ *
+ * Implement this interface to enable:
+ * - Current user display in header
+ * - User menu with profile info
+ * - User context in API calls
+ *
+ * @example
+ * ```typescript
+ * class MyUserProvider implements IUserProvider {
+ *   async getCurrentUser(request: Request) {
+ *     const session = await this.getSession(request);
+ *     if (!session) return null;
+ *     return this.db.getUser(session.userId);
+ *   }
+ *
+ *   async getUser(userId: string) {
+ *     return this.db.getUser(userId);
+ *   }
+ * }
+ * ```
+ */
+export interface IUserProvider<TUser extends User = User> {
+    /**
+     * Get current user from request (session cookie, token, etc.)
+     *
+     * @param request - Incoming HTTP request
+     * @returns User object or null if not authenticated
+     */
+    getCurrentUser(request: Request): Promise<TUser | null>;
+    /**
+     * Get user by ID.
+     *
+     * @param userId - User identifier
+     * @returns User object or null if not found
+     */
+    getUser(userId: string): Promise<TUser | null>;
+    /**
+     * Optional: Get multiple users by ID.
+     * Implement for efficient batch loading in user enrichment flows.
+     *
+     * @param userIds - User identifiers
+     * @returns User objects for the requested IDs (null for missing users, order preserved)
+     */
+    getUsers?(userIds: string[]): Promise<Array<TUser | null>>;
+    /**
+     * Optional: Get URL to user's profile page.
+     *
+     * @param user - User object
+     * @returns URL string to profile
+     */
+    getUserProfileUrl?(user: TUser): string;
+}
+/**
+ * SSO provider interface for EE authentication.
+ * Enables single sign-on flows in Studio.
+ */
+/**
+ * Configuration for rendering a login button.
+ */
+export interface SSOLoginConfig {
+    /** Provider identifier (e.g., 'mastra', 'auth0', 'okta') */
+    provider: string;
+    /** Button text (e.g., 'Sign in with Mastra') */
+    text: string;
+    /** Optional icon URL */
+    icon?: string;
+    /** Optional description explaining the auth requirement and what credentials to use */
+    description?: string;
+}
+/**
+ * Result of an SSO callback exchange.
+ */
+export interface SSOCallbackResult<TUser> {
+    /** Authenticated user */
+    user: TUser;
+    /** OAuth tokens */
+    tokens: {
+        /** Access token for API calls */
+        accessToken: string;
+        /** Refresh token for token renewal */
+        refreshToken?: string;
+        /** ID token with user claims */
+        idToken?: string;
+        /** Token expiration time */
+        expiresAt?: Date;
+    };
+    /**
+     * Session cookies to set in the response.
+     * Providers using encrypted cookie sessions (like AuthKit) should populate this.
+     */
+    cookies?: string[];
+}
+/**
+ * Provider interface for SSO authentication.
+ *
+ * Implement this interface to enable:
+ * - SSO login button in Studio
+ * - OAuth/OIDC redirect flows
+ * - Token exchange on callback
+ *
+ * @example
+ * ```typescript
+ * class Auth0SSOProvider implements ISSOProvider {
+ *   getLoginUrl(redirectUri: string, state: string) {
+ *     const params = new URLSearchParams({
+ *       client_id: this.clientId,
+ *       redirect_uri: redirectUri,
+ *       response_type: 'code',
+ *       scope: 'openid profile email',
+ *       state,
+ *     });
+ *     return `https://${this.domain}/authorize?${params}`;
+ *   }
+ *
+ *   async handleCallback(code: string, state: string) {
+ *     const tokens = await this.exchangeCode(code);
+ *     const user = await this.getUserInfo(tokens.accessToken);
+ *     return { user, tokens };
+ *   }
+ *
+ *   getLoginButtonConfig() {
+ *     return { provider: 'auth0', text: 'Sign in with Auth0' };
+ *   }
+ * }
+ * ```
+ */
+export interface ISSOProvider<TUser = unknown> {
+    /**
+     * Get URL to redirect user to for login.
+     *
+     * @param redirectUri - Callback URL after authentication
+     * @param state - CSRF protection state parameter
+     * @returns Full URL to redirect user to
+     */
+    getLoginUrl(redirectUri: string, state: string): string | Promise<string>;
+    /**
+     * Handle OAuth callback, exchange code for tokens and user.
+     *
+     * @param code - Authorization code from callback
+     * @param state - State parameter for CSRF validation
+     * @returns User and tokens
+     */
+    handleCallback(code: string, state: string): Promise<SSOCallbackResult<TUser>>;
+    /**
+     * Optional: Get logout URL if provider supports it.
+     *
+     * @param redirectUri - URL to redirect to after logout
+     * @param request - Optional request to extract session info (e.g., for WorkOS sid)
+     * @returns Logout URL, null if no active session, or undefined if not implemented
+     */
+    getLogoutUrl?(redirectUri: string, request?: Request): string | null | Promise<string | null>;
+    /**
+     * Get configuration for rendering login button in UI.
+     *
+     * @returns Login button configuration
+     */
+    getLoginButtonConfig(): SSOLoginConfig;
+    /**
+     * Optional: Get cookies to set during login redirect.
+     * Used by PKCE-enabled providers to store code verifier.
+     *
+     * @param redirectUri - OAuth callback URL
+     * @param state - State parameter
+     * @returns Array of Set-Cookie header values, or undefined
+     */
+    getLoginCookies?(redirectUri: string, state: string): string[] | undefined;
+}
+/**
+ * Credentials provider interface for authentication.
+ * Enables email/password sign-in and sign-up in Studio.
+ */
+/**
+ * Result of a successful credentials operation.
+ */
+export interface CredentialsResult<TUser = User> {
+    /** The authenticated user */
+    user: TUser;
+    /** Optional session token */
+    token?: string;
+    /** Optional cookies to set on the response (e.g., session cookies) */
+    cookies?: string[];
+}
+/**
+ * Provider interface for credentials-based authentication in Studio.
+ *
+ * Implement this interface to enable:
+ * - Email/password sign-in
+ * - Email/password sign-up
+ * - Password reset (optional)
+ *
+ * @example
+ * ```typescript
+ * class MyCredentialsProvider implements ICredentialsProvider {
+ *   async signIn(email: string, password: string, request: Request) {
+ *     const user = await this.validateCredentials(email, password);
+ *     if (!user) throw new Error('Invalid credentials');
+ *     return { user };
+ *   }
+ *
+ *   async signUp(email: string, password: string, name: string | undefined, request: Request) {
+ *     const user = await this.createUser({ email, password, name });
+ *     return { user };
+ *   }
+ * }
+ * ```
+ */
+export interface ICredentialsProvider<TUser extends User = User> {
+    /**
+     * Sign in with email and password.
+     *
+     * @param email - User email
+     * @param password - User password
+     * @param request - Incoming HTTP request (for setting cookies, etc.)
+     * @returns Result with user and optional token
+     * @throws Error if credentials are invalid
+     */
+    signIn(email: string, password: string, request: Request): Promise<CredentialsResult<TUser>>;
+    /**
+     * Sign up with email and password.
+     *
+     * @param email - User email
+     * @param password - User password
+     * @param name - Optional display name
+     * @param request - Incoming HTTP request (for setting cookies, etc.)
+     * @returns Result with new user and optional token
+     * @throws Error if sign up fails (e.g., email already exists)
+     */
+    signUp(email: string, password: string, name: string | undefined, request: Request): Promise<CredentialsResult<TUser>>;
+    /**
+     * Optional: Request password reset.
+     *
+     * @param email - User email
+     * @returns Promise that resolves when reset email is sent
+     */
+    requestPasswordReset?(email: string): Promise<void>;
+    /**
+     * Optional: Reset password with token.
+     *
+     * @param token - Reset token from email
+     * @param newPassword - New password
+     * @returns Promise that resolves when password is reset
+     */
+    resetPassword?(token: string, newPassword: string): Promise<void>;
+    /**
+     * Optional: Check if sign-up is enabled.
+     * Defaults to true if not implemented.
+     *
+     * Use this to disable public registration while still allowing sign-in.
+     *
+     * @returns Whether sign-up is enabled
+     */
+    isSignUpEnabled?(): boolean;
+}
+export * from './session/index.js';
+export * from './provider/index.js';
+export * from './types/index.js';
+export * from './ee/index.js';
+//# sourceMappingURL=index.d.ts.map