@mastra/core 1.7.0 → 1.8.0

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

@@ -0,0 +1,272 @@
+# MastraAuthFirebase Class
+
+The `MastraAuthFirebase` class provides authentication for Mastra using Firebase Authentication. It verifies incoming requests using Firebase ID tokens and integrates with the Mastra server using the `auth` option.
+
+## Prerequisites
+
+This example uses Firebase Authentication. Make sure to:
+
+1. Create a Firebase project in the [Firebase Console](https://console.firebase.google.com/)
+2. Enable Authentication and configure your preferred sign-in methods (Google, Email/Password, etc.)
+3. Generate a service account key from Project Settings > Service Accounts
+4. Download the service account JSON file
+
+```env
+FIREBASE_SERVICE_ACCOUNT=/path/to/your/service-account-key.json
+FIRESTORE_DATABASE_ID=(default)
+# Alternative environment variable names:
+# FIREBASE_DATABASE_ID=(default)
+```
+
+> **Note:** Store your service account JSON file securely and never commit it to version control.
+
+## Installation
+
+Before you can use the `MastraAuthFirebase` class you have to install the `@mastra/auth-firebase` package.
+
+```bash
+npm install @mastra/auth-firebase@latest
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+If you set the required environment variables (`FIREBASE_SERVICE_ACCOUNT` and `FIRESTORE_DATABASE_ID`), you can initialize `MastraAuthFirebase` without any constructor arguments. The class will automatically read these environment variables as configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+// Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthFirebase(),
+  },
+})
+```
+
+### Custom configuration
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthFirebase({
+      serviceAccount: '/path/to/service-account.json',
+      databaseId: 'your-database-id',
+    }),
+  },
+})
+```
+
+## Configuration
+
+The `MastraAuthFirebase` class can be configured through constructor options or environment variables.
+
+### Environment Variables
+
+- `FIREBASE_SERVICE_ACCOUNT`: Path to Firebase service account JSON file
+- `FIRESTORE_DATABASE_ID` or `FIREBASE_DATABASE_ID`: Firestore database ID
+
+> **Note:** When constructor options are not provided, the class automatically reads these environment variables. This means you can simply call `new MastraAuthFirebase()` without any arguments if your environment variables are properly configured.
+
+### User Authorization
+
+By default, `MastraAuthFirebase` uses Firestore to manage user access. It expects a collection named `user_access` with documents keyed by user UIDs. The presence of a document in this collection determines whether a user is authorized.
+
+```text
+user_access/
+  {user_uid_1}/     // Document exists = user authorized
+  {user_uid_2}/     // Document exists = user authorized
+```
+
+To customize user authorization, provide a custom `authorizeUser` function:
+
+```typescript
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+const firebaseAuth = new MastraAuthFirebase({
+  authorizeUser: async user => {
+    // Custom authorization logic
+    return user.email?.endsWith('@yourcompany.com') || false
+  },
+})
+```
+
+> **Info:** Visit [MastraAuthFirebase](https://mastra.ai/reference/auth/firebase) for all available configuration options.
+
+## Client-side setup
+
+When using Firebase auth, you'll need to initialize Firebase on the client side, authenticate users, and retrieve their ID tokens to pass to your Mastra requests.
+
+### Setting up Firebase on the client
+
+First, initialize Firebase in your client application:
+
+```typescript
+import { initializeApp } from 'firebase/app'
+import { getAuth, GoogleAuthProvider } from 'firebase/auth'
+
+const firebaseConfig = {
+  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
+  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
+  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
+}
+
+const app = initializeApp(firebaseConfig)
+export const auth = getAuth(app)
+export const googleProvider = new GoogleAuthProvider()
+```
+
+### Authenticating users and retrieving tokens
+
+Use Firebase authentication to sign in users and retrieve their ID tokens:
+
+```typescript
+import { signInWithPopup, signOut, User } from 'firebase/auth'
+import { auth, googleProvider } from './firebase'
+
+export const signInWithGoogle = async () => {
+  try {
+    const result = await signInWithPopup(auth, googleProvider)
+    return result.user
+  } catch (error) {
+    console.error('Error signing in:', error)
+    throw error
+  }
+}
+
+export const getIdToken = async (user: User) => {
+  try {
+    const idToken = await user.getIdToken()
+    return idToken
+  } catch (error) {
+    console.error('Error getting ID token:', error)
+    throw error
+  }
+}
+
+export const signOutUser = async () => {
+  try {
+    await signOut(auth)
+  } catch (error) {
+    console.error('Error signing out:', error)
+    throw error
+  }
+}
+```
+
+> **Note:** Refer to the [Firebase documentation](https://firebase.google.com/docs/auth) for other authentication methods like email/password, phone authentication, and more.
+
+## Configuring `MastraClient`
+
+When `auth` is enabled, all requests made with `MastraClient` must include a valid Firebase ID token in the `Authorization` header:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const createMastraClient = (idToken: string) => {
+  return new MastraClient({
+    baseUrl: 'https://<mastra-api-url>',
+    headers: {
+      Authorization: `Bearer ${idToken}`,
+    },
+  })
+}
+```
+
+> **Info:** The ID 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 Firebase ID token, you can send authenticated requests:
+
+**React**:
+
+```tsx
+'use client'
+
+import { useAuthState } from 'react-firebase-hooks/auth'
+import { MastraClient } from '@mastra/client-js'
+import { auth } from '../lib/firebase'
+import { getIdToken } from '../lib/auth'
+
+export const TestAgent = () => {
+  const [user] = useAuthState(auth)
+
+  async function handleClick() {
+    if (!user) return
+
+    const token = await getIdToken(user)
+    const client = createMastraClient(token)
+
+    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} disabled={!user}>
+      Test Agent
+    </button>
+  )
+}
+```
+
+**Node.js**:
+
+```typescript
+const express = require('express')
+const admin = require('firebase-admin')
+const { MastraClient } = require('@mastra/client-js')
+
+// Initialize Firebase Admin
+admin.initializeApp({
+  credential: admin.credential.cert({
+    // Your service account credentials
+  }),
+})
+
+const app = express()
+app.use(express.json())
+
+app.post('/generate', async (req, res) => {
+  try {
+    const { idToken } = req.body
+
+    // Verify the token
+    await admin.auth().verifyIdToken(idToken)
+
+    const mastra = new MastraClient({
+      baseUrl: 'http://localhost:4111',
+      headers: {
+        Authorization: `Bearer ${idToken}`,
+      },
+    })
+
+    const weatherAgent = mastra.getAgent('weatherAgent')
+    const response = await weatherAgent.generate("What's the weather like in Nairobi")
+
+    res.json({ response: response.text })
+  } catch (error) {
+    res.status(401).json({ error: 'Unauthorized' })
+  }
+})
+```
+
+**cURL**:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-firebase-id-token>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```

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

@@ -0,0 +1,110 @@
+# MastraJwtAuth Class
+
+The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `auth` option.
+
+## Installation
+
+Before you can use the `MastraJwtAuth` class you have to install the `@mastra/auth` package.
+
+**npm**:
+
+```bash
+npm install @mastra/auth@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/auth@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/auth@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/auth@latest
+```
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraJwtAuth } from '@mastra/auth'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraJwtAuth({
+      secret: process.env.MASTRA_JWT_SECRET,
+    }),
+  },
+})
+```
+
+> **Info:** Visit [MastraJwtAuth](https://mastra.ai/reference/auth/jwt) for all available configuration options.
+
+## Configuring `MastraClient`
+
+When `auth` is enabled, all requests made with `MastraClient` must include a valid JWT in the `Authorization` header:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const mastraClient = new MastraClient({
+  baseUrl: 'https://<mastra-api-url>',
+  headers: {
+    Authorization: `Bearer ${process.env.MASTRA_JWT_TOKEN}`,
+  },
+})
+```
+
+> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured, you can send authenticated requests from your frontend application, or use `curl` for quick local testing:
+
+**React**:
+
+```tsx
+import { mastraClient } from '../../lib/mastra-client'
+
+export const TestAgent = () => {
+  async function handleClick() {
+    const agent = mastraClient.getAgent('weatherAgent')
+
+    const response = await agent.generate('Weather in London')
+
+    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-jwt>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```
+
+## Creating a JWT
+
+To authenticate requests to your Mastra server, you'll need a valid JSON Web Token (JWT) signed with your `MASTRA_JWT_SECRET`.
+
+The easiest way to generate one is using [jwt.io](https://www.jwt.io/):
+
+1. Select **JWT Encoder**.
+2. Scroll down to the **Sign JWT: Secret** section.
+3. Enter your secret (for example: `supersecretdevkeythatishs256safe!`).
+4. Click **Generate example** to create a valid JWT.
+5. Copy the generated token and set it as `MASTRA_JWT_TOKEN` in your `.env` file.

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

@@ -0,0 +1,180 @@
+# SimpleAuth Class
+
+The `SimpleAuth` class provides token-based authentication using a simple token-to-user mapping. It's included in `@mastra/core/server` and is useful for development, testing, and simple API key authentication scenarios.
+
+## Use Cases
+
+- Local development and testing
+- Simple API key authentication
+- Prototyping before integrating a full identity provider
+- Internal services with static tokens
+
+## Installation
+
+SimpleAuth is included in `@mastra/core`, no additional packages required.
+
+```typescript
+import { SimpleAuth } from '@mastra/core/server'
+```
+
+## Usage Example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { SimpleAuth } from '@mastra/core/server'
+
+// Define your user type
+type User = {
+  id: string
+  name: string
+  role: 'admin' | 'user'
+}
+
+export const mastra = new Mastra({
+  server: {
+    auth: new SimpleAuth<User>({
+      tokens: {
+        'sk-admin-token-123': {
+          id: 'user-1',
+          name: 'Admin User',
+          role: 'admin',
+        },
+        'sk-user-token-456': {
+          id: 'user-2',
+          name: 'Regular User',
+          role: 'user',
+        },
+      },
+    }),
+  },
+})
+```
+
+## Configuration Options
+
+| Option          | Type                         | Required | Description                            |
+| --------------- | ---------------------------- | -------- | -------------------------------------- |
+| `tokens`        | `Record<string, TUser>`      | Yes      | Map of tokens to user objects          |
+| `headers`       | `string \| string[]`         | No       | Additional headers to check for tokens |
+| `name`          | `string`                     | No       | Provider name for logging              |
+| `authorizeUser` | `(user, request) => boolean` | No       | Custom authorization function          |
+| `protected`     | `(RegExp \| string)[]`       | No       | Paths that require authentication      |
+| `public`        | `(RegExp \| string)[]`       | No       | Paths that bypass authentication       |
+
+### Default Headers
+
+SimpleAuth checks these headers by default:
+
+- `Authorization` (with or without `Bearer` prefix)
+- `X-Playground-Access`
+
+Add custom headers using the `headers` option:
+
+```typescript
+new SimpleAuth({
+  tokens: {
+    /* ... */
+  },
+  headers: ['X-API-Key', 'X-Custom-Auth'],
+})
+```
+
+## Making Authenticated Requests
+
+Include your token in the `Authorization` header:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/myAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk-admin-token-123" \
+  -d '{"messages": "Hello"}'
+```
+
+Or without the `Bearer` prefix:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/myAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: sk-admin-token-123" \
+  -d '{"messages": "Hello"}'
+```
+
+## Custom Authorization
+
+Add role-based or custom authorization logic:
+
+```typescript
+new SimpleAuth<User>({
+  tokens: {
+    'sk-admin-token': { id: '1', name: 'Admin', role: 'admin' },
+    'sk-user-token': { id: '2', name: 'User', role: 'user' },
+  },
+  authorizeUser: (user, request) => {
+    // Only admins can access /admin routes
+    if (request.url.includes('/admin')) {
+      return user.role === 'admin'
+    }
+    return true
+  },
+})
+```
+
+## Environment Variables
+
+For production-like setups, load tokens from environment variables:
+
+```typescript
+const tokens: Record<string, User> = {}
+
+// Load from environment
+const adminToken = process.env.ADMIN_API_KEY
+if (adminToken) {
+  tokens[adminToken] = { id: 'admin', name: 'Admin', role: 'admin' }
+}
+
+const userToken = process.env.USER_API_KEY
+if (userToken) {
+  tokens[userToken] = { id: 'user', name: 'User', role: 'user' }
+}
+
+export const mastra = new Mastra({
+  server: {
+    auth: new SimpleAuth({ tokens }),
+  },
+})
+```
+
+## With MastraClient
+
+Configure the client with your token:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: 'http://localhost:4111',
+  headers: {
+    Authorization: 'Bearer sk-admin-token-123',
+  },
+})
+
+const agent = client.getAgent('myAgent')
+const response = await agent.generate('Hello')
+```
+
+## Limitations
+
+SimpleAuth is designed for simplicity, not production security:
+
+- Tokens are stored in memory
+- No token expiration or refresh
+- No cryptographic verification
+- All tokens must be known at startup
+
+For production applications, consider using [JWT](https://mastra.ai/docs/server/auth/jwt), [Clerk](https://mastra.ai/docs/server/auth/clerk), [Auth0](https://mastra.ai/docs/server/auth/auth0), or another identity provider.
+
+## Related
+
+- [Auth Overview](https://mastra.ai/docs/server/auth) - Authentication concepts
+- [JWT Auth](https://mastra.ai/docs/server/auth/jwt) - JSON Web Token authentication
+- [Custom Auth Provider](https://mastra.ai/docs/server/auth/custom-auth-provider) - Build your own provider

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

@@ -0,0 +1,117 @@
+# MastraAuthSupabase Class
+
+The `MastraAuthSupabase` class provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the `auth` option.
+
+## Prerequisites
+
+This example uses Supabase Auth. Make sure to add your Supabase credentials to your `.env` file and ensure your Supabase project is properly configured.
+
+```env
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your-anon-key
+```
+
+> **Note:** Review your Supabase Row Level Security (RLS) settings to ensure proper data access controls.
+
+## Installation
+
+Before you can use the `MastraAuthSupabase` class you have to install the `@mastra/auth-supabase` package.
+
+```bash
+npm install @mastra/auth-supabase@latest
+```
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthSupabase } from '@mastra/auth-supabase'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthSupabase({
+      url: process.env.SUPABASE_URL,
+      anonKey: process.env.SUPABASE_ANON_KEY,
+    }),
+  },
+})
+```
+
+> **Info:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+>
+> Visit [MastraAuthSupabase](https://mastra.ai/reference/auth/supabase) for all available configuration options.
+
+## Client-side setup
+
+When using Supabase auth, you'll need to retrieve the access token from Supabase on the client side and pass it to your Mastra requests.
+
+### Retrieving the access token
+
+Use the Supabase client to authenticate users and retrieve their access token:
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient('<supabase-url>', '<supabase-key>')
+
+const authTokenResponse = await supabase.auth.signInWithPassword({
+  email: "<user's email>",
+  password: "<user's password>",
+})
+
+const accessToken = authTokenResponse.data?.session?.access_token
+```
+
+> **Note:** Refer to the [Supabase documentation](https://supabase.com/docs/guides/auth) for other authentication methods like OAuth, magic links, and more.
+
+## Configuring `MastraClient`
+
+When `auth` is enabled, all requests made with `MastraClient` must include a valid Supabase 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 Supabase access token, you can send authenticated requests:
+
+**React**:
+
+```tsx
+import { mastraClient } from '../../lib/mastra-client'
+
+export const TestAgent = () => {
+  async function handleClick() {
+    const agent = mastraClient.getAgent('weatherAgent')
+
+    const response = await agent.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-supabase-access-token>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```