@mastra/mcp-docs-server 1.2.2-alpha.7 → 1.2.2

package/.docs/reference/auth/google.md

@@ -0,0 +1,355 @@
+# MastraAuthGoogle & MastraRBACGoogle class
+
+## MastraAuthGoogle class
+
+The `MastraAuthGoogle` class provides authentication for Mastra using Google Workspace. It implements an OAuth 2.0 / OIDC login flow with encrypted session cookies, verifies Google ID tokens, and integrates with the Mastra server using the `auth` option.
+
+### Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthGoogle } from '@mastra/auth-google'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthGoogle({
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      redirectUri: process.env.GOOGLE_REDIRECT_URI,
+      allowedDomains: ['example.com'],
+    }),
+  },
+})
+```
+
+> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables set. In that case, use `new MastraAuthGoogle()` without any arguments.
+
+### Constructor parameters
+
+**clientId** (`string`): Google OAuth client ID. (Default: `process.env.GOOGLE_CLIENT_ID`)
+
+**clientSecret** (`string`): Google OAuth client secret. Required for Studio SSO. (Default: `process.env.GOOGLE_CLIENT_SECRET`)
+
+**redirectUri** (`string`): OAuth redirect URI for the SSO callback. Must match the redirect URI configured in your Google Cloud OAuth client. (Default: `process.env.GOOGLE_REDIRECT_URI`)
+
+**scopes** (`string[]`): OAuth scopes requested during the login flow. (Default: `['openid', 'profile', 'email']`)
+
+**allowedDomains** (`string | string[]`): Allowed Google Workspace hosted domains. Mastra validates these against the verified \`hd\` claim. (Default: `process.env.GOOGLE_ALLOWED_DOMAINS`)
+
+**hostedDomain** (`string`): Hosted-domain login hint passed to Google as \`hd\`. This is a hint only and is not used for authorization. (Default: `process.env.GOOGLE_HOSTED_DOMAIN or the single allowed domain`)
+
+**session** (`GoogleSessionOptions`): Session cookie configuration.
+
+**session.cookieName** (`string`): Name of the session cookie.
+
+**session.cookieMaxAge** (`number`): Cookie max age in seconds.
+
+**session.cookiePassword** (`string`): Password for encrypting session cookies. Must be at least 32 characters. If not set, an auto-generated value is used in development that does not survive restarts.
+
+**session.secureCookies** (`boolean`): Set the \`Secure\` flag on session cookies.
+
+**name** (`string`): Custom name for the auth provider instance. (Default: `'google'`)
+
+### Environment variables
+
+The following environment variables are automatically used when constructor options aren't provided:
+
+**GOOGLE\_CLIENT\_ID** (`string`): Google OAuth client ID from your Google Cloud OAuth client.
+
+**GOOGLE\_CLIENT\_SECRET** (`string`): Google OAuth client secret. Required for the SSO authorization code flow.
+
+**GOOGLE\_REDIRECT\_URI** (`string`): OAuth redirect URI for the SSO callback.
+
+**GOOGLE\_COOKIE\_PASSWORD** (`string`): Password for encrypting session cookies. Must be at least 32 characters.
+
+**GOOGLE\_ALLOWED\_DOMAINS** (`string`): Comma-separated Google Workspace hosted domains to allow.
+
+**GOOGLE\_HOSTED\_DOMAIN** (`string`): Hosted-domain login hint passed to Google during SSO login.
+
+### Authentication flow
+
+`MastraAuthGoogle` authenticates requests in the following order:
+
+1. **Session cookie**: When SSO is enabled, reads the encrypted session cookie and decrypts it. If the session is valid and not expired, the user is authenticated.
+2. **Google ID token fallback**: If no valid session cookie is present, verifies the `Authorization` header token against Google's JWKS endpoint.
+
+After authentication, `authorizeUser` checks that the user has a valid Google user ID, the token-derived expiration has not passed, and the user's verified `hd` claim matches `allowedDomains` when domains are configured.
+
+### Authentication methods
+
+#### `authenticateToken(token, request?)`
+
+Authenticates a Google ID token. When SSO is enabled, this method checks the encrypted session cookie before it verifies the Bearer token.
+
+```typescript
+const user = await auth.authenticateToken(idToken, request)
+```
+
+Returns: `Promise<GoogleUser | null>`
+
+#### `getCurrentUser(request)`
+
+Returns the authenticated user from a session cookie or Bearer Google ID token.
+
+```typescript
+const user = await auth.getCurrentUser(request)
+```
+
+Returns: `Promise<GoogleUser | null>`
+
+#### `authorizeUser(user)`
+
+Returns `true` when the user has an ID, has not expired, and matches `allowedDomains` when domains are configured.
+
+```typescript
+const allowed = auth.authorizeUser(user)
+```
+
+Returns: `boolean`
+
+#### `getUser(userId)`
+
+Returns `null`. Google ID tokens are verified directly, so this provider does not perform user lookup by ID.
+
+```typescript
+const user = await auth.getUser(userId)
+```
+
+Returns: `Promise<GoogleUser | null>`
+
+### `GoogleUser` type
+
+The `GoogleUser` type extends the base `EEUser` interface with Google-specific fields:
+
+**id** (`string`): Mastra user ID. Uses the Google \`sub\` claim.
+
+**googleId** (`string`): Google Account subject identifier.
+
+**email** (`string`): User email address.
+
+**name** (`string`): User display name from Google profile claims.
+
+**avatarUrl** (`string`): URL to the user's Google profile picture.
+
+**hostedDomain** (`string`): Google Workspace hosted domain from the verified \`hd\` claim.
+
+**expiresAt** (`Date`): Verified ID token expiration time, when available.
+
+**emailVerified** (`boolean`): Whether Google reports the email address as verified.
+
+**groups** (`string[]`): Optional pre-resolved Google Workspace group role IDs.
+
+## MastraRBACGoogle class
+
+The `MastraRBACGoogle` class maps Google Workspace groups to Mastra permissions. It fetches user groups from the Google Admin SDK Directory API and resolves them against a configurable role mapping. Use it with `MastraAuthGoogle` or any other auth provider.
+
+> **Note:** RBAC requires a valid Enterprise Edition license. It works without a license in development so you can try it locally, but you'll need a license for production. [Contact sales](https://mastra.ai/contact) for more information.
+
+### Usage example
+
+Use `MastraRBACGoogle` alongside an auth provider by passing it to the `rbac` option:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthGoogle, MastraRBACGoogle } from '@mastra/auth-google'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthGoogle(),
+    rbac: new MastraRBACGoogle({
+      serviceAccount: {
+        clientEmail: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL!,
+        privateKey: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY!,
+        subject: process.env.GOOGLE_WORKSPACE_ADMIN_EMAIL!,
+      },
+      roleMapping: {
+        'admins@example.com': ['*'],
+        'engineering@example.com': ['agents:*', 'workflows:*', 'tools:*'],
+        'viewers@example.com': ['agents:read', 'workflows:read'],
+        _default: [],
+      },
+    }),
+  },
+})
+```
+
+To use Google Workspace RBAC with a different auth provider, pass a `getUserKey` function to resolve the Google Directory API user key from the other provider's user object:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthAuth0 } from '@mastra/auth-auth0'
+import { MastraRBACGoogle } from '@mastra/auth-google'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthAuth0(),
+    rbac: new MastraRBACGoogle({
+      getUserKey: user => user.email,
+      serviceAccount: {
+        clientEmail: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL!,
+        privateKey: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY!,
+        subject: process.env.GOOGLE_WORKSPACE_ADMIN_EMAIL!,
+      },
+      roleMapping: {
+        'engineering@example.com': ['agents:*', 'workflows:*'],
+        'admins@example.com': ['*'],
+        _default: [],
+      },
+    }),
+  },
+})
+```
+
+### Constructor parameters
+
+**roleMapping** (`RoleMapping`): Maps Google Workspace group role IDs to arrays of Mastra permission strings. Use \`'\_default'\` to assign permissions to users who do not match any group. Supports wildcards like \`'\*'\` (full access) and \`'agents:\*'\` (all agent actions).
+
+**accessToken** (`string`): Pre-obtained Workspace Directory API access token.
+
+**getAccessToken** (`() => Promise<string> | string`): Callback that returns a Workspace Directory API access token.
+
+**serviceAccount** (`GoogleWorkspaceServiceAccount`): Service account credentials for domain-wide delegated Directory API access.
+
+**serviceAccount.clientEmail** (`string`): Google service account email.
+
+**serviceAccount.privateKey** (`string`): PEM-encoded private key. Escaped \`\n\` values from .env files are supported.
+
+**serviceAccount.privateKeyId** (`string`): Optional private key ID.
+
+**serviceAccount.subject** (`string`): Workspace administrator user to impersonate with domain-wide delegation.
+
+**serviceAccount.scopes** (`string[]`): OAuth scopes for the service account token.
+
+**getUserKey** (`(user: unknown) => string | undefined`): Extract the Directory API \`userKey\` from an authenticated user. Defaults to \`user.email\`.
+
+**mapGroupToRoles** (`(group: GoogleWorkspaceGroup) => string[]`): Map a Google Workspace group to role IDs. Defaults to \`\[group.email]\`.
+
+**cache** (`PermissionCacheOptions`): Configure the LRU cache for group lookups.
+
+**cache.maxSize** (`number`): Maximum number of users to cache.
+
+**cache.ttlMs** (`number`): Time-to-live in milliseconds.
+
+### RBAC methods
+
+#### `getRoles(user)`
+
+Returns Google Workspace group role IDs for a user.
+
+```typescript
+const roles = await rbac.getRoles(user)
+```
+
+Returns: `Promise<string[]>`
+
+#### `getPermissions(user)`
+
+Returns Mastra permissions resolved from Google Workspace groups and `roleMapping`.
+
+```typescript
+const permissions = await rbac.getPermissions(user)
+```
+
+Returns: `Promise<string[]>`
+
+#### `hasPermission(user, permission)`
+
+Checks whether a user has a permission.
+
+```typescript
+const canReadAgents = await rbac.hasPermission(user, 'agents:read')
+```
+
+Returns: `Promise<boolean>`
+
+#### `hasRole(user, role)`
+
+Checks whether a user resolved to a specific Google Workspace group role.
+
+```typescript
+const isAdmin = await rbac.hasRole(user, 'admins@example.com')
+```
+
+Returns: `Promise<boolean>`
+
+#### `hasAllPermissions(user, permissions)`
+
+Checks whether a user has every requested permission.
+
+```typescript
+const canManageAgents = await rbac.hasAllPermissions(user, ['agents:read', 'agents:update'])
+```
+
+Returns: `Promise<boolean>`
+
+#### `hasAnyPermission(user, permissions)`
+
+Checks whether a user has at least one requested permission.
+
+```typescript
+const canReadSomething = await rbac.hasAnyPermission(user, ['agents:read', 'workflows:read'])
+```
+
+Returns: `Promise<boolean>`
+
+#### `getAvailableRoles()`
+
+Returns the role IDs configured in `roleMapping`, excluding `_default`.
+
+```typescript
+const roles = await rbac.getAvailableRoles()
+```
+
+Returns: `Promise<{ id: string; name: string }[]>`
+
+#### `getPermissionsForRole(roleId)`
+
+Returns the permissions configured for a role ID.
+
+```typescript
+const permissions = await rbac.getPermissionsForRole('engineering@example.com')
+```
+
+Returns: `Promise<string[]>`
+
+#### `clearCache()`
+
+Clears all cached Google Workspace group lookups.
+
+```typescript
+rbac.clearCache()
+```
+
+Returns: `void`
+
+#### `clearUserCache(userKey)`
+
+Clears the cached group lookup for one Directory API user key, such as an email address.
+
+```typescript
+rbac.clearUserCache('user@example.com')
+```
+
+Returns: `void`
+
+#### `getCacheStats()`
+
+Returns the current group lookup cache size and maximum size.
+
+```typescript
+const stats = rbac.getCacheStats()
+```
+
+Returns: `{ size: number; maxSize: number }`
+
+### Additional configuration
+
+`MastraRBACGoogle` uses `GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=...` and handles pagination. Provide a service account with domain-wide delegation for production Google Workspace deployments, or pass `accessToken` / `getAccessToken` if your application already manages Google API tokens.
+
+If `user.groups` is already an array, `MastraRBACGoogle` uses that value and does not call the Directory API. An empty `groups` array means the user has no Google group roles and resolves to `_default` permissions when `_default` is configured.
+
+`MastraRBACGoogle` does not automatically read service-account environment variables. Pass service-account credentials through the `serviceAccount` option, or pass `accessToken` / `getAccessToken`.
+
+## Related
+
+[Google auth docs](https://mastra.ai/docs/server/auth/google)

package/.docs/reference/index.md

@@ -45,6 +45,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Better Auth](https://mastra.ai/reference/auth/better-auth)
 - [Clerk](https://mastra.ai/reference/auth/clerk)
 - [Firebase](https://mastra.ai/reference/auth/firebase)
+- [Google](https://mastra.ai/reference/auth/google)
 - [JSON Web Token](https://mastra.ai/reference/auth/jwt)
 - [Okta](https://mastra.ai/reference/auth/okta)
 - [Supabase](https://mastra.ai/reference/auth/supabase)

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @mastra/mcp-docs-server
 
+## 1.2.2
+
+### Patch Changes
+
+- Updated dependencies [[`86623c1`](https://github.com/mastra-ai/mastra/commit/86623c1adf7d22de32cc916dda17f4155184db36), [`023766f`](https://github.com/mastra-ai/mastra/commit/023766f44d59b30a50f3a381e33eddde8ab56c00), [`0200e75`](https://github.com/mastra-ai/mastra/commit/0200e7552d02d4221cd6040bf4eddf189a97a156), [`7c9dd77`](https://github.com/mastra-ai/mastra/commit/7c9dd77bd18cb8dc72797e25f1a0fbdc71a11347), [`7f9ae70`](https://github.com/mastra-ai/mastra/commit/7f9ae70826b047e5a66218f9e92f20e54a2d791f), [`a0509c7`](https://github.com/mastra-ai/mastra/commit/a0509c731a08aa3ed626557c5338126362856f57), [`06e0d63`](https://github.com/mastra-ai/mastra/commit/06e0d63d42bc2a202e18bc091f3781f409f5e6fb), [`bf3fe49`](https://github.com/mastra-ai/mastra/commit/bf3fe49f9467dbbdb8f9eaf74e0f7971ffb19559), [`01caf93`](https://github.com/mastra-ai/mastra/commit/01caf93d71ae2c1e65f49735cafb531975187426), [`438a971`](https://github.com/mastra-ai/mastra/commit/438a9715c8b4398e5eaf8914a1f19dc8a85dc1de), [`9990965`](https://github.com/mastra-ai/mastra/commit/999096571635a83b42ef40841fd7028cfa630779), [`77518cc`](https://github.com/mastra-ai/mastra/commit/77518ccb5bb8cc684875081e64213dc85cffdbee), [`fbeda0c`](https://github.com/mastra-ai/mastra/commit/fbeda0c0f35def07e6837936dd3a003b2b7c5172), [`8a68844`](https://github.com/mastra-ai/mastra/commit/8a688443013816105a09f89c6afa34b5ff13e26d), [`bb2a13b`](https://github.com/mastra-ai/mastra/commit/bb2a13bb4b32e6bb807200fe7b18ae8fa4322118), [`24ceaea`](https://github.com/mastra-ai/mastra/commit/24ceaea0bdd8609cabbab764380608ca6621a194), [`a73cd1a`](https://github.com/mastra-ai/mastra/commit/a73cd1a62a5e4ca023dcc39ba150029f4f1f74c1), [`c0ffa3c`](https://github.com/mastra-ai/mastra/commit/c0ffa3c897ccd326de880df734740a7f0681a18f), [`462a769`](https://github.com/mastra-ai/mastra/commit/462a769da61850862ca1be3d74134d33078ee6a7), [`0504bf5`](https://github.com/mastra-ai/mastra/commit/0504bf5e8cffc571a4b343326178de371e6f859b), [`0b5cc47`](https://github.com/mastra-ai/mastra/commit/0b5cc4726dc18d9a685a27520db39ff1b36bb89a), [`87f38a3`](https://github.com/mastra-ai/mastra/commit/87f38a3de03e24731f2dd6f8ed6a60b6722b85a1), [`d5fa3cd`](https://github.com/mastra-ai/mastra/commit/d5fa3cda1788c3cb93a361a3c6ec47de6ba21e98), [`fe98ef2`](https://github.com/mastra-ai/mastra/commit/fe98ef2e66dbfcbd7d645c88c9ee1e67b458a136), [`6ccf67b`](https://github.com/mastra-ai/mastra/commit/6ccf67bf075753754927a57bc2e1734ba2c820c5), [`793ea0f`](https://github.com/mastra-ai/mastra/commit/793ea0f52f831178837f21c83af6af93bf4ce638), [`825d8de`](https://github.com/mastra-ai/mastra/commit/825d8def9fa64c2bcc3d8dd6b49e09342c3ac5c7), [`507a5c4`](https://github.com/mastra-ai/mastra/commit/507a5c461bdc3136ad80744c0efbb55ce1f18f97), [`5afe423`](https://github.com/mastra-ai/mastra/commit/5afe423e4badf040f1b0d4525183a856fcb8146e), [`307573b`](https://github.com/mastra-ai/mastra/commit/307573b9ff3149b70c79540dbc86f1319b180f29), [`79b3626`](https://github.com/mastra-ai/mastra/commit/79b3626f8d647307eb07c8da14c9073c2699719d), [`c2c1d7b`](https://github.com/mastra-ai/mastra/commit/c2c1d7bb61d2602955f14ed3952f807c2d6eb576), [`86623c1`](https://github.com/mastra-ai/mastra/commit/86623c1adf7d22de32cc916dda17f4155184db36), [`1505c07`](https://github.com/mastra-ai/mastra/commit/1505c07603f6346bae12aa82f140e8b88ffea9ab), [`f328049`](https://github.com/mastra-ai/mastra/commit/f3280498c324afd2a8d36cd828f5b9f94a2dddc1), [`e545228`](https://github.com/mastra-ai/mastra/commit/e54522856934a5dc030b7b6385771e3548020d59), [`3eb852e`](https://github.com/mastra-ai/mastra/commit/3eb852e5435bc908b800193498103dc724f455b0), [`ffa09e7`](https://github.com/mastra-ai/mastra/commit/ffa09e772a5c92270eabe2090fc42d45bd8ec4b7), [`8c9f1c0`](https://github.com/mastra-ai/mastra/commit/8c9f1c0361d89066f9bcd14a2f69e761b01766c8), [`461a7c5`](https://github.com/mastra-ai/mastra/commit/461a7c501449295287f4f0ee4b0b42344f39fcf8), [`4211472`](https://github.com/mastra-ai/mastra/commit/4211472a5a2bd319c60cd2e42d9109c3eef7ac1c), [`9e45902`](https://github.com/mastra-ai/mastra/commit/9e4590208e745055cecca202e2db0e5c65e17d3c), [`5c0df77`](https://github.com/mastra-ai/mastra/commit/5c0df776c40efa420f8c07a2f3ee66010296618e), [`e940f09`](https://github.com/mastra-ai/mastra/commit/e940f099ef5d18b403e6f2b4937e086a4da857b1)]:
+  - @mastra/core@1.47.0
+
+## 1.2.2-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`8a68844`](https://github.com/mastra-ai/mastra/commit/8a688443013816105a09f89c6afa34b5ff13e26d)]:
+  - @mastra/core@1.47.0-alpha.7
+
+## 1.2.2-alpha.10
+
+### Patch Changes
+
+- Updated dependencies [[`0200e75`](https://github.com/mastra-ai/mastra/commit/0200e7552d02d4221cd6040bf4eddf189a97a156), [`06e0d63`](https://github.com/mastra-ai/mastra/commit/06e0d63d42bc2a202e18bc091f3781f409f5e6fb), [`438a971`](https://github.com/mastra-ai/mastra/commit/438a9715c8b4398e5eaf8914a1f19dc8a85dc1de), [`77518cc`](https://github.com/mastra-ai/mastra/commit/77518ccb5bb8cc684875081e64213dc85cffdbee), [`bb2a13b`](https://github.com/mastra-ai/mastra/commit/bb2a13bb4b32e6bb807200fe7b18ae8fa4322118), [`a73cd1a`](https://github.com/mastra-ai/mastra/commit/a73cd1a62a5e4ca023dcc39ba150029f4f1f74c1), [`0b5cc47`](https://github.com/mastra-ai/mastra/commit/0b5cc4726dc18d9a685a27520db39ff1b36bb89a), [`87f38a3`](https://github.com/mastra-ai/mastra/commit/87f38a3de03e24731f2dd6f8ed6a60b6722b85a1), [`d5fa3cd`](https://github.com/mastra-ai/mastra/commit/d5fa3cda1788c3cb93a361a3c6ec47de6ba21e98), [`fe98ef2`](https://github.com/mastra-ai/mastra/commit/fe98ef2e66dbfcbd7d645c88c9ee1e67b458a136), [`793ea0f`](https://github.com/mastra-ai/mastra/commit/793ea0f52f831178837f21c83af6af93bf4ce638), [`507a5c4`](https://github.com/mastra-ai/mastra/commit/507a5c461bdc3136ad80744c0efbb55ce1f18f97), [`79b3626`](https://github.com/mastra-ai/mastra/commit/79b3626f8d647307eb07c8da14c9073c2699719d)]:
+  - @mastra/core@1.47.0-alpha.6
+
+## 1.2.2-alpha.8
+
+### Patch Changes
+
+- Updated dependencies [[`023766f`](https://github.com/mastra-ai/mastra/commit/023766f44d59b30a50f3a381e33eddde8ab56c00), [`a0509c7`](https://github.com/mastra-ai/mastra/commit/a0509c731a08aa3ed626557c5338126362856f57), [`01caf93`](https://github.com/mastra-ai/mastra/commit/01caf93d71ae2c1e65f49735cafb531975187426), [`c2c1d7b`](https://github.com/mastra-ai/mastra/commit/c2c1d7bb61d2602955f14ed3952f807c2d6eb576), [`3eb852e`](https://github.com/mastra-ai/mastra/commit/3eb852e5435bc908b800193498103dc724f455b0)]:
+  - @mastra/core@1.47.0-alpha.5
+
 ## 1.2.2-alpha.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.2-alpha.7",
+  "version": "1.2.2",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
     "@mastra/mcp": "^1.12.0",
-    "@mastra/core": "1.47.0-alpha.4"
+    "@mastra/core": "1.47.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
-    "@internal/lint": "0.0.108",
-    "@internal/types-builder": "0.0.83",
-    "@mastra/core": "1.47.0-alpha.4"
+    "@internal/lint": "0.0.109",
+    "@internal/types-builder": "0.0.84",
+    "@mastra/core": "1.47.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {