@mastra/core 1.2.0 → 1.2.1-alpha.0

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

@@ -0,0 +1,33 @@
+# 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

@@ -0,0 +1,84 @@
+# 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)

package/dist/docs/{cli/01-reference.md → references/reference-cli-mastra.md}

@@ -1,29 +1,20 @@
-# Cli API Reference
-
-> API reference for cli - 1 entries
-
-
----
-
-## Reference: CLI Commands
-
-> Documentation for the Mastra CLI to develop, build, and start your project.
+# CLI Commands
 
 You can use the Command-Line Interface (CLI) provided by Mastra to develop, build, and start your Mastra project.
 
 ## `mastra dev`
 
-Starts a server which exposes [Studio](https://mastra.ai/docs/getting-started/studio) and REST endpoints for your agents, tools, and workflows. You can visit [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui) for an overview of all available endpoints once `mastra dev` is running.
+Starts a server which exposes [Studio](https://mastra.ai/docs/getting-started/studio) and REST endpoints for your agents, tools, and workflows. You can visit <http://localhost:4111/swagger-ui> for an overview of all available endpoints once `mastra dev` is running.
 
-You can also [configure the server](https://mastra.ai/docs/getting-started/studio#configuration).
+You can also [configure the server](https://mastra.ai/docs/getting-started/studio).
 
 ### Flags
 
-The command accepts [common flags][common-flags] and the following additional flags:
+The command accepts [common flags](#common-flags) and the following additional flags:
 
 #### `--https`
 
-Enable local HTTPS support. [Learn more](https://mastra.ai/reference/configuration#serverhttps).
+Enable local HTTPS support. [Learn more](https://mastra.ai/reference/configuration).
 
 #### `--inspect`
 
@@ -89,8 +80,7 @@ ANTHROPIC_BASE_URL=https://anthropic.internal \
 mastra dev
 ```
 
-These are forwarded to the Mastra model router and will work with any `"openai/..."`
-or `"anthropic/..."` model selections.
+These are forwarded to the Mastra model router and will work with any `"openai/..."` or `"anthropic/..."` model selections.
 
 ## `mastra build`
 
@@ -102,7 +92,7 @@ The output in `.mastra` can be deployed to any cloud server using [`mastra start
 
 If you're deploying to a [serverless platform](https://mastra.ai/guides/deployment) you need to install the correct deployer in order to receive the correct output in `.mastra`.
 
-It accepts [common flags][common-flags].
+It accepts [common flags](#common-flags).
 
 ### Flags
 
@@ -132,15 +122,13 @@ MASTRA_CONCURRENCY=2 mastra build
 
 ## `mastra start`
 
-> **Note:**
-
-You need to run `mastra build` before using `mastra start`.
+> **Info:** You need to run `mastra build` before using `mastra start`.
 
 Starts a local server to serve your built Mastra application in production mode. By default, [OTEL Tracing](https://mastra.ai/docs/observability/tracing/overview) is enabled.
 
 ### Flags
 
-The command accepts [common flags][common-flags] and the following additional flags:
+The command accepts [common flags](#common-flags) and the following additional flags:
 
 #### `--dir`
 
@@ -156,7 +144,7 @@ Starts [Mastra Studio](https://mastra.ai/docs/getting-started/studio) as a stati
 
 ### Flags
 
-The command accepts [common flags][common-flags] and the following additional flags:
+The command accepts [common flags](#common-flags) and the following additional flags:
 
 #### `--port`
 
@@ -178,7 +166,7 @@ The protocol of the Mastra API server to connect to. Defaults to `http`.
 
 The `mastra lint` command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.
 
-It accepts [common flags][common-flags].
+It accepts [common flags](#common-flags).
 
 ## `mastra scorers`
 
@@ -258,9 +246,9 @@ The command bundles your project, connects to your configured storage backend, a
 mastra migrate
 ```
 
-See the [Storage migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/storage#duplicate-spans-migration) for details on when migrations are needed.
+See the [Storage migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/storage) for details on when migrations are needed.
 
-It accepts [common flags][common-flags].
+It accepts [common flags](#common-flags).
 
 ## Common flags
 
@@ -320,6 +308,4 @@ You can also set this while using other `mastra` commands:
 
 ```bash
 MASTRA_TELEMETRY_DISABLED=1 mastra dev
-```
-
-[common-flags]: #common-flags
+```

package/dist/docs/{client-js/01-reference.md → references/reference-client-js-agents.md}

@@ -1,13 +1,4 @@
-# Client js API Reference
-
-> API reference for client js - 1 entries
-
-
----
-
-## Reference: Agents API
-
-> Learn how to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools using the client-js SDK.
+# Agents API
 
 The Agents API provides methods to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools.
 
@@ -25,7 +16,7 @@ Returns a record of agent IDs to their serialized agent configurations.
 
 Get an instance of a specific agent by its ID:
 
-```typescript title="src/mastra/agents/my-agent.ts"
+```typescript
 export const myAgent = new Agent({
   id: "my-agent",
 });
@@ -128,7 +119,7 @@ while (true) {
 
 To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:
 
-```typescript title="client-ai-sdk-transform.ts"
+```typescript
 import { createUIMessageStream } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
 import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";