SuperAPI AI 工具集

clerk-clock-skew-jwt

通用与其它

查看项目

更新于 10-15 23:41

技能介绍

用途:解决 Clerk 会话令牌与自定义 JWT 模板因时钟偏移导致的验证失败,常见错误为 token-not-active-yet、token-expired、invalid-iat。Clerk 令牌含 iat、nbf、exp 三个时间声明,验证方时钟落后会误判 nbf,超前会提前判定 exp。

主要能力:解释时间声明含义与错误对应关系;给出各环境的偏移成因(WSL2、Docker Desktop、无 chrony 的 Linux 容器、Kubernetes pod、CI runner、serverless 冷启动、挂起虚拟机等);提供校时排查步骤与修复命令,如 date -u +%s、docker exec <container> date -u、sudo hwclock -s、sudo timedatectl set-ntp true、wsl --shutdown、GitHub Actions 的 sudo sntp -S time.cloudflare.com;汇总各库 leeway 配置:Node jsonwebtoken 的 clockTolerance、jose 的 clockTolerance、PyJWT 的 leeway、python-jose、golang-jwt/jwt/v5 的 WithLeeway、Ruby jwt 的 leeway、Nimbus 的 setMaxClockSkew、Auth0 java-jwt 的 acceptLeeway、.NET 的 ClockSkew、firebase/php-jwt 的 JWT::$leeway;提供区分时钟偏移与真实过期的诊断决策树。

使用方式:先用不验证方式解码令牌读取 iat/nbf/exp,再取验证方当前时间比对差值;确认容器/主机时钟是否同步,优先修时钟,再考虑加 leeway。Clerk 后端 verifyToken 支持 clockSkewInMs,文档默认 5000 毫秒;Dashboard 也有会话级 Allowed Clock Skew / nbf offset 设置,仅影响新签发令牌。clerkMiddleware() 和 auth.protect() 不支持直接传入 clockSkewInMs,需改用 verifyToken。

限制与权衡:leeway 越大,过期令牌被接受的时间越长,安全性越低,建议生产环境用 30-60 秒;.NET 默认 5 分钟被认为过于宽松。不要只调 leeway 而不修时钟。前端时钟偏移不影响后端验证。Webhook 使用 Svix 的时间戳容忍窗口,与 JWT 时钟偏移是不同问题,不可混为一谈。资料未提供该技能的安装方式和具体调用命令。