Mastra mastra/auth-better-auth Better Auth 认证 Provider版本演进全解与源码机制剖析【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/auth-better-auth是 Mastra 用于对接自托管认证框架 Better Auth 的认证 Provider 包。本文以 auth/better-auth/CHANGELOG.md 的完整版本史为主线逐版梳理从 1.0.0-beta.1 到 1.1.5 的能力演进并结合 auth/better-auth/src/index.ts 的实现源码深入解析延迟实例模式、Bearer Token 会话签名、组织管理与默认组织解析等关键机制的底层原理。读完本文你将掌握该 Provider 的接入方式、各版本关键变更的实际影响以及每个变更对应的源码级证据。一、包的定位与基础接入1.0.0 初版形态Better Auth 是一个自托管、开源的 TypeScript 认证框架。mastra/auth-better-auth将其接入 Mastra 的服务端认证层server.auth让你在不依赖托管身份提供商的前提下用自己完全掌控的认证系统为 Mastra 应用做鉴权。包的安装方式见 auth/better-auth/README.mdnpm install mastra/auth-better-auth npm install better-auth1.0.0 版本对应 CHANGELOG 中 “Add Better Auth authentication provider” 条目确立了最基础的接入形态自行创建betterAuth()实例再把它交给 Mastra Providerimport { betterAuth } from better-auth; import { MastraAuthBetterAuth } from mastra/auth-better-auth; import { Mastra } from mastra/core; // Create your Better Auth instance const auth betterAuth({ database: { provider: postgresql, url: process.env.DATABASE_URL!, }, emailAndPassword: { enabled: true, }, }); // Create the Mastra auth provider const mastraAuth new MastraAuthBetterAuth({ auth, }); // Use with Mastra const mastra new Mastra({ server: { auth: mastraAuth, }, });初版1.0.0-beta.1 的发布说明列出的能力清单是自托管认证、基于会话的认证、自定义授权逻辑、以及公开/受保护路径的路由配置。此后每个版本的演进都在这份能力基线上叠加新特性下文按时间线完整展开。二、版本演进主线1.0.0-beta.1 → 1.1.52.1 1.0.x 系列从会话认证到凭据流版本关键变更1.0.0-beta.1首次发布自托管认证、会话认证、自定义授权、公开/受保护路径配置1.0.0正式添加 Better Auth 认证 Provider上文完整示例1.0.1依赖升级better-auth从^1.4.5升到^1.4.181.0.2实现mastra/core/auth的新认证接口IUserProvider、ISessionProvider、ICredentialsProvider在既有 Token 认证之外新增用户名/密码凭据流1.0.3从mastra/core与 auth 包运行时依赖中移除 Hono认证 Provider 改为接收框架无关的请求类型支持标准Request与 Hono 兼容形态1.0.4安全补救发布针对 “easy-day-js” 供应链事件发布干净版本并前移latestdist-tag取代声明了恶意easy-day-js依赖的被污染版本1.1.0版本对齐mastra/core1.45.0的小版本升级1.1.1构建改进从 auth Provider 中移除对 core 的直接依赖同时保留既有公开认证 API1.0.2 的凭据流从源码看MastraAuthBetterAuth实现了signIn(email, password, request)与signUp(email, password, name, request)两个方法auth/better-auth/src/index.ts#L747-L834。两者都通过this.auth.api.signInEmail/signUpEmail并显式传入asResponse: true以便从响应中取出完整的Set-Cookie头返回结构是{ user, token, cookies }其中user经过mapBetterAuthUserToEEUser映射为 Mastra 的 EE User 形态。1.0.3 的框架无关化CHANGELOG 说明 MCP 与 deployer 不再在包边界上依赖 core 捆绑的 Hono context 类型。对应实现是 packages/core/src/server/request-types.ts#L17-L23 中的getRequestHeader辅助函数export type MastraAuthRequest Request | HonoRequestLike; export function getRequestHeader(request: MastraAuthRequest, name: string): string | null { if (request instanceof Request) { return request.headers.get(name); } return request.raw?.headers.get(name) ?? request.headers?.get(name) ?? request.header(name) ?? null; }它按“标准Request→ Hono 风格raw/headers/header()”的优先级逐级兜底读取请求头。MastraAuthBetterAuth.authenticateToken正是通过它读取Cookie头auth/better-auth/src/index.ts#L680-L683这也是 1.1.4 修复 Express 场景问题时的着力点。1.0.4 的供应链事件CHANGELOG 明确记录了这是一次安全补救发布Patch bump 前移latestdist-tag用于取代声明了恶意easy-day-js依赖的被污染版本。对于依赖该包的项目这是一个值得注意的版本事实升级到 1.0.4 及之后版本可确保不继承被污染的依赖声明。2.2 1.1.x 系列延迟实例、组织管理与多项认证修复版本关键变更1.1.2① 新增“延迟实例模式”与组织管理Provider 可直接交给服务器宿主无需包装适配器② 最低better-auth版本提到 1.6.13以引入其 OIDC Provider 与 MCP 插件中存储型 XSS 漏洞GHSA-86j7-9j95-vpqj的修复③ 修复 Bearer Token 认证并真正实现getUser()/getUsers()1.1.3依赖升级better-auth从^1.6.13升到^1.6.231.1.4① 当存储的会话没有activeOrganizationId时从用户最早的既有成员关系解析默认值② 修复从 Express 风格普通头对象读取请求头的问题Cookie 认证不再以误导性的 401 失败1.1.5文档与包体积维护更新 README把CHANGELOG.md从 npm 发布文件中移除以减小包体积1.1.2 是功能上最重要的一版下面三节按源码逐一展开。三、源码深潜延迟实例模式与组织管理1.1.23.1 两种构造形态1.1.2 之前构造 Provider 必须自带betterAuth()实例即 CHANGELOG 中的Before形态。1.1.2 之后支持延迟实例模式deferred instance mode只传secretProvider 会在宿主调用的init()阶段基于宿主提供的认证数据库自行构建 Better Auth 实例含执行迁移// Before自带实例 import { betterAuth } from better-auth; import { MastraAuthBetterAuth } from mastra/auth-better-auth; const auth new MastraAuthBetterAuth({ auth: betterAuth({ /* ... */ }) });// After延迟实例模式自带实例的旧用法依然兼容 import { MastraAuthBetterAuth } from mastra/auth-better-auth; const auth new MastraAuthBetterAuth({ secret: process.env.BETTER_AUTH_SECRET! }); // 宿主在启动时调用 auth.init({ database, publicUrl, allowedOrigins })源码中的构造约束是“auth与secret至少提供一个”否则直接抛错auth/better-auth/src/index.ts#L210-L225。内部通过#ownsInstance标记区分两种形态只有 Provider 自己构建实例时才由它负责 schema 迁移自带实例的宿主则自行管理数据库与迁移auth/better-auth/src/index.ts#L265-L339 的注释明确了这一职责划分。3.2 init()实例构建与数据库方言映射init(ctx: AuthInitContext)的核心逻辑auth/better-auth/src/index.ts#L274-L320跨站检测ctx.allowedOrigins非空时置#crossSite true后续构建会话 Cookie 时会附加SameSiteNone; Secure方言映射宿主传入的“带标签”认证数据库句柄按方言映射为 better-auth 的database选项——postgres直接复用连接池libsql经libsql/kysely-libsql的 Kysely 方言包装为 SQLite 形态其余形态原样透传给宿主负责兼容性固定 basePath所有 Provider 端点sign-in/up/out/session都挂在/auth/api下宿主把handleAuthRequest挂载到该路径即可信任来源把allowedOrigins转发为 better-auth 的trustedOrigins。源码注释特别强调SameSiteNone只解决浏览器“愿意发送 Cookie”的问题better-auth 仍会拒绝来源不在信任列表内的请求因此跨域 SPA 部署必须同时把 SPA 来源配置为可信注册能力无条件启用emailAndPassworddisableSignUp由signUpEnabled选项控制默认true允许注册并注册 better-auth 的organization()插件——这正是会话上activeOrganizationId字段的来源。迁移由#ensureDbReady()以“每进程一次”的 Promise 闩锁惰性执行失败时会重置闩锁以便后续调用重试并打印警告auth/better-auth/src/index.ts#L326-L339。handleAuthRequest是暴露给宿主的 HTTP 代理迁移不可用时返回503 auth_unavailable否则把原始请求转发给this.auth.handler(request)auth/better-auth/src/index.ts#L349-L359。延迟实例模式的行为有专门的测试文件 auth/better-auth/src/deferred.test.ts 覆盖构造时缺auth/secret抛错、init()前访问实例抛错、无数据库时快速失败、以及“构建的实例挂/auth/api并信任宿主来源”等断言。3.3 组织管理ensureOrganization 与 isOrganizationAdmin1.1.2 同时引入了组织管理能力CHANGELOG 点名了两个方法ensureOrganization(userId)auth/better-auth/src/index.ts#L418-L504为新用户引导个人组织。逻辑是“幂等 防抢占”已有 ≥1 个成员关系 → 直接返回最早的组织 id无成员关系 → 用personal-userId作为唯一 slug 创建名为email|name|ids org的个人组织并以owner角色挂接成员。并发或重试的首次登录会通过唯一 slug 冲突恢复而不是创建重复组织安全细节仅凭 slug 命中不足以证明归属组织 API 对任何已认证用户可达攻击者理论上可抢占personal-victimId。因此 slug 命中的组织只有在“没有他人是成员”时才被采纳否则回退到带crypto.randomUUID()后缀的不可猜测 slug 新建整体是 best-effort任何失败都被吞掉并打印警告用户处于“无组织”状态直到引导成功。isOrganizationAdmin(organizationId, userId)auth/better-auth/src/index.ts#L510-L526通过内部 adapter 查成员角色owner或admin返回trueProvider 错误一律解析为false。四、源码深潜Bearer Token 认证与会话 Cookie 签名1.1.2CHANGELOG 1.1.2 记录了两个此前长期存在的问题问题一Bearer Token 认证始终失败。signIn/signUp返回的是 Better Auth 的原始未签名会话 token而 Better Auth 只接受签名会话 Cookie格式为token.HMAC-SHA256 签名。直接把原始 token 放进Authorization: Bearer token之前总是认证失败。修复方案与 Better Auth 的 bearer 插件语义对齐Provider 在验证会话前先用实例 secret 给未签名 token 补签better-auth/crypto的makeSignature。对应实现在ensureSessionCookieauth/better-auth/src/index.ts#L637-L659// 含 . 的 token 视为已签名可能 URI 编码 let cookieValue token.includes(.) ? (token.includes(%) ? tryDecode(token) : token) : token; if (!token.includes(.) secret) { cookieValue ${token}.${await makeSignature(token, secret)}; }同时会话 Cookie 名从 Better Auth 实例解析ctx?.authCookies.sessionToken.name回退到sessionCookieNamegetterauth/better-auth/src/index.ts#L245-L259——它按“advanced.cookies.session_token.name显式改名 ${cookiePrefix}.session_token 默认better-auth.session_token”解析并根据 secure Cookie 生效与否useSecureCookies或baseURL以https://开头决定是否加__Secure-前缀。这样__Secure-前缀的部署也能正确工作。问题二getUser()/getUsers()曾是恒返回null的桩破坏了 Studio 的用户查询与作者信息补全。现在getUser通过 Better Auth 内部 adapterinternalAdapter.findUserById按 id 解析用户getUsers基于它做批量查询auth/better-auth/src/index.ts#L584-L606。测试覆盖相当完整auth/better-auth/src/index.test.ts未签名 Bearer token 会被用实例 secret 补签、自定义cookiePrefix、__Secure-前缀的会话名、已存在 Cookie 时不重复注入、以及“Cookie 值中恰好包含会话名”的边界情形均有断言。五、源码深潜默认组织解析1.1.4CHANGELOG 1.1.4 描述了这样一个缺陷默认登录流程中的任何环节都不会调用 organization 插件的setActive导致存储的会话里activeOrganizationId恒为null组织维度的消费方看到的所有用户都“没有组织”。修复策略authenticateToken中的兜底auth/better-auth/src/index.ts#L696-L706会话验证成功后若session.activeOrganizationId为空则调用#resolveActiveOrganizationId(userId)该方法走#findMembershipOrgId按createdAt升序查询member表取最早的既有成员关系对应的组织 id保证多组织用户跨进程解析稳定auth/better-auth/src/index.ts#L370-L401解析结果只回填到返回的 session 对象上不写回数据库会话行——CHANGELOG 称之为“只读、尽力而为”无成员关系的用户照常认证查询失败则回退到修复前行为。CHANGELOG 还列出了明确的注意事项使用方必须了解解析值是推断的默认值不是用户的显式选择通过setActive被主动清空活跃组织的会话与从未设置的会话无法区分二者都会拿到默认值解析结果缓存在进程内TTL 为 60 秒ORG_CACHE_TTL_MS 60_000auth/better-auth/src/index.ts#L91-L200所以管理员移除某个成员关系后约一分钟内新会话即不再应用该组织映射。缓存只在成功时写入无成员关系的用户每次请求都会重查写入时按过期序清扫均摊 O(1)。六、源码深潜Express 风格头对象读取修复1.1.4CHANGELOG 1.1.4 的另一项修复读取 Express 风格普通头对象plain header object的请求头时出错导致基于 Cookie 的认证“抛异常并以误导性的 401 失败”。该修复依赖 1.0.3 引入的框架无关请求抽象。如第二节所示getRequestHeaderpackages/core/src/server/request-types.ts#L17-L23对非标准Request形态按raw→headers→header()逐级兜底authenticateToken读 Cookie 头、signIn/signUp读请求头时都走这一通道auth/better-auth/src/index.ts#L673-L715。修复后的效果是在 Express 等框架适配层传入普通头对象时Cookie 能被正确提取并交给auth.api.getSession不再因取头失败而误报 401。七、版本前提、依赖与安全注意事项从 auth/better-auth/package.json 可以确认当前仓库状态的适用前提当前版本1.1.5files只发布dist印证 1.1.5 “CHANGELOG.md 移出 npm 发布文件”的说明运行时依赖better-auth^1.6.231.1.3 从^1.6.13升级而来、libsql/kysely-libsql^0.4.1peer 依赖hono^4.0.0Node 引擎22.13.0。结合 CHANGELOG 的两条安全相关条目升级时值得记住的版本下限1.1.2 起最低 better-auth 为 1.6.13用于修复 better-auth OIDC Provider 与 MCP 插件中的存储型 XSS 漏洞GHSA-86j7-9j95-vpqj1.0.4 是供应链事件的补救版本早于它的版本可能携带被污染的easy-day-js依赖声明。八、小结mastra/auth-better-auth的版本史清晰地呈现了三个阶段1.0.x 完成基础接入会话认证 → 凭据流 → 框架无关化并经历一次供应链安全补救1.1.2 是能力跃迁点延迟实例模式让 Provider 可以零包装直接交给宿主同时补上了 Bearer Token 认证与用户查询两块短板1.1.4/1.1.5 则聚焦组织语义的默认解析、跨框架头读取兼容与发布维护。所有关键结论均可在 auth/better-auth/src/index.ts、auth/better-auth/src/index.test.ts、auth/better-auth/src/deferred.test.ts 与 auth/better-auth/CHANGELOG.md 中逐条对应验证。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考