尧图网站建设 
Mastra mastra/auth-cloud将自托管服务器登录与会话管理委托给 Mastra Cloud 的 PKCE OAuth 方案【免费下载链接】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 项目自己只负责维护一个 HTTP-Only 会话 Cookie。读完本文你将掌握该包的完整接入方式、构造参数含义以及其底层 OAuth 2.0 PKCE 登录时序、Cookie 生命周期、Bearer Token 回退机制与 RBAC 权限映射的实现细节能够安全地在自己的 Mastra 应用中启用云端登录。一、包定位与安装mastra/auth-cloud通过 Proof Key for Code ExchangePKCEOAuth 流程在 Mastra Cloud 中完成用户认证。典型场景是你的 Mastra 服务是自托管的但希望复用 Mastra Cloud 项目的登录入口WorkOS 后端的账户体系与会话校验而无需自己搭建 IdP。安装方式见 auth/cloud/README.mdnpm install mastra/auth-cloud从 auth/cloud/package.json 可以看到几个运行前提当前版本为1.2.5type: module同时提供 ESM 与 CJS 产物dist/index.js/dist/index.cjs运行环境要求node 22.13.0生产依赖只有mastra/authworkspace 包并声明hono: ^4.0.0为 peerDependency说明其请求/响应抽象基于 Hono 风格的Request接口依赖了internal/auth中的抽象接口即该包是 Mastra 认证体系mastra/auth内部实现之上的一个云端实现。二、基本用法与构造参数使用前需要设置环境变量MASTRA_PROJECT_IDMastra Cloud 项目 ID然后在 Mastra 实例的server.auth上挂载MastraCloudAuthProviderimport { 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, }), }, });构造参数的完整定义在 MastraCloudAuthProviderOptions 中它继承自MastraAuthProviderOptionsCloudUser参数类型必填说明projectIdstring是Mastra Cloud 项目 ID请求 Cloud API 时作为X-Project-ID头发送cloudBaseUrlstring是Mastra Cloud API 的 Base URL例如https://cloud.mastra.aicallbackUrlstring是应用中注册好的 OAuth 回调绝对 URL必须与 Cloud 侧登记的一致isProductionboolean否为true时给认证 Cookie 加Secure属性不传时源码回退到process.env.NODE_ENV production判断见 client.ts 的 setSessionCookie其余通用项—否继承 Mastra 通用认证选项支持 public/protected 路由配置和自定义用户授权三、Provider 的类结构与公共 API从 auth/cloud/src/index.ts 可以看到包的公共导出面MastraCloudAuthProvider面向 Mastra 服务端的认证 Provider本文主角MastraCloudAuth底层 OAuth 会话客户端Provider 的引擎AuthError及AuthErrorCode认证过程错误类型MastraRBACCloud基于角色映射的 RBAC Provider数据类型CloudUser、CloudSession、VerifyResponse、CallbackResult、LoginUrlResult。MastraCloudAuthProvider的类声明见 auth-provider.ts为export class MastraCloudAuthProvider extends MastraAuthProviderCloudUser implements IUserProviderEEUser, ISSOProviderEEUser, ISessionProviderSession即它继承通用认证基类MastraAuthProvider同时实现用户IUserProvider、单点登录ISSOProvider、会话ISessionProvider三个接口从而被 Mastra 服务端认证中间件识别。构造时内部持有一个MastraCloudAuth客户端实例见 构造函数所有与 Cloud 的 HTTP 交互都通过该客户端完成。核心用户类型CloudUser见 types.ts字段为id项目 API Token 场景下为api-token、email、name、avatar、role角色来自/auth/verify端点而不是 JWT claims。四、登录流程PKCE 授权码模式逐步拆解仓库内架构文档 auth/cloud/cloud-auth.md 给出的高层流程是浏览器访问/login→ Provider 携带 PKCE 挑战重定向到 Cloud → 用户在 Cloud 完成登录 → Cloud 重定向回/callback→ Provider 交换授权码并验证 Token → 下发会话 Cookie。下面结合源码逐步说明每一步的实现。4.1 生成登录 URLgetLoginUrlMastraCloudAuthProvider.getLoginUrl见 auth-provider.ts负责从state参数中解出postLoginRedirect格式为uuid|encodedPostLoginRedirect取redirectUri的 origin然后调用底层getLoginUrloauth/oauth.ts后者做四件事生成 PKCE 密钥对generateCodeVerifier()使用 32 个随机字节编码为 base64url43 字符满足 RFC 7636 对 verifier 43–128 字符的要求computeCodeChallenge(verifier)计算BASE64URL(SHA256(verifier))即 S256 挑战方法见 pkce/pkce.ts。生成并编码 stategenerateState()产生 16 字节随机 CSRF tokenencodeState(csrf, returnTo)把{ csrf, returnTo }序列化为 JSON 后做 base64url 编码见 oauth/state.ts使同一个 OAuthstate参数同时承担 CSRF 防护与登录前跳转地址传递两个职责。防开放重定向validateReturnTo(returnTo, requestOrigin)只接受以/开头且非//的同源相对路径或与请求 origin 完全一致的绝对 URL否则一律回退为/见 state.ts。拼装授权 URL 与 PKCE Cookieconst url new URL(/auth/oss, cloudBaseUrl); url.searchParams.set(project_id, projectId); url.searchParams.set(code_challenge, challenge); url.searchParams.set(code_challenge_method, S256); url.searchParams.set(redirect_uri, callbackUrl); url.searchParams.set(state, state);同时生成名为mastra_pkce_verifier的 Cookie把verifier、csrfstate和过期时间序列化后 URL 编码写入属性为HttpOnly; SameSiteLax; Path/Max-Age为 5 分钟生产环境追加Secure见 pkce/cookie.ts。该 Cookie 必须在重定向响应中下发回调阶段用来取回 verifier 并核对 CSRF。getLoginCookiesauth-provider.ts通过 state 键从内部缓存_loginResults取出这些 Cookie 并立即删除防止竞态与内存泄漏缓存超过 100 条时会淘汰最早条目。4.2 处理回调handleCallback用户在 Cloud 完成认证后浏览器带着code与state回到callbackUrl。MastraCloudAuthProvider.handleCallback会先把服务端收到的原始Cookie头通过setCallbackCookieHeader()注入auth-provider.ts供 PKCE 校验使用。底层handleCallbackoauth/oauth.ts依次执行parsePKCECookie(cookieHeader)解析mastra_pkce_verifierCookie缺失、格式错误或过期expiresAt Date.now()分别抛出PKCEError的missingVerifier/invalid/expireddecodeState(state)解码 base64url 得到{ csrf, returnTo }解码失败抛AuthError.invalidState()比对stateData.csrf ! pkceData.state则抛AuthError.stateMismatch()完成 CSRF 校验向 Cloud 交换授权码POST {cloudBaseUrl}/auth/callback Headers: Content-Type: application/json, X-Project-ID: {projectId} Body: { code, redirect_uri, code_verifier }Cloud 成功时返回{ access_token, token_type, expires_in }失败时解析错误体中的code/message并抛AuthError.tokenExchangeFailed请求经由fetchWithRetry带重试发送。 5. 用 access token 换取用户信息POST {cloudBaseUrl}/auth/verify Headers: Authorization: Bearer {access_token}, X-Project-ID: {projectId}返回{ sub, email, name?, avatar_url?, role }映射为CloudUserid: subrole直接来自该端点。 6. 下发清除 PKCE Cookie 的响应头Max-Age0返回{ user, accessToken, returnTo, cookies }。Provider 层随后用client.setSessionCookie(result.accessToken)追加会话 Cookie把user、accessToken与全部 Cookie 合并返回见 handleCallback。4.3 每请求的认证Cookie 优先、Bearer 回退之后每个请求的鉴权在authenticateToken(token, request)中完成auth-provider.ts从请求cookie头解析mastra_cloud_sessionCookiesession/cookie.ts有会话 Cookie 时调verifyToken(sessionToken)到 Cloud 校验返回{ ...user, role }无 Cookie 时回退到Authorization: Bearer token同样走verifyToken服务浏览器 Cookie 之外的 API 客户端任一环节出错统一返回null源码注释说明这是有意的决策由上层中间件按未认证处理。authorizeUser仅做轻量校验!!user?.id细粒度权限交给服务端中间件的checkRoutePermission()。4.4 会话管理接口ISessionProvider各方法的云端实现auth-provider.tscreateSession(userId, metadata)仅做接口兼容id取metadata.accessToken否则随机 UUIDexpiresAt设为 24 小时后validateSession(sessionId)调用 Cloud 的validateSession无效/过期返回nulldestroySession(sessionId)调用 Cloud 的服务端登出接口销毁会话refreshSession(sessionId)Cloud 内部处理刷新这里等价于重新validateSessiongetSessionIdFromRequest(request)/getCurrentUser(request)从 Cookie 解析 token 并对后者向 Cloud 验证得到带角色的用户getSessionHeaders/getClearSessionHeaders生成Set-Cookie写入/清除mastra_cloud_sessiongetUser(userId)Cloud API 没有/users/:id端点恒返回nullauth-provider.ts。登出方面getLogoutUrl(redirectUri, request)先从请求 Cookie 提取会话 token 作为id_token_hint无活跃会话时返回null否则生成 Cloud 侧登出重定向 URLauth-provider.tsgetLoginButtonConfig返回登录按钮配置provider: mastra文案 Sign in with Mastra Cloud。五、Cookie 生命周期与安全层综合 pkce/cookie.ts 与 session/cookie.ts两个 Cookie 的生命周期为Cookie名称有效期写入时机清除时机PKCE 态 Cookiemastra_pkce_verifier5 分钟Max-Age300发起登录重定向时存 verifier CSRF 过期时间回调处理成功后以Max-Age0清除会话 Cookiemastra_cloud_session24 小时Max-Age86400回调换取 access token 成功后写入登出时以Max-Age0清除两个 Cookie 都固定携带HttpOnly; SameSiteLax; Path/isProduction或NODE_ENVproduction时追加Secure。cloud-auth.md 将安全层归纳为六点均可在源码中对应PKCES256verifier 只存在 HttpOnly Cookie 中回调时用code_verifier换取 token抵御授权码截获攻击CSRFstate 内嵌随机 token与 PKCE Cookie 中存的状态二次比对开放重定向防护returnTo强制同源校验HttpOnly两类敏感 Cookie 均不可被 JS 读取SameSiteLax降低跨站请求携带 Cookie 的风险Secure 标志生产环境仅经 HTTPS 传输 Cookie。六、Mastra Cloud 侧关键端点源码中实际调用到的 Cloud 端点如下与 cloud-auth.md 的端点表一致端点用途调用位置GET /auth/ossOAuth 授权重定向浏览器跳转目标oauth/oauth.tsPOST /auth/callback授权码 code_verifier 换 access tokenoauth/oauth.tsPOST /auth/verifytoken 换用户信息与角色登录回调及每请求验证均使用oauth/oauth.ts、auth-provider.tsPOST /auth/session/validate会话有效性校验经client.validateSession封装client.tsPOST /auth/session/destroy服务端登出、销毁会话经client.destroySession封装/auth/logout客户端侧登出重定向 URL经client.getLogoutUrl封装七、配套 RBACMastraRBACCloud包还导出了面向 Cloud 单角色模型的 RBAC ProviderMastraRBACCloudrbac/rbac-provider.ts通过roleMapping把/auth/verify返回的角色翻译成 Mastra 权限字符串支持通配符匹配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.role ? [user.role] : []——Cloud 采用单角色模型源码注释明确其比 WorkOS 多角色 RBAC 更简单用户无角色时getPermissions回退到roleMapping[_default] ?? []hasPermission/hasAllPermissions/hasAnyPermission均基于通配符匹配函数matchesPermissionroleMapping通过 getter 暴露给中间件便于同步解析权限而无需调用异步方法。八、接入注意事项小结callbackUrl必须是绝对 URL 且与 Cloud 项目登记一致它是授权 URL 中redirect_uri与换码请求中redirect_uri的唯一来源生产环境务必保证isProduction为真或设置NODE_ENVproduction使 Cookie 带Secure属性PKCE Cookie 只有 5 分钟 TTL用户若长时间停留在 Cloud 登录页会导致回调时 PKCE 过期PKCEError.expiredauthenticateToken出错时静默返回null意味着 Cloud 不可达时所有请求都会按未认证处理而非 5xx监控上需留意getUser不支持按 ID 查询依赖按用户 ID 取用户的自定义逻辑需要自行实现包声明hono: ^4.0.0为 peer 依赖并要求 Node ≥ 22.13.0接入前需确认运行环境满足。参考入口auth/cloud/README.md、auth/cloud/cloud-auth.md、auth/cloud/src/auth-provider.ts、auth/cloud/src/index.ts。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra @mastra/auth-cloud：将自托管服务器登录与会话管理委托给 Mastra Cloud 的 PKCE OAuth 方案
Mastra mastra/auth-cloud将自托管服务器登录与会话管理委托给 Mastra Cloud 的 PKCE OAuth 方案【免费下载链接】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 项目自己只负责维护一个 HTTP-Only 会话 Cookie。读完本文你将掌握该包的完整接入方式、构造参数含义以及其底层 OAuth 2.0 PKCE 登录时序、Cookie 生命周期、Bearer Token 回退机制与 RBAC 权限映射的实现细节能够安全地在自己的 Mastra 应用中启用云端登录。一、包定位与安装mastra/auth-cloud通过 Proof Key for Code ExchangePKCEOAuth 流程在 Mastra Cloud 中完成用户认证。典型场景是你的 Mastra 服务是自托管的但希望复用 Mastra Cloud 项目的登录入口WorkOS 后端的账户体系与会话校验而无需自己搭建 IdP。安装方式见 auth/cloud/README.mdnpm install mastra/auth-cloud从 auth/cloud/package.json 可以看到几个运行前提当前版本为1.2.5type: module同时提供 ESM 与 CJS 产物dist/index.js/dist/index.cjs运行环境要求node 22.13.0生产依赖只有mastra/authworkspace 包并声明hono: ^4.0.0为 peerDependency说明其请求/响应抽象基于 Hono 风格的Request接口依赖了internal/auth中的抽象接口即该包是 Mastra 认证体系mastra/auth内部实现之上的一个云端实现。二、基本用法与构造参数使用前需要设置环境变量MASTRA_PROJECT_IDMastra Cloud 项目 ID然后在 Mastra 实例的server.auth上挂载MastraCloudAuthProviderimport { 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, }), }, });构造参数的完整定义在 MastraCloudAuthProviderOptions 中它继承自MastraAuthProviderOptionsCloudUser参数类型必填说明projectIdstring是Mastra Cloud 项目 ID请求 Cloud API 时作为X-Project-ID头发送cloudBaseUrlstring是Mastra Cloud API 的 Base URL例如https://cloud.mastra.aicallbackUrlstring是应用中注册好的 OAuth 回调绝对 URL必须与 Cloud 侧登记的一致isProductionboolean否为true时给认证 Cookie 加Secure属性不传时源码回退到process.env.NODE_ENV production判断见 client.ts 的 setSessionCookie其余通用项—否继承 Mastra 通用认证选项支持 public/protected 路由配置和自定义用户授权三、Provider 的类结构与公共 API从 auth/cloud/src/index.ts 可以看到包的公共导出面MastraCloudAuthProvider面向 Mastra 服务端的认证 Provider本文主角MastraCloudAuth底层 OAuth 会话客户端Provider 的引擎AuthError及AuthErrorCode认证过程错误类型MastraRBACCloud基于角色映射的 RBAC Provider数据类型CloudUser、CloudSession、VerifyResponse、CallbackResult、LoginUrlResult。MastraCloudAuthProvider的类声明见 auth-provider.ts为export class MastraCloudAuthProvider extends MastraAuthProviderCloudUser implements IUserProviderEEUser, ISSOProviderEEUser, ISessionProviderSession即它继承通用认证基类MastraAuthProvider同时实现用户IUserProvider、单点登录ISSOProvider、会话ISessionProvider三个接口从而被 Mastra 服务端认证中间件识别。构造时内部持有一个MastraCloudAuth客户端实例见 构造函数所有与 Cloud 的 HTTP 交互都通过该客户端完成。核心用户类型CloudUser见 types.ts字段为id项目 API Token 场景下为api-token、email、name、avatar、role角色来自/auth/verify端点而不是 JWT claims。四、登录流程PKCE 授权码模式逐步拆解仓库内架构文档 auth/cloud/cloud-auth.md 给出的高层流程是浏览器访问/login→ Provider 携带 PKCE 挑战重定向到 Cloud → 用户在 Cloud 完成登录 → Cloud 重定向回/callback→ Provider 交换授权码并验证 Token → 下发会话 Cookie。下面结合源码逐步说明每一步的实现。4.1 生成登录 URLgetLoginUrlMastraCloudAuthProvider.getLoginUrl见 auth-provider.ts负责从state参数中解出postLoginRedirect格式为uuid|encodedPostLoginRedirect取redirectUri的 origin然后调用底层getLoginUrloauth/oauth.ts后者做四件事生成 PKCE 密钥对generateCodeVerifier()使用 32 个随机字节编码为 base64url43 字符满足 RFC 7636 对 verifier 43–128 字符的要求computeCodeChallenge(verifier)计算BASE64URL(SHA256(verifier))即 S256 挑战方法见 pkce/pkce.ts。生成并编码 stategenerateState()产生 16 字节随机 CSRF tokenencodeState(csrf, returnTo)把{ csrf, returnTo }序列化为 JSON 后做 base64url 编码见 oauth/state.ts使同一个 OAuthstate参数同时承担 CSRF 防护与登录前跳转地址传递两个职责。防开放重定向validateReturnTo(returnTo, requestOrigin)只接受以/开头且非//的同源相对路径或与请求 origin 完全一致的绝对 URL否则一律回退为/见 state.ts。拼装授权 URL 与 PKCE Cookieconst url new URL(/auth/oss, cloudBaseUrl); url.searchParams.set(project_id, projectId); url.searchParams.set(code_challenge, challenge); url.searchParams.set(code_challenge_method, S256); url.searchParams.set(redirect_uri, callbackUrl); url.searchParams.set(state, state);同时生成名为mastra_pkce_verifier的 Cookie把verifier、csrfstate和过期时间序列化后 URL 编码写入属性为HttpOnly; SameSiteLax; Path/Max-Age为 5 分钟生产环境追加Secure见 pkce/cookie.ts。该 Cookie 必须在重定向响应中下发回调阶段用来取回 verifier 并核对 CSRF。getLoginCookiesauth-provider.ts通过 state 键从内部缓存_loginResults取出这些 Cookie 并立即删除防止竞态与内存泄漏缓存超过 100 条时会淘汰最早条目。4.2 处理回调handleCallback用户在 Cloud 完成认证后浏览器带着code与state回到callbackUrl。MastraCloudAuthProvider.handleCallback会先把服务端收到的原始Cookie头通过setCallbackCookieHeader()注入auth-provider.ts供 PKCE 校验使用。底层handleCallbackoauth/oauth.ts依次执行parsePKCECookie(cookieHeader)解析mastra_pkce_verifierCookie缺失、格式错误或过期expiresAt Date.now()分别抛出PKCEError的missingVerifier/invalid/expireddecodeState(state)解码 base64url 得到{ csrf, returnTo }解码失败抛AuthError.invalidState()比对stateData.csrf ! pkceData.state则抛AuthError.stateMismatch()完成 CSRF 校验向 Cloud 交换授权码POST {cloudBaseUrl}/auth/callback Headers: Content-Type: application/json, X-Project-ID: {projectId} Body: { code, redirect_uri, code_verifier }Cloud 成功时返回{ access_token, token_type, expires_in }失败时解析错误体中的code/message并抛AuthError.tokenExchangeFailed请求经由fetchWithRetry带重试发送。 5. 用 access token 换取用户信息POST {cloudBaseUrl}/auth/verify Headers: Authorization: Bearer {access_token}, X-Project-ID: {projectId}返回{ sub, email, name?, avatar_url?, role }映射为CloudUserid: subrole直接来自该端点。 6. 下发清除 PKCE Cookie 的响应头Max-Age0返回{ user, accessToken, returnTo, cookies }。Provider 层随后用client.setSessionCookie(result.accessToken)追加会话 Cookie把user、accessToken与全部 Cookie 合并返回见 handleCallback。4.3 每请求的认证Cookie 优先、Bearer 回退之后每个请求的鉴权在authenticateToken(token, request)中完成auth-provider.ts从请求cookie头解析mastra_cloud_sessionCookiesession/cookie.ts有会话 Cookie 时调verifyToken(sessionToken)到 Cloud 校验返回{ ...user, role }无 Cookie 时回退到Authorization: Bearer token同样走verifyToken服务浏览器 Cookie 之外的 API 客户端任一环节出错统一返回null源码注释说明这是有意的决策由上层中间件按未认证处理。authorizeUser仅做轻量校验!!user?.id细粒度权限交给服务端中间件的checkRoutePermission()。4.4 会话管理接口ISessionProvider各方法的云端实现auth-provider.tscreateSession(userId, metadata)仅做接口兼容id取metadata.accessToken否则随机 UUIDexpiresAt设为 24 小时后validateSession(sessionId)调用 Cloud 的validateSession无效/过期返回nulldestroySession(sessionId)调用 Cloud 的服务端登出接口销毁会话refreshSession(sessionId)Cloud 内部处理刷新这里等价于重新validateSessiongetSessionIdFromRequest(request)/getCurrentUser(request)从 Cookie 解析 token 并对后者向 Cloud 验证得到带角色的用户getSessionHeaders/getClearSessionHeaders生成Set-Cookie写入/清除mastra_cloud_sessiongetUser(userId)Cloud API 没有/users/:id端点恒返回nullauth-provider.ts。登出方面getLogoutUrl(redirectUri, request)先从请求 Cookie 提取会话 token 作为id_token_hint无活跃会话时返回null否则生成 Cloud 侧登出重定向 URLauth-provider.tsgetLoginButtonConfig返回登录按钮配置provider: mastra文案 Sign in with Mastra Cloud。五、Cookie 生命周期与安全层综合 pkce/cookie.ts 与 session/cookie.ts两个 Cookie 的生命周期为Cookie名称有效期写入时机清除时机PKCE 态 Cookiemastra_pkce_verifier5 分钟Max-Age300发起登录重定向时存 verifier CSRF 过期时间回调处理成功后以Max-Age0清除会话 Cookiemastra_cloud_session24 小时Max-Age86400回调换取 access token 成功后写入登出时以Max-Age0清除两个 Cookie 都固定携带HttpOnly; SameSiteLax; Path/isProduction或NODE_ENVproduction时追加Secure。cloud-auth.md 将安全层归纳为六点均可在源码中对应PKCES256verifier 只存在 HttpOnly Cookie 中回调时用code_verifier换取 token抵御授权码截获攻击CSRFstate 内嵌随机 token与 PKCE Cookie 中存的状态二次比对开放重定向防护returnTo强制同源校验HttpOnly两类敏感 Cookie 均不可被 JS 读取SameSiteLax降低跨站请求携带 Cookie 的风险Secure 标志生产环境仅经 HTTPS 传输 Cookie。六、Mastra Cloud 侧关键端点源码中实际调用到的 Cloud 端点如下与 cloud-auth.md 的端点表一致端点用途调用位置GET /auth/ossOAuth 授权重定向浏览器跳转目标oauth/oauth.tsPOST /auth/callback授权码 code_verifier 换 access tokenoauth/oauth.tsPOST /auth/verifytoken 换用户信息与角色登录回调及每请求验证均使用oauth/oauth.ts、auth-provider.tsPOST /auth/session/validate会话有效性校验经client.validateSession封装client.tsPOST /auth/session/destroy服务端登出、销毁会话经client.destroySession封装/auth/logout客户端侧登出重定向 URL经client.getLogoutUrl封装七、配套 RBACMastraRBACCloud包还导出了面向 Cloud 单角色模型的 RBAC ProviderMastraRBACCloudrbac/rbac-provider.ts通过roleMapping把/auth/verify返回的角色翻译成 Mastra 权限字符串支持通配符匹配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.role ? [user.role] : []——Cloud 采用单角色模型源码注释明确其比 WorkOS 多角色 RBAC 更简单用户无角色时getPermissions回退到roleMapping[_default] ?? []hasPermission/hasAllPermissions/hasAnyPermission均基于通配符匹配函数matchesPermissionroleMapping通过 getter 暴露给中间件便于同步解析权限而无需调用异步方法。八、接入注意事项小结callbackUrl必须是绝对 URL 且与 Cloud 项目登记一致它是授权 URL 中redirect_uri与换码请求中redirect_uri的唯一来源生产环境务必保证isProduction为真或设置NODE_ENVproduction使 Cookie 带Secure属性PKCE Cookie 只有 5 分钟 TTL用户若长时间停留在 Cloud 登录页会导致回调时 PKCE 过期PKCEError.expiredauthenticateToken出错时静默返回null意味着 Cloud 不可达时所有请求都会按未认证处理而非 5xx监控上需留意getUser不支持按 ID 查询依赖按用户 ID 取用户的自定义逻辑需要自行实现包声明hono: ^4.0.0为 peer 依赖并要求 Node ≥ 22.13.0接入前需确认运行环境满足。参考入口auth/cloud/README.md、auth/cloud/cloud-auth.md、auth/cloud/src/auth-provider.ts、auth/cloud/src/index.ts。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考