Shopify Hydrogen 项目中 JWT 解码异常问题分析

问题背景

在 Shopify Hydrogen 项目（版本 2024.7.5）中，开发者在实现用户登录功能时遇到了一个关于 JWT（JSON Web Token）解码的异常问题。当使用 ngrok 或生产域名进行新登录方式验证时，系统抛出了一个意外的服务器错误，提示 atob() called with invalid base64-encoded data。

错误详情

错误发生在 JWT 解码过程中，具体是在 decodeJwt 函数内部。该函数尝试将 JWT 令牌分割为三部分（header、payload 和 signature），然后分别对 header 和 payload 进行 base64 解码。

异常的关键点在于：

1. JWT 的 header 部分出现了意外的下划线字符 _
2. 标准的 base64 编码只允许包含特定字符集（字母数字、'+'、'/' 和最多两个末尾的 '=' 填充字符）
3. 非标准字符导致 atob() 函数抛出异常

技术分析

JWT 标准格式

正常情况下，JWT 应由三部分组成，每部分都是标准的 base64url 编码：

1. Header：包含令牌类型和签名算法
2. Payload：包含声明（claims）
3. Signature：验证令牌完整性的签名

Base64 与 Base64URL 的区别

问题中出现的下划线 _ 不是标准 base64 字符集的组成部分。实际上，JWT 规范使用的是 Base64URL 编码，它与标准 Base64 有以下区别：

1. 使用 - 代替 +
2. 使用 _ 代替 /
3. 省略末尾的 = 填充字符

问题根源

错误表明 Hydrogen 项目中的解码函数可能没有正确处理 Base64URL 编码格式，而是直接使用了标准的 atob() 函数，这导致了非标准字符的解析失败。

解决方案

临时解决方案

开发者可以自行实现一个 Base64URL 解码函数，在调用 atob() 前先将特殊字符转换回标准 Base64 格式：

function base64UrlDecode(str) {
  // 将 URL-safe 字符转换回标准 Base64 字符
  str = str.replace(/-/g, '+').replace(/_/g, '/');
  
  // 添加必要的填充字符
  while (str.length % 4) {
    str += '=';
  }
  
  return atob(str);
}

官方修复

根据后续讨论，Shopify 团队确认这是一个 bug，并在客户账户 API 端点进行了修复。修复后的版本正确处理了 JWT 的 Base64URL 编码格式。

最佳实践建议

1. 编码一致性：在 JWT 相关操作中，确保编码和解码使用相同的格式（Base64 或 Base64URL）
2. 错误处理：实现健壮的错误处理机制，捕获并适当处理解码异常
3. 依赖检查：定期检查依赖库版本，确保使用的是修复了已知问题的版本
4. 测试覆盖：对认证流程进行充分测试，包括各种边缘情况

总结

这个案例展示了在实现认证流程时，对标准协议细节理解的重要性。即使是像 Base64 编码这样看似简单的技术，不同变体之间的细微差别也可能导致严重问题。开发者应当仔细阅读相关规范，并在实现关键安全功能时格外注意细节处理。

对于使用 Shopify Hydrogen 的开发者，建议保持项目依赖的最新状态，并关注官方更新日志，以确保使用的版本包含所有关键修复。