@mastra/core 1.6.0 → 1.7.0-alpha.0

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

@@ -1,73 +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.
-
-## Usage example
-
-```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,
-    }),
-  },
-});
-```
-
-> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`AUTH0_DOMAIN` and `AUTH0_AUDIENCE`) set. In that case, simply use `new MastraAuthAuth0()` without any arguments.
-
-## Constructor parameters
-
-**domain?:** (`string`): Your Auth0 domain (e.g., your-tenant.auth0.com). This is used to verify JWT tokens issued by your Auth0 tenant. (Default: `process.env.AUTH0_DOMAIN`)
-
-**audience?:** (`string`): Your Auth0 API identifier/audience. This ensures tokens are intended for your specific API. (Default: `process.env.AUTH0_AUDIENCE`)
-
-**name?:** (`string`): Custom name for the auth provider instance. (Default: `"auth0"`)
-
-**authorizeUser?:** (`(user: Auth0User) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users with valid tokens.
-
-## Environment Variables
-
-The following environment variables are automatically used when constructor options are not provided:
-
-**AUTH0\_DOMAIN?:** (`string`): Your Auth0 domain. Can be found in your Auth0 Dashboard under Applications > Settings.
-
-**AUTH0\_AUDIENCE?:** (`string`): Your Auth0 API identifier. This is the identifier you set when creating an API in your Auth0 Dashboard.
-
-## Default Authorization Behavior
-
-By default, `MastraAuthAuth0` validates Auth0 JWT tokens and allows access to all authenticated users:
-
-1. **Token Verification**: The JWT token is verified using Auth0's public keys (JWKS)
-2. **Signature Validation**: Ensures the token was signed by your Auth0 tenant
-3. **Expiration Check**: Verifies the token has not expired
-4. **Audience Validation**: Confirms the token was issued for your specific API (audience)
-5. **Issuer Validation**: Ensures the token was issued by your Auth0 domain
-
-If all validations pass, the user is considered authorized. To implement custom authorization logic (e.g., role-based access control), provide a custom `authorizeUser` function.
-
-## Auth0 User Type
-
-The `Auth0User` type used in the `authorizeUser` function corresponds to the decoded JWT token payload, which typically includes:
-
-- `sub`: The user's unique identifier (subject)
-- `email`: The user's email address (if included in token)
-- `email_verified`: Whether the email is verified
-- `name`: The user's display name (if available)
-- `picture`: URL to the user's profile picture (if available)
-- `iss`: Token issuer (your Auth0 domain)
-- `aud`: Token audience (your API identifier)
-- `iat`: Token issued at timestamp
-- `exp`: Token expiration timestamp
-- `scope`: Granted scopes for the token
-- Custom claims and app metadata configured in your Auth0 tenant
-
-The exact properties available depend on your Auth0 configuration, scopes requested, and any custom claims you've configured.
-
-## Related
-
-[MastraAuthAuth0 Class](https://mastra.ai/docs/server/auth/auth0)

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

@@ -1,36 +0,0 @@
-# MastraAuthClerk Class
-
-The `MastraAuthClerk` class provides authentication for Mastra applications using Clerk. It verifies incoming requests with Clerk-issued JWT tokens and integrates with the Mastra server using the `auth` option.
-
-## Usage example
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { MastraAuthClerk } from "@mastra/auth-clerk";
-
-export const mastra = new Mastra({
-  server: {
-    auth: new MastraAuthClerk({
-      jwksUri: process.env.CLERK_JWKS_URI,
-      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
-      secretKey: process.env.CLERK_SECRET_KEY,
-    }),
-  },
-});
-```
-
-## Constructor parameters
-
-**publishableKey?:** (`string`): Your Clerk publishable key. Can be found in your Clerk Dashboard under API Keys. (Default: `process.env.CLERK_PUBLISHABLE_KEY`)
-
-**secretKey?:** (`string`): Your Clerk secret key. Used for server-side authentication and token verification. (Default: `process.env.CLERK_SECRET_KEY`)
-
-**jwksUri?:** (`string`): The JWKS URI from your Clerk application. Used to verify JWT signatures. (Default: `process.env.CLERK_JWKS_URI`)
-
-**name?:** (`string`): Custom name for the auth provider instance.
-
-**authorizeUser?:** (`(user: User, request: HonoRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users.
-
-## Related
-
-[MastraAuthClerk Class](https://mastra.ai/docs/server/auth/clerk)

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

@@ -1,80 +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.
-
-## Usage examples
-
-### Basic usage with environment variables
-
-```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-key.json",
-      databaseId: "your-database-id",
-    }),
-  },
-});
-```
-
-## Constructor parameters
-
-**serviceAccount?:** (`string`): Path to the Firebase service account JSON file. This file contains the credentials needed to verify Firebase ID tokens on the server side. (Default: `process.env.FIREBASE_SERVICE_ACCOUNT`)
-
-**databaseId?:** (`string`): The Firestore database ID to use. Typically '(default)' for the default database. (Default: `process.env.FIRESTORE_DATABASE_ID || process.env.FIREBASE_DATABASE_ID`)
-
-**name?:** (`string`): Custom name for the auth provider instance. (Default: `"firebase"`)
-
-**authorizeUser?:** (`(user: FirebaseUser) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks for the presence of a document in the 'user\_access' collection keyed by the user's UID.
-
-## Environment Variables
-
-The following environment variables are automatically used when constructor options are not provided:
-
-**FIREBASE\_SERVICE\_ACCOUNT?:** (`string`): Path to Firebase service account JSON file. Used if serviceAccount option is not provided.
-
-**FIRESTORE\_DATABASE\_ID?:** (`string`): Firestore database ID. Primary environment variable for database configuration.
-
-**FIREBASE\_DATABASE\_ID?:** (`string`): Alternative environment variable for Firestore database ID. Used if FIRESTORE\_DATABASE\_ID is not set.
-
-## Default Authorization Behavior
-
-By default, `MastraAuthFirebase` uses Firestore to manage user access:
-
-1. After successfully verifying a Firebase ID token, the `authorizeUser` method is called
-2. It checks for the existence of a document in the `user_access` collection with the user's UID as the document ID
-3. If the document exists, the user is authorized; otherwise, access is denied
-4. The Firestore database used is determined by the `databaseId` parameter or environment variables
-
-## Firebase User Type
-
-The `FirebaseUser` type used in the `authorizeUser` function corresponds to Firebase's `DecodedIdToken` interface, which includes:
-
-- `uid`: The user's unique identifier
-- `email`: The user's email address (if available)
-- `email_verified`: Whether the email is verified
-- `name`: The user's display name (if available)
-- `picture`: URL to the user's profile picture (if available)
-- `auth_time`: When the user authenticated
-- And other standard JWT claims
-
-## Related
-
-[MastraAuthFirebase Class](https://mastra.ai/docs/server/auth/firebase)

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

@@ -1,26 +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.
-
-## Usage example
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { MastraJwtAuth } from "@mastra/auth";
-
-export const mastra = new Mastra({
-  server: {
-    auth: new MastraJwtAuth({
-      secret: "<your-secret>",
-    }),
-  },
-});
-```
-
-## Constructor parameters
-
-**secret:** (`string`): A unique string used to sign and verify JSON Web Tokens (JWTs) for authenticating incoming requests.
-
-## Related
-
-[MastraJwtAuth](https://mastra.ai/docs/server/auth/jwt)

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

@@ -1,33 +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.
-
-## 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,
-    }),
-  },
-});
-```
-
-## Constructor parameters
-
-**url?:** (`string`): The URL of your Supabase project. Can be found in your Supabase project settings. (Default: `process.env.SUPABASE_URL`)
-
-**anonKey?:** (`string`): The anonymous/public key for your Supabase project. Used for client-side authentication. (Default: `process.env.SUPABASE_ANON_KEY`)
-
-**name?:** (`string`): Custom name for the auth provider instance.
-
-**authorizeUser?:** (`(user: User, request: HoneRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks the 'isAdmin' column in the 'users' table.
-
-## Related
-
-[MastraAuthSupabase](https://mastra.ai/docs/server/auth/supabase)

package/dist/docs/references/reference-auth-workos.md

@@ -1,84 +0,0 @@
-# MastraAuthWorkos Class
-
-The `MastraAuthWorkos` class provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `auth` option.
-
-## Usage example
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { MastraAuthWorkos } from "@mastra/auth-workos";
-
-export const mastra = new Mastra({
-  server: {
-    auth: new MastraAuthWorkos({
-      apiKey: process.env.WORKOS_API_KEY,
-      clientId: process.env.WORKOS_CLIENT_ID,
-    }),
-  },
-});
-```
-
-> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`WORKOS_API_KEY` and `WORKOS_CLIENT_ID`) set. In that case, simply use `new MastraAuthWorkos()` without any arguments.
-
-## Constructor parameters
-
-**apiKey?:** (`string`): Your WorkOS API key. This is used to authenticate with the WorkOS API for user verification and organization management. (Default: `process.env.WORKOS_API_KEY`)
-
-**clientId?:** (`string`): Your WorkOS Client ID. This identifies your application when exchanging authorization codes for access tokens. (Default: `process.env.WORKOS_CLIENT_ID`)
-
-**name?:** (`string`): Custom name for the auth provider instance. (Default: `"workos"`)
-
-**authorizeUser?:** (`(user: WorkosUser) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks if the user has an 'admin' role in any organization membership.
-
-## Environment Variables
-
-The following environment variables are automatically used when constructor options are not provided:
-
-**WORKOS\_API\_KEY?:** (`string`): Your WorkOS API key. Can be found in your WorkOS Dashboard under API Keys.
-
-**WORKOS\_CLIENT\_ID?:** (`string`): Your WorkOS Client ID. Can be found in your WorkOS Dashboard under Applications.
-
-## Default Authorization Behavior
-
-By default, `MastraAuthWorkos` implements role-based authorization that checks for admin access:
-
-1. **Token Verification**: The access token is verified with WorkOS to ensure it's valid and not expired
-2. **User Retrieval**: User information is extracted from the verified token
-3. **Organization Membership Check**: The system queries WorkOS for all organization memberships associated with the user's ID
-4. **Role Extraction**: All roles from the user's organization memberships are collected
-5. **Admin Check**: The system checks if any role has the slug 'admin'
-6. **Authorization Decision**: Access is granted only if the user has an admin role in at least one organization
-
-This means that by default, only users with admin privileges in at least one organization will be authorized to access your Mastra endpoints.
-
-To implement custom authorization logic (e.g., allow all authenticated users, check for specific roles, or implement custom business logic), provide a custom `authorizeUser` function.
-
-## WorkOS User Type
-
-The `WorkosUser` type used in the `authorizeUser` function corresponds to the JWT token payload returned by WorkOS. WorkOS allows administrators to set up custom JWT templates, so the exact structure may vary based on your configuration. Here's an example of what the user object might look like:
-
-```javascript
-{
-  'urn:myapp:full_name': 'John Doe',
-  'urn:myapp:email': 'john.doe@example.com',
-  'urn:myapp:organization_tier': 'bronze',
-  'urn:myapp:user_language': 'en',
-  'urn:myapp:organization_domain': 'example.com',
-  iss: 'https://api.workos.com/user_management/client_01ABC123DEF456GHI789JKL012',
-  sub: 'user_01XYZ789ABC123DEF456GHI012',
-  sid: 'session_01PQR456STU789VWX012YZA345',
-  jti: '01MNO678PQR901STU234VWX567',
-  org_id: 'org_01DEF234GHI567JKL890MNO123',
-  role: 'member',
-  roles: [ 'member' ],
-  permissions: [],
-  exp: 1758290589,
-  iat: 1758290289
-}
-```
-
-The properties with `urn:myapp:` prefixes are custom claims configured in your WorkOS JWT template. Standard JWT claims include `sub` (user ID), `iss` (issuer), `exp` (expiration), and WorkOS-specific claims like `org_id`, `role`, and `roles`.
-
-## Related
-
-[MastraAuthWorkos Class](https://mastra.ai/docs/server/auth/workos)