@mastra/auth 0.0.0-fix-local-pkg-cwd-20251224015404 → 0.0.0-jail-fs-20260105160110

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @mastra/auth
 
-## 0.0.0-fix-local-pkg-cwd-20251224015404
+## 0.0.0-jail-fs-20260105160110
 
 ### Major Changes
 
@@ -10,6 +10,17 @@
 
 ### Patch Changes
 
+- Add embedded documentation support for Mastra packages ([#11472](https://github.com/mastra-ai/mastra/pull/11472))
+
+  Mastra packages now include embedded documentation in the published npm package under `dist/docs/`. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from `node_modules`.
+
+  Each package includes:
+  - **SKILL.md** - Entry point explaining the package's purpose and capabilities
+  - **SOURCE_MAP.json** - Machine-readable index mapping exports to types and implementation files
+  - **Topic folders** - Conceptual documentation organized by feature area
+
+  Documentation is driven by the `packages` frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
+
 - Allow provider to pass through options to the auth config ([#10284](https://github.com/mastra-ai/mastra/pull/10284))
 
 ## 1.0.0-beta.1

package/dist/docs/README.md

@@ -0,0 +1,32 @@
+# @mastra/auth Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── auth/ (1 files)
+├── server/ (2 files)
+```
+
+## Version
+
+Package: @mastra/auth
+Version: 1.0.0-beta.1

package/dist/docs/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mastra-auth-docs
+description: Documentation for @mastra/auth. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/auth Documentation
+
+> **Version**: 1.0.0-beta.1
+> **Package**: @mastra/auth
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Auth](auth/) - 1 file(s)
+- [Server](server/) - 2 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.0.0-beta.1",
+  "package": "@mastra/auth",
+  "exports": {},
+  "modules": {}
+}

package/dist/docs/auth/01-reference.md

@@ -0,0 +1,33 @@
+# Auth API Reference
+
+> API reference for auth - 1 entries
+
+
+---
+
+## Reference: MastraJwtAuth Class
+
+> API reference for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens.
+
+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 title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { MastraJwtAuth } from "@mastra/auth";
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraJwtAuth({
+      secret: "<your-secret>",
+    }),
+  },
+});
+```
+
+## Constructor parameters
+
+## Related
+
+[MastraJwtAuth](https://mastra.ai/docs/v1/server/auth/jwt)

package/dist/docs/server/01-index.md

@@ -0,0 +1,16 @@
+> Learn about different Auth options for your Mastra applications
+
+# Auth Overview
+
+Mastra lets you choose how you handle authentication, so you can secure access to your application's endpoints using the identity system that fits your stack.
+
+You can start with simple shared secret JWT authentication and switch to providers like Supabase, Firebase Auth, Auth0, Clerk, or WorkOS when you need more advanced identity features.
+
+## Available providers
+
+- [JSON Web Token (JWT)](https://mastra.ai/docs/v1/server/auth/jwt)
+- [Clerk](https://mastra.ai/docs/v1/server/auth/clerk)
+- [Supabase](https://mastra.ai/docs/v1/server/auth/supabase)
+- [Firebase](https://mastra.ai/docs/v1/server/auth/firebase)
+- [WorkOS](https://mastra.ai/docs/v1/server/auth/workos)
+- [Auth0](https://mastra.ai/docs/v1/server/auth/auth0)

package/dist/docs/server/02-jwt.md

@@ -0,0 +1,100 @@
+> Documentation for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens.
+
+# 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.
+
+```bash
+npm install @mastra/auth@beta
+```
+
+## Usage example
+
+```typescript {2,6-8} title="src/mastra/index.ts"
+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,
+    }),
+  },
+});
+```
+
+> **Note:**
+
+Visit [MastraJwtAuth](https://mastra.ai/reference/v1/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 {6} title="lib/mastra/mastra-client.ts"
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "https://<mastra-api-url>",
+  headers: {
+    Authorization: `Bearer ${process.env.MASTRA_JWT_TOKEN}`,
+  },
+});
+```
+
+> **Note:**
+
+Visit [Mastra Client SDK](https://mastra.ai/docs/v1/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 title="src/components/test-agent.tsx" copy
+    import { mastraClient } from "../../lib/mastra-client";
+
+    export const TestAgent = () => {
+      async function handleClick() {
+        const agent = mastraClient.getAgent("weatherAgent");
+
+        const response = await agent.generate({
+          messages: "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/auth",
-  "version": "0.0.0-fix-local-pkg-cwd-20251224015404",
+  "version": "0.0.0-jail-fs-20260105160110",
   "description": "",
   "type": "module",
   "files": [
@@ -36,10 +36,10 @@
     "eslint": "^9.37.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "vitest": "4.0.12",
-    "@internal/lint": "0.0.0-fix-local-pkg-cwd-20251224015404",
-    "@internal/types-builder": "0.0.0-fix-local-pkg-cwd-20251224015404",
-    "@mastra/core": "0.0.0-fix-local-pkg-cwd-20251224015404"
+    "vitest": "4.0.16",
+    "@internal/lint": "0.0.0-jail-fs-20260105160110",
+    "@internal/types-builder": "0.0.0-jail-fs-20260105160110",
+    "@mastra/core": "0.0.0-jail-fs-20260105160110"
   },
   "homepage": "https://mastra.ai",
   "repository": {
@@ -55,6 +55,7 @@
   },
   "scripts": {
     "build": "tsup --silent --config tsup.config.ts",
+    "postbuild": "pnpx tsx ../../scripts/generate-package-docs.ts packages/auth",
     "build:watch": "tsup --watch --silent --config tsup.config.ts",
     "test": "vitest run",
     "lint": "eslint ."