saas

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

定义 Birdor JWT Decoder 的实现规格，覆盖 token 规范化、Base64URL 解码、claim 展示、时间字段、安全提示、错误类型和测试样例。

Leeting Yan 4 分钟阅读 1884 字

本系列导航

本章关键词

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 页面建议分为：

区域内容要求
Header标题、说明、隐私提示明确本地 decode，不上传 token
Inputtoken textarea、Sample、Clear支持长 token、Bearer 前缀
ResultHeader、Payload、Signature 三块JSON 美化展示，可复制
Claim Panelexp、iat、nbf、iss、aud、sub时间字段可读
Security Paneldecode/verify 区分、signature 未验证靠近结果区
Related ToolsTimestamp、Base64、Header Parser、Curl BuilderAPI 调试路径
FAQdecode vs verify、JWT 过期、401/403承接 SEO 问题

安全提示不能藏在页面底部。用户看到解析结果时，就应该看到 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。

错误类型：

错误说明
invalid_segments不是三段 token
invalid_base64urlheader 或 payload 无法解码
invalid_json解码后不是合法 JSON
empty_input输入为空
too_largetoken 过长

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

Claim 展示

常见字段：

Claim展示方式
exp过期时间，本地时间、UTC、相对时间
iat签发时间，本地时间、UTC、相对时间
nbf生效时间，本地时间、UTC、相对时间
ississuer 原文
audaudience，支持字符串或数组
subsubject 原文
algheader 算法
typheader 类型

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

时间状态

时间判断：

状态条件文案
expirednow > expToken 已过期
activenbf 为空或 now >= nbf，且 exp 未过期当前时间处于有效窗口内
not_yet_validnow < nbfToken 尚未生效
no_expexp 缺失没有 exp 字段，无法判断过期时间
invalid_time字段非数字时间字段不是有效 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 监控。
  • 服务端保存历史。

延伸阅读

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页