Medusa auth-emailpass 认证 Provider 演进全解从版本历史到 Email/Password 认证实现剖析【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa导读本文以medusajs/auth-emailpass的 CHANGELOG.md 为主线结合该 Provider 的源码、类型定义与集成测试系统讲解 Medusa 邮件/密码认证 Provider 从 2.0 到 2.20.1 的演进脉络以及其底层实现原理。读完本文你将理解 emailpass Provider 在 Medusa 认证体系中的定位、注册/登录/改密的完整调用链、hashConfig等关键配置参数的含义以及 CHANGELOG 中每个关键变更背后的代码依据。一、包定位Medusa 认证模块的可插拔 Providermedusajs/auth-emailpass是 Medusa 2.x 认证模块Modules.AUTH的可插拔 Provider 实现负责邮箱 密码这一最常见的凭据认证方式。它的包描述为Email and password credential authentication provider for Medusa见 package.json要求 Node.js 20依赖scrypt-kdf完成密码散列并以medusajs/framework作为 peerDependency。在 Medusa 的 Provider 生态中与它并列的还有 auth-github、auth-google、auth-oidc 等它们共享同一套抽象接口注册时通过 index.ts 将服务注册为Modules.AUTH下的一个 ModuleProviderimport { ModuleProvider, Modules } from medusajs/framework/utils import { EmailPassAuthService } from ./services/emailpass const services [EmailPassAuthService] export default ModuleProvider(Modules.AUTH, { services, })核心服务EmailPassAuthService继承自框架的AbstractAuthModuleProvider见 emailpass.ts静态标识符为emailpass显示名为Email/Password Authentication并实现authenticate、register、update三个核心方法。二、版本演进时间线CHANGELOG 里的关键节点CHANGELOG 记录了该包自 2.0.0 以来的所有发布绝大多数为跟随medusajs/framework的依赖升级Patch Changes但有几个版本携带了真正的功能变更是理解该 Provider 能力边界的关键版本变更类型内容要点2.0.0Major随 Medusa 2.0 发布PR #7341作为新认证模块的 Provider 引入2.6.1Patch移除 Medusa 包上的版本区间PR #11738依赖策略收紧2.11.0Patch修复相同邮箱身份错误处理提升重复注册场景的健壮性PR #135372.11.3Patch依赖清理与改进PR #139102.15.5Patch为 emailpass 增加认证验证原语PR #154962.16.0Minor按 actor 类型要求验证feat: require verification by actor type2.17.2Patch补充包 bugs 元数据PR #156832.20.1Patch最新版本同步medusajs/framework2.20.1从结构上看该包的版本号始终与medusajs/framework保持一致如 2.20.1 对应 framework 2.20.1说明它作为框架级 Provider 与核心同步发版、紧随框架 API 变化。值得关注的功能性变更2.16.0 - 按 actor 类型要求验证CHANGELOG 记录为feat(auth-emailpass, types, medusa): require verification by actor type。这意味着验证verification策略不再一刀切而是可以针对不同 actor如用户、管理员等分别配置是否必须完成验证。该能力与 auth 模块的验证体系直接相关。2.15.5 - 认证验证原语Add auth verification primitives for emailpass。这是验证能力的基础建设为后续按 actor 类型验证提供了底层原语。2.11.0 - 相同邮箱身份处理优化fix(auth-emailpass): better handle identity with same email error。该修复与register方法中邮箱已存在的判定逻辑强相关详见下文第五节。三、源码实现三大核心方法与密码散列3.1 密码散列Scrypt 可配置参数hashPassword方法emailpass.ts使用scrypt-kdf库对明文密码进行散列并将结果以 base64 字符串存储protected async hashPassword(password: string) { const hashConfig this.config_.hashConfig ?? { logN: 15, r: 8, p: 1 } const passwordHash await Scrypt.kdf(password, hashConfig) return passwordHash.toString(base64) }这里直接体现了hashConfig配置项的作用。其类型定义位于 packages/core/types/src/auth/providers/emailpass.tsexport interface EmailPassAuthProviderOptions { hashConfig?: { logN: number r: number p: number } }参数含义logNCPU/内存成本参数以 2 为底的对数默认15越大越慢越安全r块大小参数默认8p并行化参数默认1。未配置hashConfig时使用默认值{ logN: 15, r: 8, p: 1 }。集成测试 services.spec.ts 中同样使用该默认配置生成密码散列来验证认证逻辑说明这是官方推荐的默认强度。3.2 authenticate验证凭据authenticate方法emailpass.ts的核心流程输入校验从userData.body取出email和password两者缺失或非字符串时分别返回Email should be a string/Password should be a string按邮箱检索身份调用authIdentityService.retrieve({ entity_id: email })若抛出MedusaError.Types.NOT_FOUND统一返回Invalid email or password——这是防枚举攻击的标准做法不暴露该邮箱是否已注册提取 Provider 身份从authIdentity.provider_identities中找到provider emailpass的条目取出provider_metadata.passwordbase64 编码的散列校验密码Buffer.from(passwordHash, base64)还原字节后调用Scrypt.verify(buf, password)比对返回结果成功时返回success: true与经过脱敏的authIdentity失败则返回Invalid email or password。注意成功返回前会调用sanitizeAuthIdentity_从返回结果中删除provider_metadata.password确保密码散列绝不泄漏到上层调用方emailpass.ts。3.3 register注册与可认领身份register方法emailpass.ts逻辑上分为两条路径邮箱不存在捕获NOT_FOUND后走create分支创建新的 AuthIdentityentity_id即邮箱provider_metadata.password为散列值邮箱已存在但尚未被认领若identity.app_metadata未定义或为空!isPresent(identity.app_metadata)说明该身份尚未绑定任何 actor用户/管理员等此时走update分支直接接管并更新密码返回success: true。这一可认领claimable设计在源码注释中写得很清楚If app_metadata is not defined or empty, it means no actor was assigned to the auth_identity yet (still claimable)邮箱已存在且已被认领app_metadata非空返回success: false错误信息为Identity with email already exists。upsertAuthIdentityemailpass.ts统一处理 create/update 两种情形且在update时会先读取原有provider_metadata再合并写入新密码因此原有自定义元数据如测试中的custom: keep-me不会丢失。这正是 2.11.0 变更better handle identity with same email error所优化的场景重复邮箱不再简单报错而是依据身份是否可认领给出正确的接管或冲突响应。3.4 update修改密码update方法emailpass.ts用于改密必须携带entity_id否则返回Cannot update emailpass provider identity without entity_id且password必须是非空字符串随后重新散列新密码并合并进provider_metadata完成更新。四、集成测试验证行为即契约该包自带集成测试 services.spec.ts用 9 个用例把上述行为固定为契约缺少 email 或 password 时返回对应错误Email should be a string/Password should be a string密码不匹配返回Invalid email or password且会先调用retrieve密码匹配返回success: true且返回的provider_metadata为{}密码已被脱敏删除身份不存在时register会调用create新建身份身份存在但app_metadata未定义或为空时register会调用update更新身份同时保留自定义元数据身份存在且app_metadata非空时register返回Identity with email already exists身份不存在时authenticate返回Invalid email or password。这些用例与上文 3.2/3.3 节的描述一一对应可作为实现事实的直接证据。测试通过 mockauthIdentityService.retrieve/create/update的方式隔离了 Auth 模块依赖聚焦验证 Provider 自身逻辑。五、在认证模块中的接入方式与验证能力5.1 Provider 的注册与解析EmailPassAuthService经ModuleProvider(Modules.AUTH, { services })注册后由 auth 模块的 loader 加载。providers.ts 中展示了 Provider 解析的关键逻辑框架会检查每个 Provider 是否带有resolve模块解析器并区分认证 Provider 与验证 ProviderMFA/verification分别校验。emailpass 作为认证 Provider其服务会在模块启动时实例化并注入容器。5.2 验证Verification能力的演进2.15.5 引入的验证原语与 2.16.0 的按 actor 类型要求验证共同完善了 emailpass 的验证体系。在 auth 模块集成测试 中可以看到测试用static identifier emailpass的 fixture Provider 模拟配置provider: emailpass, displayName: Emailpass Fixture并调用service.authenticate(emailpass, ...)验证含auth_provider: emailpass的认证流程——这证实了 emailpass 可作为验证场景的认证 Provider 使用且验证策略可按 actor 类型差异化配置。六、升级与使用建议版本对齐该包与medusajs/framework同步发版升级时应保持两者版本一致当前仓库为 2.20.1避免 peerDependency 冲突关注验证相关变更若业务依赖邮箱验证流程2.15.5 与 2.16.0 涉及验证原语与按 actor 类型的验证要求升级后需检查验证配置是否符合预期hashConfig 权衡默认{ logN: 15, r: 8, p: 1 }在安全性与性能间取得平衡追求更高安全性可增大logN但需评估登录延迟利用可认领机制利用app_metadata是否为空判定身份是否被占用可实现先注册邮箱、后绑定 actor的灵活用户流防御性设计authenticate对不存在的邮箱统一返回Invalid email or password这是避免用户枚举的既有行为二次开发时应保持。结语从 2.0.0 到 2.20.1medusajs/auth-emailpass在近二十个版本的迭代中逐步成熟从基础的注册/登录/改密到同邮箱冲突处理的优化、验证原语与按 actor 验证策略的引入。其实现简洁而严谨——Scrypt 散列、防枚举错误、密码脱敏、可认领身份等设计均可从 emailpass.ts 与 services.spec.ts 中得到直接印证。理解这份 CHANGELOG 及其背后的代码也就理解了 Medusa 凭据认证体系的基石。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Medusa auth-emailpass 认证 Provider 演进全解：从版本历史到 Email/Password 认证实现剖析
Medusa auth-emailpass 认证 Provider 演进全解从版本历史到 Email/Password 认证实现剖析【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa导读本文以medusajs/auth-emailpass的 CHANGELOG.md 为主线结合该 Provider 的源码、类型定义与集成测试系统讲解 Medusa 邮件/密码认证 Provider 从 2.0 到 2.20.1 的演进脉络以及其底层实现原理。读完本文你将理解 emailpass Provider 在 Medusa 认证体系中的定位、注册/登录/改密的完整调用链、hashConfig等关键配置参数的含义以及 CHANGELOG 中每个关键变更背后的代码依据。一、包定位Medusa 认证模块的可插拔 Providermedusajs/auth-emailpass是 Medusa 2.x 认证模块Modules.AUTH的可插拔 Provider 实现负责邮箱 密码这一最常见的凭据认证方式。它的包描述为Email and password credential authentication provider for Medusa见 package.json要求 Node.js 20依赖scrypt-kdf完成密码散列并以medusajs/framework作为 peerDependency。在 Medusa 的 Provider 生态中与它并列的还有 auth-github、auth-google、auth-oidc 等它们共享同一套抽象接口注册时通过 index.ts 将服务注册为Modules.AUTH下的一个 ModuleProviderimport { ModuleProvider, Modules } from medusajs/framework/utils import { EmailPassAuthService } from ./services/emailpass const services [EmailPassAuthService] export default ModuleProvider(Modules.AUTH, { services, })核心服务EmailPassAuthService继承自框架的AbstractAuthModuleProvider见 emailpass.ts静态标识符为emailpass显示名为Email/Password Authentication并实现authenticate、register、update三个核心方法。二、版本演进时间线CHANGELOG 里的关键节点CHANGELOG 记录了该包自 2.0.0 以来的所有发布绝大多数为跟随medusajs/framework的依赖升级Patch Changes但有几个版本携带了真正的功能变更是理解该 Provider 能力边界的关键版本变更类型内容要点2.0.0Major随 Medusa 2.0 发布PR #7341作为新认证模块的 Provider 引入2.6.1Patch移除 Medusa 包上的版本区间PR #11738依赖策略收紧2.11.0Patch修复相同邮箱身份错误处理提升重复注册场景的健壮性PR #135372.11.3Patch依赖清理与改进PR #139102.15.5Patch为 emailpass 增加认证验证原语PR #154962.16.0Minor按 actor 类型要求验证feat: require verification by actor type2.17.2Patch补充包 bugs 元数据PR #156832.20.1Patch最新版本同步medusajs/framework2.20.1从结构上看该包的版本号始终与medusajs/framework保持一致如 2.20.1 对应 framework 2.20.1说明它作为框架级 Provider 与核心同步发版、紧随框架 API 变化。值得关注的功能性变更2.16.0 - 按 actor 类型要求验证CHANGELOG 记录为feat(auth-emailpass, types, medusa): require verification by actor type。这意味着验证verification策略不再一刀切而是可以针对不同 actor如用户、管理员等分别配置是否必须完成验证。该能力与 auth 模块的验证体系直接相关。2.15.5 - 认证验证原语Add auth verification primitives for emailpass。这是验证能力的基础建设为后续按 actor 类型验证提供了底层原语。2.11.0 - 相同邮箱身份处理优化fix(auth-emailpass): better handle identity with same email error。该修复与register方法中邮箱已存在的判定逻辑强相关详见下文第五节。三、源码实现三大核心方法与密码散列3.1 密码散列Scrypt 可配置参数hashPassword方法emailpass.ts使用scrypt-kdf库对明文密码进行散列并将结果以 base64 字符串存储protected async hashPassword(password: string) { const hashConfig this.config_.hashConfig ?? { logN: 15, r: 8, p: 1 } const passwordHash await Scrypt.kdf(password, hashConfig) return passwordHash.toString(base64) }这里直接体现了hashConfig配置项的作用。其类型定义位于 packages/core/types/src/auth/providers/emailpass.tsexport interface EmailPassAuthProviderOptions { hashConfig?: { logN: number r: number p: number } }参数含义logNCPU/内存成本参数以 2 为底的对数默认15越大越慢越安全r块大小参数默认8p并行化参数默认1。未配置hashConfig时使用默认值{ logN: 15, r: 8, p: 1 }。集成测试 services.spec.ts 中同样使用该默认配置生成密码散列来验证认证逻辑说明这是官方推荐的默认强度。3.2 authenticate验证凭据authenticate方法emailpass.ts的核心流程输入校验从userData.body取出email和password两者缺失或非字符串时分别返回Email should be a string/Password should be a string按邮箱检索身份调用authIdentityService.retrieve({ entity_id: email })若抛出MedusaError.Types.NOT_FOUND统一返回Invalid email or password——这是防枚举攻击的标准做法不暴露该邮箱是否已注册提取 Provider 身份从authIdentity.provider_identities中找到provider emailpass的条目取出provider_metadata.passwordbase64 编码的散列校验密码Buffer.from(passwordHash, base64)还原字节后调用Scrypt.verify(buf, password)比对返回结果成功时返回success: true与经过脱敏的authIdentity失败则返回Invalid email or password。注意成功返回前会调用sanitizeAuthIdentity_从返回结果中删除provider_metadata.password确保密码散列绝不泄漏到上层调用方emailpass.ts。3.3 register注册与可认领身份register方法emailpass.ts逻辑上分为两条路径邮箱不存在捕获NOT_FOUND后走create分支创建新的 AuthIdentityentity_id即邮箱provider_metadata.password为散列值邮箱已存在但尚未被认领若identity.app_metadata未定义或为空!isPresent(identity.app_metadata)说明该身份尚未绑定任何 actor用户/管理员等此时走update分支直接接管并更新密码返回success: true。这一可认领claimable设计在源码注释中写得很清楚If app_metadata is not defined or empty, it means no actor was assigned to the auth_identity yet (still claimable)邮箱已存在且已被认领app_metadata非空返回success: false错误信息为Identity with email already exists。upsertAuthIdentityemailpass.ts统一处理 create/update 两种情形且在update时会先读取原有provider_metadata再合并写入新密码因此原有自定义元数据如测试中的custom: keep-me不会丢失。这正是 2.11.0 变更better handle identity with same email error所优化的场景重复邮箱不再简单报错而是依据身份是否可认领给出正确的接管或冲突响应。3.4 update修改密码update方法emailpass.ts用于改密必须携带entity_id否则返回Cannot update emailpass provider identity without entity_id且password必须是非空字符串随后重新散列新密码并合并进provider_metadata完成更新。四、集成测试验证行为即契约该包自带集成测试 services.spec.ts用 9 个用例把上述行为固定为契约缺少 email 或 password 时返回对应错误Email should be a string/Password should be a string密码不匹配返回Invalid email or password且会先调用retrieve密码匹配返回success: true且返回的provider_metadata为{}密码已被脱敏删除身份不存在时register会调用create新建身份身份存在但app_metadata未定义或为空时register会调用update更新身份同时保留自定义元数据身份存在且app_metadata非空时register返回Identity with email already exists身份不存在时authenticate返回Invalid email or password。这些用例与上文 3.2/3.3 节的描述一一对应可作为实现事实的直接证据。测试通过 mockauthIdentityService.retrieve/create/update的方式隔离了 Auth 模块依赖聚焦验证 Provider 自身逻辑。五、在认证模块中的接入方式与验证能力5.1 Provider 的注册与解析EmailPassAuthService经ModuleProvider(Modules.AUTH, { services })注册后由 auth 模块的 loader 加载。providers.ts 中展示了 Provider 解析的关键逻辑框架会检查每个 Provider 是否带有resolve模块解析器并区分认证 Provider 与验证 ProviderMFA/verification分别校验。emailpass 作为认证 Provider其服务会在模块启动时实例化并注入容器。5.2 验证Verification能力的演进2.15.5 引入的验证原语与 2.16.0 的按 actor 类型要求验证共同完善了 emailpass 的验证体系。在 auth 模块集成测试 中可以看到测试用static identifier emailpass的 fixture Provider 模拟配置provider: emailpass, displayName: Emailpass Fixture并调用service.authenticate(emailpass, ...)验证含auth_provider: emailpass的认证流程——这证实了 emailpass 可作为验证场景的认证 Provider 使用且验证策略可按 actor 类型差异化配置。六、升级与使用建议版本对齐该包与medusajs/framework同步发版升级时应保持两者版本一致当前仓库为 2.20.1避免 peerDependency 冲突关注验证相关变更若业务依赖邮箱验证流程2.15.5 与 2.16.0 涉及验证原语与按 actor 类型的验证要求升级后需检查验证配置是否符合预期hashConfig 权衡默认{ logN: 15, r: 8, p: 1 }在安全性与性能间取得平衡追求更高安全性可增大logN但需评估登录延迟利用可认领机制利用app_metadata是否为空判定身份是否被占用可实现先注册邮箱、后绑定 actor的灵活用户流防御性设计authenticate对不存在的邮箱统一返回Invalid email or password这是避免用户枚举的既有行为二次开发时应保持。结语从 2.0.0 到 2.20.1medusajs/auth-emailpass在近二十个版本的迭代中逐步成熟从基础的注册/登录/改密到同邮箱冲突处理的优化、验证原语与按 actor 验证策略的引入。其实现简洁而严谨——Scrypt 散列、防枚举错误、密码脱敏、可认领身份等设计均可从 emailpass.ts 与 services.spec.ts 中得到直接印证。理解这份 CHANGELOG 及其背后的代码也就理解了 Medusa 凭据认证体系的基石。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考