Birdor JWT Decoder 实现规格：Token 解析、时间字段、安全提示与边界输入

本系列导航

• 上一篇：Birdor JSON Formatter 实现规格
• 下一篇：工具页通用组件规格
• 返回目录：Birdor 商业计划书目录

本章关键词

JWT Decoder、token 解析、Base64URL、exp、iat、nbf、decode、verify、安全提示、边界输入。

适合阅读的人

• 准备实现 Birdor JWT Decoder 的工程师。
• 需要明确 JWT decode 和 verify 边界的人。
• 想把 JWT 页面做成 API 鉴权调试入口的人。

本章摘要

JWT Decoder 是 Birdor API 鉴权调试工作流的入口。它的第一版目标不是验证签名，而是稳定完成本地 decode、claim 展示、时间解释和安全提示。页面必须明确告诉用户：decode 只是解码内容，不代表 token 有效。

本文把 JWT Decoder PRD 转成实现规格，覆盖输入规范化、三段解析、Base64URL 解码、时间字段、错误提示、相关工具和测试样例。JWT Verify、JWK、OAuth Debug Helper 不进入第一版。

页面结构

JWT Decoder 页面建议分为：

安全提示不能藏在页面底部。用户看到解析结果时，就应该看到 signature 未验证的提示。

输入规范化

输入处理顺序：

1. trim 首尾空白。
2. 如果以 Bearer 开头，移除前缀。
3. 移除换行和多余空白。
4. 按 . 分割。
5. 检查是否为三段。
6. 分别处理 header、payload、signature。

支持示例：

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMifQ.signature

不支持示例：

abc.def

应提示：JWT 通常包含 header、payload、signature 三段。

Base64URL 解码

Base64URL 解码规则：

• - 替换为 +。
• _ 替换为 /。
• 根据长度补 =。
• 解码为 UTF-8 字符串。
• 尝试 JSON.parse header 和 payload。

错误类型：

signature 不需要 JSON.parse，只展示原始值和长度。

Claim 展示

常见字段：

时间字段如果不是数字，应显示“无法识别为 Unix timestamp”。不要静默忽略。

时间状态

时间判断：

页面应显示 UTC 和用户本地时间，避免跨时区误判。

安全提示

必须展示：

• Decode 只是解码，不验证签名。
• Signature 未被验证。
• 不要粘贴生产敏感 token。
• 如果 payload 包含 email、phone、token、secret、role、permission 等字段，显示轻提示。
• alg: none 或异常 alg 时给出风险提示。

提示要准确，不要夸大。比如不要说“token 不安全”，而应说“当前页面未验证签名，不能据此判断 token 是否有效”。

操作规则

Decode：

• 输入为空时提示。
• 输入不为三段时提示。
• 成功时展示 header、payload、signature。
• 成功时展示 claim panel 和 security panel。

Copy：

• 支持复制 header JSON。
• 支持复制 payload JSON。
• 支持复制原始 token。

Sample：

• 填入无敏感信息的示例 token。
• 示例 payload 包含 sub、name、iat、exp。

Clear：

• 清空输入、结果和错误。

测试样例

合法 JWT：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkJpcmRvciIsImlhdCI6MTUxNjIzOTAyMn0.signature

预期：展示 header、payload、signature，iat 转成本地时间和 UTC。

Bearer 输入：

Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjMifQ.signature

预期：自动移除 Bearer 前缀并解析。

缺少分段：

abc.def

预期：提示 JWT 通常包含三段。

非法 payload：

eyJhbGciOiJIUzI1NiJ9.invalid.signature

预期：提示 payload 无法 Base64URL 解码或不是合法 JSON。

指标

事件：

• jwt_decode_click
• jwt_decode_success
• jwt_decode_error
• jwt_copy_header
• jwt_copy_payload
• jwt_time_claim_view
• jwt_security_hint_view
• jwt_related_tool_click

事件不能记录 token 原文、payload 内容或任何 claim 值。只记录成功、错误类型、token 长度区间、是否含时间字段。

验收标准

• 本地 decode 可用。
• Bearer、空格、换行可规范化。
• header/payload JSON 展示稳定。
• exp、iat、nbf 可读。
• decode/verify 区分明确。
• 敏感字段有轻提示。
• Copy、Sample、Clear 可用。
• 不上传 token，不记录 token 内容。

非目标

第一版不做：

• JWT Verify。
• JWK Viewer。
• OAuth Debug Helper。
• 批量 JWT 检查。
• Token 监控。
• 服务端保存历史。

延伸阅读

• JWT Decoder PRD
• JWT Decoder 工具页应该怎么做
• Birdor 首批工程 Issue
• 工具页通用组件规格
• 第三十五章：隐私、安全与数据策略
• 第二十四章：API 用量计费模型

JWT Decoder 与 Verify 的边界

第一版只做 decode，但代码结构应预留 verify 的位置：

解码和验证的区别必须在 UI 上明确区分。建议：

• 页面标题是"JWT Decoder"，不是"JWT Validator"。
• 结果区顶部有一条不可关闭的 banner：“此工具仅展示 token 内容，不验证签名或声称的真实性。”
• 如果后续加入 verify 功能，应该作为独立入口或明确切换。

时间字段处理细节

JWT 的时间字段（exp、iat、nbf）需要特殊处理：

相对时间比绝对时间更有用。一个显示"2025-11-15T10:00:00Z"的字段不如"3 小时后过期"直观。

时间精度问题

JWT 的 exp、iat、nbf 的单位是秒。但在前端展示时，用户可能混淆毫秒和秒。如果收到一个毫秒级的时间戳（如 1700000000000），应提示"此时间戳单位可能是毫秒而不是秒"。

敏感字段识别逻辑

JWT payload 中可能包含敏感信息。以下为建议的敏感字段列表：

如果检测到敏感字段，在 Security Panel 中显示：“此 token 包含 email/phone 等个人信息，请勿在公开渠道分享解析结果。”

JWT Decoder 的 API 复用边界

JWT Decoder 的本地逻辑可以复用为 API 端点：

API 版本的 decode 逻辑与前端共享同一套核心函数，确保一致性。

测试样例补充

第一版应覆盖以下额外边界情况：

超长 token：

eyJhbGciOiJIUzI1NiJ9.[超长payload].signature

预期：正常解码 header 和 payload，提示 token 长度。超大 token 不应导致浏览器卡顿。

非标准 claim：

{"sub":"123","custom_field":"value","nested":{"a":1}}

预期：展示所有 claim，包括非标准字段。不要只展示预定义字段。

FAQ 补充

Q: JWT Decoder 是否需要支持 JWE（加密 JWT）？
第一版不需要。JWE 的解密需要密钥，与"本地处理、不上传"的原则冲突。如果用户需要解密 JWE，应引导到服务端工具或命令行工具。

Q: 是否需要在 JWT Decoder 中集成 OAuth 2.0 调试功能？
不需要。OAuth 调试是另一个工具的需求（如查看 authorization code flow）。JWT Decoder 应保持专注：解析单个 token 的内容。OAuth 调试可以作为独立工具"OAuth Flow Debugger"开发。

Q: 如果 JWT 的 alg 是 “none”，应该怎么提示？
这是一个安全风险。应显示明显的警告：“此 token 的 alg 为 none，表示没有签名验证。任何人都可以伪造此 token。请勿在生产环境中使用 alg:none。”

Q: JWT Decoder 应不应该展示 signature 的 base64 解码内容？
不应该。signature 的内容是二进制数据（HMAC 签名或 RSA 签名），base64 解码后没有意义。展示 signature 的原始 base64 字符串和长度即可。

Q: 是否需要支持多个 token 同时解析？
第一版不需要。多 token 解析可以放入后续"批量 JWT 检查"工具。单个 token 的解析体验应保持简单：一个输入框，一个结果区。

JWT Decoder 在 API 开发工作流中的位置

JWT Decoder 不仅是一个独立工具，也是 API 调试工作流中的一环：

API 调试工作流：
1. 获取 JWT token（登录 / OAuth / 测试账号）
2. JWT Decoder -> 查看 payload 中的用户 ID、角色、过期时间
3. 根据角色判断预期权限
4. 发送请求到受保护端点
5. 收到 401/403 -> 回到 JWT Decoder 检查 token 是否过期或 alg 异常

JWT Decoder 的价值不在于它多复杂，而在于它帮开发者快速定位"是 token 问题还是服务端问题"。

批量 JWT 检查策略

单个 JWT Decoder 是第一版，后续可以扩展为"批量 JWT 检查"工具：

批量检查的目标用户是：安全审计人员、运维团队、测试工程师。

JWT 安全攻击场景

JWT Decoder 不仅是开发工具，也是安全教育的载体。以下是几个关键攻击场景及其在 UI 中的提示：

Alg 混淆攻击（Alg Confusion）

攻击者修改 header 中的 alg 从 RS256 改为 HS256，然后用公钥作为 HMAC 密钥伪造签名。如果服务端未正确校验 alg，就会接受伪造 token。

JWT Decoder 的提示：“此 token 使用 RS256 算法。请确认服务端已正确校验 alg 字段，防止 alg 混淆攻击。”

过期 Token 重放

如果服务端未正确校验 exp，攻击者可以重放过期的 token。

JWT Decoder 的提示：“此 token 已过期。如果服务端仍然接受它，请检查服务端是否正确校验 exp 字段。”

敏感 Claim 泄露

如果 token 中包含不应暴露的信息（如 email、role），且被记录到日志或前端暴露，会导致信息泄露。

JWT Decoder 的提示：“此 token 包含 email/role 等敏感 claim。建议在服务端使用 scope 最小化原则，只包含必要的 claim。”

JWT Decoder 与 API Gateway 集成

在微服务架构中，JWT 通常在 API Gateway 层解析：

FAQ 补充（续）

Q: JWT Decoder 是否支持刷新 token（Refresh Token）的解析？
Refresh Token 的格式和 Access Token 通常相同（也是 JWT）。因此 JWT Decoder 可以直接解析 Refresh Token。但应该提示用户：“Refresh Token 的有效期通常更长，泄露风险更高。请勿在公开渠道分享 Refresh Token。”

Q: 如何处理 JWT 中的自定义 claim（如 x-custom-field）？
展示所有 claim，包括自定义 claim。自定义 claim 用与标准 claim 相同的格式展示，不做特殊处理。但可以在 UI 中用标签标记哪些是标准 claim（如 exp、iat），哪些是自定义 claim。

Q: 是否需要提供 “Copy as cURL” 功能？
不需要在 JWT Decoder 中提供。但可以在相关工具区推荐"cURL Builder"，让用户能把解析出的 claim 拼接到 API 请求中。这保持了每个工具的职责单一。

Q: JWT Decoder 如何帮助教育初级开发者理解 JWT？
在结果区增加一个"什么是 JWT？“的折叠说明：

• JWT 由 header、payload、signature 三部分组成。
• Header 定义算法和类型。
• Payload 包含 claim（如用户 ID、过期时间）。
• Signature 用于验证 token 未被篡改。
• Decode 只是查看内容，不代表 token 有效。

这个教育元素可以提升页面的 SEO 和用户停留时间。