Mastra 框架接入 Mastra Cloud 认证mastra/auth-cloud 的 OAuth 2.0 PKCE 全流程解析【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/auth-cloud是 Mastra 官方提供的云认证集成包它让自托管的 Mastra 服务可以把登录、会话与权限校验完整委托给 Mastra Cloud 平台通过 OAuth 2.0 PKCE 授权码流程实现浏览器重定向登录 Cookie 会话 Bearer Token 回退 RBAC 权限控制。本文以 cloud-auth.md 为骨架结合 auth/cloud/src 下的源码实现与测试用例完整拆解其登录流程、认证端点、Cookie 生命周期、安全防护与角色权限模型帮助你在自己的 Mastra 服务中正确接入并理解其底层机制。一、适用场景与设计目标当你的 Mastra 服务采用**自托管self-hosted**方式部署但又不想自己维护一套用户体系时mastra/auth-cloud可以让你把身份认证外包给 Mastra Cloud用户在Mastra Cloud上完成登录其底层由 WorkOS 等身份服务支撑你的服务器通过PKCE 授权码流程换取访问令牌浏览器端通过HttpOnly Cookie维持会话无 JS 可直接读取令牌非浏览器 API 客户端则通过Authorization: Bearer头携带令牌完成认证权限判断由role → permission 映射的 RBAC 机制完成。该包对外暴露三个核心类见 index.ts公共 API职责MastraCloudAuth底层客户端门面facade封装 OAuth 与会话模块为统一 APIMastraCloudAuthProvider服务端 Provider实现 Mastra 服务器认证中间件所需的 SSO / Session / User 接口MastraRBACCloud基于角色映射的权限判定 Provider三者之上再叠加三个内部模块oauth/登录 URL 生成与回调处理、pkce/PKCE 密码学与 Cookie 存储、session/令牌校验、会话验证、登出。源码中MastraCloudAuthProvider持有MastraCloudAuth客户端实例MastraCloudAuth再依次组合oauth/、pkce/、session/模块构成清晰的公共门面 → 内部实现分层结构见 client.ts。二、安装与基础配置安装命令仓库内该包版本为 1.2.5见 package.jsonnpm install mastra/auth-cloud在启动 Mastra 之前需要先设置环境变量MASTRA_PROJECT_IDMastra Cloud 项目 ID。最小可用配置如下摘自 README.mdimport { MastraCloudAuthProvider } from mastra/auth-cloud; import { Mastra } from mastra/core/mastra; export const mastra new Mastra({ server: { auth: new MastraCloudAuthProvider({ projectId: process.env.MASTRA_PROJECT_ID!, cloudBaseUrl: https://cloud.mastra.ai, callbackUrl: https://example.com/auth/callback, isProduction: process.env.NODE_ENV production, }), }, });四个核心配置项类型定义见 client.ts 与 auth-provider.ts配置项必填说明projectId是Mastra Cloud 项目 ID也会作为X-Project-ID请求头发送给 Cloud APIcloudBaseUrl是Cloud API 基地址例如https://cloud.mastra.ai所有/auth/*端点都基于它拼接callbackUrl是应用注册的 OAuth 回调地址必须为绝对 URL且与发送给/auth/oss的redirect_uri保持一致isProduction否生产环境开关为true时给认证 Cookie 追加Secure属性缺省时回退判断process.env.NODE_ENV productionMastraCloudAuthProvider同时继承自MastraAuthProvider并实现IUserProvider、ISSOProvider、ISessionProvider三个接口见 auth-provider.ts因此可以无缝接入 Mastra 服务器认证中间件还能复用 Mastra 公共认证选项中关于公开/受保护路由与自定义用户授权的配置。三、登录流程PKCE 授权码全链路拆解整个登录过程是标准的OAuth 2.0 Authorization Code PKCE流程文档中的序列图可展开为以下 12 个关键步骤1. Browser → Server : GET /auth/login 2. Server 内部 : 生成 code_verifier code_challengeS256 3. Server 内部 : 生成 CSRF 随机令牌 4. Server 内部 : 将 CSRF 与 returnTo 编码进 state 参数 5. Server → Browser : 写入 PKCE Cookie5 分钟 302 重定向 6. Browser → Cloud : /auth/oss?code_challengeXstateY用户在 Cloud 登录 7. Cloud → Browser : 302 重定向到 /callback?codeZstateY 8. Browser → Server : GET /callback?codeZstateY 9. Server 内部 : 读取并校验 PKCE Cookie是否过期、是否匹配 10. Server → Cloud : POST /auth/callback携带 code code_verifier 11. Cloud → Server : 返回 { accessToken } 12. Server → Cloud : POST /auth/verifyBearer token 13. Cloud → Server : 返回 { user, role } 14. Server → Browser : 写入会话 Cookie24 小时 重定向3.1 生成登录 URLgetLoginUrloauth/oauth.ts中的getLoginUrl()oauth.ts按顺序完成生成 PKCE 凭证generateCodeVerifier()使用 32 字节随机数生成 43 字符的 base64url verifiercomputeCodeChallenge()按 RFC 7636 的 S256 方法计算BASE64URL(SHA256(verifier))见 pkce.ts生成 CSRF 令牌generateState()使用 16 字节随机数生成 22 字符 base64url 状态值校验 returnTo调用validateReturnTo()防止开放重定向攻击编码 state将{ csrf, returnTo }序列化为 JSON 后做 base64url 编码见 state.ts拼装授权 URL指向{cloudBaseUrl}/auth/oss并携带五个查询参数查询参数值project_id项目 IDcode_challengeS256 计算出的 challengecode_challenge_methodS256redirect_uri应用回调地址statebase64url 编码的{csrf, returnTo}同时生成一个名为mastra_pkce_verifier的 Cookie5 分钟 TTL其中保存 verifier、state 与过期时间随重定向响应一同下发。3.2 处理回调handleCallback回调处理handleCallback()oauth.ts包含四道校验与一次令牌兑换从请求 Cookie 中解析mastra_pkce_verifier缺失或过期会抛出PKCEError见 cookie.ts解码state参数要求包含csrf与returnTo两个字段CSRF 校验对比 state 中的csrf与 PKCE Cookie 中的state不一致则抛出AuthError.stateMismatch()Possible CSRF attack兑换令牌POST {cloudBaseUrl}/auth/callback请求头携带Content-Type: application/json与X-Project-ID请求体携带{ code, redirect_uri, code_verifier }失败时解析 Cloud 返回的code/message并抛出token_exchange_failed获取用户信息携带Authorization: Bearer {access_token}再POST /auth/verify得到{ sub, email, name?, avatar_url?, role }映射为CloudUser见 types.ts。回调完成后会下发清除 PKCE Cookie 的 Set-CookieMax-Age0随后由MastraCloudAuthProvider.handleCallback()调用setSessionCookie()写入会话 Cookie见 auth-provider.ts。四、每请求认证流程与 Bearer Token 回退登录成功后浏览器携带会话 Cookie 发起 API 请求时认证中间件调用authenticateToken()完成鉴权auth-provider.ts其判定顺序为1. 解析请求 Cookie 中的 mastra_cloud_session 令牌 2. 若存在 → POST /auth/verify 校验会话令牌返回 { user, role } 3. 若无 Cookie 但带 Authorization: Bearer token → 同样 POST /auth/verify 校验 4. 两者皆无 → 返回 null未认证 5. 任何异常 → 统一返回 null不向客户端泄露错误细节文档中的认证序列图还展示了权限判定分支hasPermission(user, agents:read)返回false时服务器返回403 Forbidden通过则返回200 Response。authorizeUser()只做最基础的用户 id 存在即通过校验更细粒度的权限检查由服务器中间件通过checkRoutePermission()调用 RBAC 完成见 auth-provider.ts。此外 Provider 还实现了getCurrentUser()从 Cookie 中解析会话并verifyToken换取用户、getUser()Cloud API 无/users/:id端点恒返回null等IUserProvider接口方法。五、Mastra Cloud 认证端点速查表文档给出了 Cloud 侧全部 6 个认证端点结合 session.ts 源码可补充请求方式与用途细节端点用途请求方式与关键头/auth/ossOAuth 授权重定向入口携带project_id、code_challenge、code_challenge_methodS256、redirect_uri、stateGET浏览器 302/auth/callback用授权码兑换访问令牌请求体含code、redirect_uri、code_verifierPOST需X-Project-ID/auth/verify令牌换取用户信息返回{ sub, email, name?, avatar_url?, role }POST需Authorization: Bearer与X-Project-ID/auth/session/validate校验会话有效性返回{ userId, expiresAt, createdAt }POST需Bearer与X-Project-ID/auth/session/destroy服务端登出销毁会话注意该端点不要求X-Project-IDPOST需Bearer/auth/logout登出重定向 URL拼接post_logout_redirect_uri与id_token_hintGET浏览器重定向其中/auth/verify对用户令牌与项目 API 令牌返回不同结构见 session.ts用户令牌返回完整用户信息项目 API 令牌返回{ valid: true, role: api, token_type: project_api_token }此时CloudUser.id被固定为api-token无 email/name/avatar。六、Cookie 生命周期管理文档以时间线形式给出了两类 Cookie 的完整生命周期源码细节如下Cookie名称TTL属性生命周期PKCE Cookiemastra_pkce_verifier5 分钟HttpOnly; SameSiteLax; Path/生产环境加Secure登录开始时写入含 verifier、state、expiresAt回调时读取并校验回调完成后立即清除会话 Cookiemastra_cloud_session24 小时HttpOnly; SameSiteLax; Path/生产环境加Secure回调成功后写入访问令牌每次请求读取并verifyToken登出时清除对应实现分别位于 pkce/cookie.ts 与 session/cookie.ts。MastraCloudAuth客户端对外提供setSessionCookie(token)/clearSessionCookie()生成 Set-Cookie 头值Provider 则通过getSessionHeaders()/getClearSessionHeaders()在登录、登出响应中落盘见 auth-provider.ts。会话模型的另外几个接口方法同样值得注意auth-provider.tscreateSession(userId, metadata)会话 id 默认取metadata.accessToken否则用crypto.randomUUID()过期时间为 24 小时validateSession(sessionId)调用 Cloud 的/auth/session/validate无效或网络异常均返回nulldestroySession(sessionId)调用/auth/session/destroy忽略响应体refreshSession(sessionId)Cloud 内部自行处理续期故仅委托给validateSession。七、RBAC角色到权限的映射与控制MastraRBACCloud实现IRBACProviderCloudUserrbac-provider.ts核心是一个可配置的roleMapping映射表import { MastraRBACCloud } from mastra/auth-cloud; const rbac new MastraRBACCloud({ roleMapping: { admin: [*], // 通配符全部权限 member: [agents:read, workflows:*], viewer: [agents:read, workflows:read], _default: [], // 无角色用户的兜底权限 }, }); const hasAccess await rbac.hasPermission(user, agents:read);关键方法的行为方法行为getRoles(user)返回[user.role]Cloud 是单角色模型或空数组getPermissions(user)有角色时按roleMapping解析权限无角色时返回_default映射hasPermission(user, perm)用通配符匹配判断单个权限hasAllPermissions(user, perms)全部权限满足才返回truehasAnyPermission(user, perms)任一权限满足即返回true权限匹配采用通配符规则如workflows:*匹配workflows:read、agents:read由admin: [*]覆盖该能力来自internal/auth/ee中的resolvePermissionsFromMapping与matchesPermission。测试用例中使用的映射表index.test.ts给出了更完整的角色示例owner: [*]、admin: [agents:*, workflows:*, tools:*, studio:*]、member与viewer均为细粒度只读/执行权限、_default: []。八、安全防护层次文档列出了六层安全设计结合源码可逐条印证PKCERFC 7636verifier 为 32 字节随机数的 base64urlchallenge 采用 S256 哈希防止授权码被截获后复用CSRF 防护state 参数内嵌 16 字节随机 CSRF 令牌回调时与 PKCE Cookie 中的 state 严格比对不匹配即抛state_mismatch开放重定向防护validateReturnTo()state.ts只允许两类returnTo——以/开头但不以//开头的相对路径排除协议相对 URL或与请求同源protocol host 一致的绝对 URL其余一律回退到/HttpOnly CookiePKCE 与会话 Cookie 均带HttpOnlyJS 无法读取令牌SameSiteLax默认附加提供基础 CSRF 缓解Secure 标志生产环境isProduction为 true 或NODE_ENV production自动追加Secure强制 HTTPS 传输。另外错误处理采用带code判别器的AuthError类error.ts覆盖invalid_state、state_mismatch、missing_code、token_exchange_failed、verification_failed、session_invalid、session_expired、network_error、cloud_api_error九种错误码便于上层中间件按码分类处理PKCE Cookie 解析失败则抛出专门的PKCEError。九、测试与验证仓库的 index.test.ts459 行对 RBAC 与 Provider 做了系统覆盖RBAC 部分为纯逻辑测试无需 mock覆盖getRoles、getPermissions含无角色走_default、hasPermission、hasAllPermissions、hasAnyPermission的通配符匹配Provider 部分通过vi.mock模拟./session/session与./oauth/oauth的网络依赖验证authenticateToken的 Cookie 优先 / Bearer 回退逻辑、handleCallback的 Cookie 拼装等。运行测试cd auth/cloud npm test十、小结mastra/auth-cloud用一套约十余个文件的精简实现oauth/、pkce/、session/、rbac/把登录委托、会话维持、权限判定三件核心工作完整闭环PKCE 保证授权码安全兑换HttpOnly SameSite Secure 的 Cookie 组合守护会话Bearer Token 回退兼容 API 客户端roleMapping通配符机制让权限模型可以按业务灵活裁剪。对于希望自托管 Mastra 服务、又不愿自建用户体系的团队这是一个开箱即用的云认证接入方案。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考