feat: auth core, server RBAC, and adapter permission enforcement (#13163)

## Summary

PR 1 of 3 from the `auth-rbac-cms` branch split. This PR adds all
backend plumbing for auth/RBAC. PRs 2 (auth providers) and 3 (playground
UI) depend on this and can land in parallel once this merges.

- **New `@mastra/core/auth` export** — interfaces for RBAC, sessions,
SSO, credentials, ACL, and user management, plus default implementations
(static RBAC provider, cookie/memory session providers, built-in roles)
- **Server auth handlers** — login, signup, logout, session management,
and SSO flows with Zod-validated schemas
- **Route-level permission enforcement** — `requiresPermission` on route
configs with convention-based derivation from path/method (e.g. `GET
/agents/:id` → `agents:read`)
- **Server adapter RBAC middleware** (Hono, Express, Fastify, Koa) —
resolves user permissions via RBAC provider, cookie auth fallthrough for
session-based auth
- **Authorization policy fix** — `isProtectedPath` now uses
`isProtectedCustomRoute` instead of `!isCustomRoutePublic`, fixing a bug
where studio UI couldn't load in production
- **Deployer updates** — `MASTRA_PACKAGES_FILE` env var injection,
dynamic CORS origin when auth configured
- **Client SDK** — `getFullUrl` helper, `AuthCapabilities` type export

### Key behavioral changes

| Change | Risk | Mitigation |
|---|---|---|
| `SimpleAuth<TUser>` → `SimpleAuth<TUser extends EEUser>` | Medium —
requires `id` + `email` fields | Intentional; compile-time catch |
| `isProtectedPath` logic change | Medium — authorization policy | New
tests cover this; required for studio login in prod |
| Cookie fallthrough in Hono auth middleware | Low | Falls back to 401
if no user found |
| No RBAC → authenticated users get full access | Low — intentional |
Auth-only mode preserved |
| CORS dynamic origin when auth configured | Low | Only activates with
auth config; user can override |

### Deviation from plan

`deployers/cloud/package.json` — the plan called for adding
`@mastra/auth-cloud` dependency, but that package is created in PR 2.
Omitted here to avoid workspace resolution failure; PR 2 will add it.

### Fixed pre-existing test bug

All 4 adapter RBAC tests had a failing test ("should derive permissions
from route path/method when not explicitly set") that registered an API
handler at `/agents/test` with no prefix. That's a frontend/SPA path —
real API handlers are always under `/api/*`. Fixed the test to use
`prefix: '/api'` so the route is at `/api/agents/test`, matching how
routes are actually registered. Verified the bug exists on
`auth-rbac-cms` with clean install + build.

## Test plan

- [x] `pnpm build:packages` — 35/35 tasks pass
- [x] Core auth tests (cookie.test.ts) — 16/16 pass
- [x] Server tests (permissions, helpers, system) — 177/177 pass
- [x] Hono RBAC tests — 21/21 pass
- [x] Express RBAC tests — 15/15 pass
- [x] Fastify RBAC tests — 15/15 pass
- [x] Koa RBAC tests — 15/15 pass
- [x] Client SDK tests (base.test.ts) — 5/5 pass
- [ ] Verify no auth configured → all existing behavior identical (no
403s, no auth prompts)
- [ ] Verify pre-commit hooks pass (eslint + prettier)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Enterprise auth: SSO and credentials sign-in/sign-up, login/logout,
cookie and in-memory sessions, auth capabilities and current-user
endpoints.
* RBAC: default roles, static RBAC provider, route-level permission
enforcement and middleware across adapters.
  * Client: full-URL helper; system responses include isDev.
* Deploy/build: bundling emits package metadata; deployers set runtime
packages file and adjust CORS when auth is enabled.

* **Bug Fixes**
  * Studio UI loads correctly in production.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Shane Thomas <shane@codekarate.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-6) <noreply@mastra.ai>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>

Author: 5 people

.changeset/auth-better-auth.md

@@ -0,0 +1,5 @@
+---
+'@mastra/auth-better-auth': patch
+---
+
+Expanded `@mastra/auth-better-auth` to implement the new auth interfaces (`IUserProvider`, `ISessionProvider`, `ICredentialsProvider`) from `@mastra/core/auth`. Adds support for username/password credential flows alongside the existing token-based authentication.

.changeset/auth-cli.md

@@ -0,0 +1,5 @@
+---
+'mastra': patch
+---
+
+Added auth provider bundling support to the build command. When an auth provider is configured, its package is automatically included in the build output.

.changeset/auth-client-js.md

@@ -0,0 +1,5 @@
+---
+'@mastra/client-js': patch
+---
+
+Added `getFullUrl` helper method for constructing auth redirect URLs and exported the `AuthCapabilities` type. HTTP retries now skip 4xx client errors to avoid retrying authentication failures.

.changeset/auth-cloud.md

@@ -0,0 +1,24 @@
+---
+'@mastra/auth-cloud': minor
+---
+
+Added `@mastra/auth-cloud` — a new auth provider for Mastra Cloud with PKCE OAuth flow, session management, and role-based access control.
+
+```ts
+import { MastraCloudAuthProvider, MastraRBACCloud } from '@mastra/auth-cloud';
+
+const mastra = new Mastra({
+  server: {
+    auth: new MastraCloudAuthProvider({
+      appId: process.env.MASTRA_APP_ID!,
+      apiKey: process.env.MASTRA_API_KEY!,
+    }),
+    rbac: new MastraRBACCloud({
+      appId: process.env.MASTRA_APP_ID!,
+      apiKey: process.env.MASTRA_API_KEY!,
+    }),
+  },
+});
+```
+
+Handles the full OAuth lifecycle including login URL generation, PKCE challenge/verification, callback handling, and session cookie management.

.changeset/auth-deployers.md

@@ -0,0 +1,5 @@
+---
+'@mastra/deployer-cloud': patch
+---
+
+Added dynamic CORS origin support and `@mastra/auth-cloud` integration when auth is configured on deployed instances. Service token auth now includes role information for RBAC compatibility.

.changeset/auth-playground-ui.md

@@ -0,0 +1,5 @@
+---
+'@mastra/playground-ui': minor
+---
+
+Add auth UI domain with login/signup pages, permission-gated components, and role-based access control for the studio. When no auth is configured, all permissions default to permissive (backward compatible). Includes AuthRequired wrapper, usePermissions hook, PermissionDenied component, and 403 error handling across all table views.

.changeset/auth-server-adapters.md

@@ -0,0 +1,8 @@
+---
+'@mastra/hono': patch
+'@mastra/express': patch
+'@mastra/fastify': patch
+'@mastra/koa': patch
+---
+
+Added RBAC permission enforcement to all server adapters. When an auth provider is configured, each route's required permission is checked against the authenticated user's permissions before the handler runs. Permissions are derived automatically from route paths and HTTP methods using the convention-based system from `@mastra/server`.

.changeset/auth-server.md

@@ -0,0 +1,22 @@
+---
+'@mastra/server': minor
+---
+
+Added auth handlers and route-level permission enforcement to the server.
+
+**Auth API routes** for login, signup, logout, session validation, and SSO flows — all wired automatically when an auth provider is configured on the Mastra instance.
+
+**Route-level permission enforcement** via `requiresPermission` in route configs. Permissions are derived automatically from the route path and HTTP method using a convention-based system (`{resource}:{action}`), so most routes are protected without any manual configuration:
+
+```ts
+// Automatic: GET /api/agents → requires "agents:read"
+// Automatic: POST /api/workflows/:id/execute → requires "workflows:execute"
+
+// Or specify explicitly:
+const route = {
+  path: '/api/custom',
+  method: 'POST',
+  requiresPermission: 'custom:write',
+  handler: myHandler,
+};
+```

.changeset/auth-studio.md

@@ -0,0 +1,7 @@
+---
+'@mastra/auth-studio': minor
+---
+
+Added `@mastra/auth-studio` — an auth provider for deployed Mastra Studio instances that proxies authentication through the Mastra shared API.
+
+Deployed instances need no secrets — all WorkOS authentication is handled by the shared API. The package provides SSO login/callback flows, session management via sealed cookies, RBAC with organization-scoped permissions, and automatic forced account picker on deploy logins.

.changeset/auth-workos.md

@@ -0,0 +1,31 @@
+---
+'@mastra/auth-workos': minor
+---
+
+Added full auth provider to `@mastra/auth-workos` with SSO, RBAC, SCIM directory sync, and admin portal support.
+
+```ts
+import { MastraAuthWorkos, MastraRBACWorkos } from '@mastra/auth-workos';
+
+const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos({
+      apiKey: process.env.WORKOS_API_KEY,
+      clientId: process.env.WORKOS_CLIENT_ID,
+    }),
+    rbac: new MastraRBACWorkos({
+      apiKey: process.env.WORKOS_API_KEY,
+      clientId: process.env.WORKOS_CLIENT_ID,
+      roleMapping: {
+        admin: ['*'],
+        member: ['agents:read', 'workflows:*'],
+      },
+    }),
+  },
+});
+```
+
+- **SSO** via WorkOS AuthKit (SAML, OIDC)
+- **RBAC** with wildcard permission mapping from WorkOS organization roles
+- **Directory Sync** webhook handler for SCIM-based user provisioning
+- **Admin Portal** helper for customer self-service SSO configuration