@mastra/core 1.6.0 → 1.7.0-alpha.0

package/dist/docs/references/docs-server-auth-auth0.md

@@ -1,222 +0,0 @@
-# MastraAuthAuth0 Class
-
-The `MastraAuthAuth0` class provides authentication for Mastra using Auth0. It verifies incoming requests using Auth0-issued JWT tokens and integrates with the Mastra server using the `auth` option.
-
-## Prerequisites
-
-This example uses Auth0 authentication. Make sure to:
-
-1. Create an Auth0 account at [auth0.com](https://auth0.com/)
-2. Set up an Application in your Auth0 Dashboard
-3. Configure an API in your Auth0 Dashboard with an identifier (audience)
-4. Configure your application's allowed callback URLs, web origins, and logout URLs
-
-```env
-AUTH0_DOMAIN=your-tenant.auth0.com
-AUTH0_AUDIENCE=your-api-identifier
-```
-
-> **Note:** You can find your domain in the Auth0 Dashboard under Applications > Settings. The audience is the identifier of your API configured in Auth0 Dashboard > APIs.
->
-> For detailed setup instructions, refer to the [Auth0 quickstarts](https://auth0.com/docs/quickstarts) for your specific platform.
-
-## Installation
-
-Before you can use the `MastraAuthAuth0` class you have to install the `@mastra/auth-auth0` package.
-
-```bash
-npm install @mastra/auth-auth0@latest
-```
-
-## Usage examples
-
-### Basic usage with environment variables
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { MastraAuthAuth0 } from "@mastra/auth-auth0";
-
-export const mastra = new Mastra({
-  server: {
-    auth: new MastraAuthAuth0(),
-  },
-});
-```
-
-### Custom configuration
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { MastraAuthAuth0 } from "@mastra/auth-auth0";
-
-export const mastra = new Mastra({
-  server: {
-    auth: new MastraAuthAuth0({
-      domain: process.env.AUTH0_DOMAIN,
-      audience: process.env.AUTH0_AUDIENCE,
-    }),
-  },
-});
-```
-
-## Configuration
-
-### User Authorization
-
-By default, `MastraAuthAuth0` allows all authenticated users who have valid Auth0 tokens for the specified audience. The token verification ensures that:
-
-1. The token is properly signed by Auth0
-2. The token is not expired
-3. The token audience matches your configured audience
-4. The token issuer matches your Auth0 domain
-
-To customize user authorization, provide a custom `authorizeUser` function:
-
-```typescript
-import { MastraAuthAuth0 } from "@mastra/auth-auth0";
-
-const auth0Provider = new MastraAuthAuth0({
-  authorizeUser: async (user) => {
-    // Custom authorization logic
-    return user.email?.endsWith("@yourcompany.com") || false;
-  },
-});
-```
-
-> **Info:** Visit [MastraAuthAuth0](https://mastra.ai/reference/auth/auth0) for all available configuration options.
-
-## Client-side setup
-
-When using Auth0 auth, you'll need to set up the Auth0 React SDK, authenticate users, and retrieve their access tokens to pass to your Mastra requests.
-
-### Setting up Auth0 React SDK
-
-First, install and configure the Auth0 React SDK in your application:
-
-```bash
-npm install @auth0/auth0-react
-```
-
-```typescript
-import React from 'react';
-import { Auth0Provider } from '@auth0/auth0-react';
-
-const Auth0ProviderWithHistory = ({ children }) => {
-  return (
-    <Auth0Provider
-      domain={process.env.REACT_APP_AUTH0_DOMAIN}
-      clientId={process.env.REACT_APP_AUTH0_CLIENT_ID}
-      authorizationParams={{
-        redirect_uri: window.location.origin,
-        audience: process.env.REACT_APP_AUTH0_AUDIENCE,
-        scope: "read:current_user update:current_user_metadata"
-      }}
-    >
-      {children}
-    </Auth0Provider>
-  );
-};
-
-export default Auth0ProviderWithHistory;
-```
-
-### Retrieving access tokens
-
-Use the Auth0 React SDK to authenticate users and retrieve their access tokens:
-
-```typescript
-import { useAuth0 } from "@auth0/auth0-react";
-
-export const useAuth0Token = () => {
-  const { getAccessTokenSilently } = useAuth0();
-
-  const getAccessToken = async () => {
-    const token = await getAccessTokenSilently();
-    return token;
-  };
-
-  return { getAccessToken };
-};
-```
-
-> **Note:** Refer to the [Auth0 React SDK documentation](https://auth0.com/docs/libraries/auth0-react) for more authentication methods and configuration options.
-
-## Configuring `MastraClient`
-
-When `auth` is enabled, all requests made with `MastraClient` must include a valid Auth0 access token in the `Authorization` header:
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-export const createMastraClient = (accessToken: string) => {
-  return new MastraClient({
-    baseUrl: "https://<mastra-api-url>",
-    headers: {
-      Authorization: `Bearer ${accessToken}`,
-    },
-  });
-};
-```
-
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
->
-> Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
-
-### Making authenticated requests
-
-Once `MastraClient` is configured with the Auth0 access token, you can send authenticated requests:
-
-**React**:
-
-```tsx
-import React, { useState } from 'react';
-import { useAuth0 } from '@auth0/auth0-react';
-import { MastraClient } from '@mastra/client-js';
-
-export const MastraApiTest = () => {
-  const { getAccessTokenSilently } = useAuth0();
-  const [result, setResult] = useState(null);
-
-  const callMastraApi = async () => {
-    const token = await getAccessTokenSilently();
-
-    const mastra = new MastraClient({
-      baseUrl: "http://localhost:4111",
-      headers: {
-        Authorization: `Bearer ${token}`
-      }
-    });
-
-    const weatherAgent = mastra.getAgent("weatherAgent");
-    const response = await weatherAgent.generate("What's the weather like in New York");
-
-    setResult(response.text);
-  };
-
-  return (
-    <div>
-      <button onClick={callMastraApi}>
-        Test Mastra API
-      </button>
-
-      {result && (
-        <div className="result">
-          <h6>Result:</h6>
-          <pre>{result}</pre>
-        </div>
-      )}
-    </div>
-  );
-};
-```
-
-**cURL**:
-
-```bash
-curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <your-auth0-access-token>" \
-  -d '{
-    "messages": "Weather in London"
-  }'
-```

package/dist/docs/references/docs-server-auth-clerk.md

@@ -1,132 +0,0 @@
-# MastraAuthClerk Class
-
-The `MastraAuthClerk` class provides authentication for Mastra using Clerk. It verifies incoming requests using Clerk's authentication system and integrates with the Mastra server using the `auth` option.
-
-## Prerequisites
-
-This example uses Clerk authentication. Make sure to add your Clerk credentials to your `.env` file and ensure your Clerk project is properly configured.
-
-```env
-CLERK_PUBLISHABLE_KEY=pk_test_...
-CLERK_SECRET_KEY=sk_test_...
-CLERK_JWKS_URI=https://your-clerk-domain.clerk.accounts.dev/.well-known/jwks.json
-```
-
-> **Note:** You can find these keys in your Clerk Dashboard under "API Keys".
-
-## Installation
-
-Before you can use the `MastraAuthClerk` class you have to install the `@mastra/auth-clerk` package.
-
-```bash
-npm install @mastra/auth-clerk@latest
-```
-
-## Usage example
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { MastraAuthClerk } from "@mastra/auth-clerk";
-
-export const mastra = new Mastra({
-  server: {
-    auth: new MastraAuthClerk({
-      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
-      secretKey: process.env.CLERK_SECRET_KEY,
-      jwksUri: process.env.CLERK_JWKS_URI,
-    }),
-  },
-});
-```
-
-> **Info:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
->
-> Visit [MastraAuthClerk](https://mastra.ai/reference/auth/clerk) for all available configuration options.
-
-## Client-side setup
-
-When using Clerk auth, you'll need to retrieve the access token from Clerk on the client side and pass it to your Mastra requests.
-
-### Retrieving the access token
-
-Use the Clerk React hooks to authenticate users and retrieve their access token:
-
-```typescript
-import { useAuth } from "@clerk/nextjs";
-
-export const useClerkAuth = () => {
-  const { getToken } = useAuth();
-
-  const getAccessToken = async () => {
-    const token = await getToken();
-    return token;
-  };
-
-  return { getAccessToken };
-};
-```
-
-> **Info:** Refer to the [Clerk documentation](https://clerk.com/docs) for more information.
-
-## Configuring `MastraClient`
-
-When `auth` is enabled, all requests made with `MastraClient` must include a valid Clerk access token in the `Authorization` header:
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-export const mastraClient = new MastraClient({
-  baseUrl: "https://<mastra-api-url>",
-  headers: {
-    Authorization: `Bearer ${accessToken}`,
-  },
-});
-```
-
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
->
-> Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
-
-### Making authenticated requests
-
-Once `MastraClient` is configured with the Clerk access token, you can send authenticated requests:
-
-**React**:
-
-```tsx
-"use client";
-
-import { useAuth } from "@clerk/nextjs";
-import { MastraClient } from "@mastra/client-js";
-
-export const TestAgent = () => {
-  const { getToken } = useAuth();
-
-  async function handleClick() {
-    const token = await getToken();
-
-    const client = new MastraClient({
-      baseUrl: "http://localhost:4111",
-      headers: token ? { Authorization: `Bearer ${token}` } : undefined,
-    });
-
-    const weatherAgent = client.getAgent("weatherAgent");
-    const response = await weatherAgent.generate("What's the weather like in New York");
-
-    console.log({ response });
-  }
-
-  return <button onClick={handleClick}>Test Agent</button>;
-};
-```
-
-**cURL**:
-
-```bash
-curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <your-clerk-access-token>" \
-  -d '{
-    "messages": "Weather in London"
-  }'
-```

package/dist/docs/references/docs-server-auth-composite-auth.md

@@ -1,234 +0,0 @@
-# CompositeAuth Class
-
-The `CompositeAuth` class allows you to combine multiple authentication providers into a single auth handler. It tries each provider in order until one succeeds.
-
-## Use Cases
-
-- Support both API keys and OAuth tokens
-- Migrate between auth providers without breaking existing clients
-- Allow multiple identity providers (e.g., Clerk for web, API keys for integrations)
-- Gradual rollout of new authentication methods
-
-## Installation
-
-CompositeAuth is included in `@mastra/core`, no additional packages required.
-
-```typescript
-import { CompositeAuth } from '@mastra/core/server';
-```
-
-## Usage Example
-
-Combine SimpleAuth (for API keys) with Clerk (for user sessions):
-
-```typescript
-import { Mastra } from '@mastra/core';
-import { CompositeAuth, SimpleAuth } from '@mastra/core/server';
-import { MastraAuthClerk } from '@mastra/auth-clerk';
-
-// API key users
-type ApiKeyUser = {
-  id: string;
-  name: string;
-  type: 'api-key';
-};
-
-const apiKeyAuth = new SimpleAuth<ApiKeyUser>({
-  tokens: {
-    'sk-integration-key-123': {
-      id: 'integration-1',
-      name: 'CI/CD Pipeline',
-      type: 'api-key',
-    },
-  },
-});
-
-// Clerk users (from web app)
-const clerkAuth = new MastraAuthClerk({
-  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
-  secretKey: process.env.CLERK_SECRET_KEY,
-  jwksUri: process.env.CLERK_JWKS_URI,
-});
-
-export const mastra = new Mastra({
-  server: {
-    auth: new CompositeAuth([apiKeyAuth, clerkAuth]),
-  },
-});
-```
-
-## How It Works
-
-When a request comes in, CompositeAuth:
-
-1. Extracts the token from the `Authorization` header
-2. Tries each provider's `authenticateToken()` method in order
-3. Returns the user from the first provider that succeeds
-4. Returns `null` (401 Unauthorized) if all providers fail
-
-For authorization, it calls each provider's `authorizeUser()` method until one returns `true`.
-
-```typescript
-// Pseudocode of CompositeAuth behavior
-async authenticateToken(token, request) {
-  for (const provider of this.providers) {
-    const user = await provider.authenticateToken(token, request);
-    if (user) return user;  // First match wins
-  }
-  return null;  // All providers failed
-}
-```
-
-## Provider Order
-
-The order of providers matters. Place the most common authentication method first for better performance:
-
-```typescript
-// If most requests use Clerk, put it first
-new CompositeAuth([
-  clerkAuth,      // Checked first (most common)
-  apiKeyAuth,     // Checked second (less common)
-]);
-
-// If most requests use API keys, put it first
-new CompositeAuth([
-  apiKeyAuth,     // Checked first (most common)
-  clerkAuth,      // Checked second (less common)
-]);
-```
-
-## Multiple OAuth Providers
-
-Support users from different identity providers:
-
-```typescript
-import { CompositeAuth } from '@mastra/core/server';
-import { MastraAuthClerk } from '@mastra/auth-clerk';
-import { MastraAuthAuth0 } from '@mastra/auth-auth0';
-
-const clerkAuth = new MastraAuthClerk({
-  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
-  secretKey: process.env.CLERK_SECRET_KEY,
-  jwksUri: process.env.CLERK_JWKS_URI,
-});
-
-const auth0Auth = new MastraAuthAuth0({
-  domain: process.env.AUTH0_DOMAIN,
-  audience: process.env.AUTH0_AUDIENCE,
-});
-
-export const mastra = new Mastra({
-  server: {
-    auth: new CompositeAuth([clerkAuth, auth0Auth]),
-  },
-});
-```
-
-## Migration Example
-
-Migrate from JWT to Clerk while maintaining backwards compatibility:
-
-```typescript
-import { CompositeAuth } from '@mastra/core/server';
-import { MastraJwtAuth } from '@mastra/auth';
-import { MastraAuthClerk } from '@mastra/auth-clerk';
-
-// Legacy JWT auth (existing clients)
-const legacyAuth = new MastraJwtAuth({
-  secret: process.env.JWT_SECRET,
-});
-
-// New Clerk auth (new clients)
-const clerkAuth = new MastraAuthClerk({
-  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
-  secretKey: process.env.CLERK_SECRET_KEY,
-  jwksUri: process.env.CLERK_JWKS_URI,
-});
-
-// Support both during migration
-export const mastra = new Mastra({
-  server: {
-    auth: new CompositeAuth([
-      clerkAuth,    // New auth method (preferred)
-      legacyAuth,   // Legacy support
-    ]),
-  },
-});
-```
-
-## With Custom Providers
-
-Combine built-in providers with custom implementations:
-
-```typescript
-import { CompositeAuth, SimpleAuth } from '@mastra/core/server';
-import { MyCustomAuth } from './my-custom-auth';
-
-const apiKeyAuth = new SimpleAuth({
-  tokens: {
-    'sk-key-123': { id: 'user-1', name: 'API User' },
-  },
-});
-
-const customAuth = new MyCustomAuth({
-  apiUrl: process.env.CUSTOM_AUTH_URL,
-});
-
-export const mastra = new Mastra({
-  server: {
-    auth: new CompositeAuth([apiKeyAuth, customAuth]),
-  },
-});
-```
-
-## Error Handling
-
-CompositeAuth silently catches errors from individual providers and moves to the next one. This prevents one failing provider from blocking authentication:
-
-```typescript
-// If clerkAuth throws an error, apiKeyAuth still gets tried
-new CompositeAuth([clerkAuth, apiKeyAuth]);
-```
-
-To debug authentication issues, add logging to your custom providers or check individual provider configurations.
-
-## Limitations
-
-- All providers share the same token from the `Authorization` header
-- User types may differ between providers (use discriminated unions if needed)
-- No built-in way to identify which provider authenticated a request
-
-### Handling Different User Types
-
-When providers return different user types, use a discriminated union:
-
-```typescript
-type ApiKeyUser = {
-  type: 'api-key';
-  id: string;
-  name: string;
-};
-
-type ClerkUser = {
-  type: 'clerk';
-  sub: string;
-  email: string;
-};
-
-type User = ApiKeyUser | ClerkUser;
-
-// In your application code
-function handleUser(user: User) {
-  if (user.type === 'api-key') {
-    console.log('API key user:', user.name);
-  } else {
-    console.log('Clerk user:', user.email);
-  }
-}
-```
-
-## Related
-
-- [Auth Overview](https://mastra.ai/docs/server/auth) - Authentication concepts
-- [Simple Auth](https://mastra.ai/docs/server/auth/simple-auth) - Token-to-user mapping
-- [Custom Auth Provider](https://mastra.ai/docs/server/auth/custom-auth-provider) - Build your own provider