npm - @mastra/core - Versions diffs - 1.6.0 → 1.7.0-alpha.0 - Mend

@mastra/core 1.6.0 → 1.7.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (452) hide show

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

@@ -1,272 +0,0 @@
-# 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.
-```typescript
-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 DELETED Viewed

@@ -1,110 +0,0 @@
-# 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 DELETED Viewed

@@ -1,178 +0,0 @@
-# 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 DELETED Viewed

@@ -1,117 +0,0 @@
-# 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"
-  }'
-```