指纹绕过方案：纯 JS 生成有效 fingerprint（无需 opencode CLI / MITM）

[jcleng]

指纹绕过方案：纯 JS 生成有效 fingerprint（无需 opencode CLI / MITM）

适用版本：opencode.ai/inference/v1 free tier（OpenCode Zen 免费档）。
对应提交：feat(fingerprint): generate the OpenCode free-tier fingerprint in pure JS (drop CLI/MITM)

⚠️ 本文已更新：早期版本认为 x-opencode-session 有校验和、无法伪造、必须 spawn 真正的 opencode。
该结论是错的。 经反编译 opencode 源码 + 对真实端点做 ablation 实测，已确认该 id 完全可以在纯 JS 里算出来。

---

📌 v1.0.2 已发布：端点修正（重要）

免费档的正确端点是 https://opencode.ai/inference/v1（OpenCode 自有客户端用的就是它，见 https://models.opencode.ai/api.json）。
早期帖子和旧镜像里写的 /zen/v1 已经失效——OpenCode 现在对免费档的 /zen/v1 返回 403 FreeTierError: OpenCode's free tier can only be used from within OpenCode。
该修复已随 v1.0.2 正式发布（tag v1.0.2 = e987934）：ghcr.io/jcleng/opencode-free-provider:latest 默认即为 inference/v1，直接拉取即可。 若你跑的是旧镜像（默认 /zen/v1，则必然 403），用 OPENCODE_BASE_OVERRIDE='https://opencode.ai/inference/v1' 强制指向可用端点。详见 README 的 Docker 段与 OPENCODE_BASE_OVERRIDE 说明。

---

1. 背景：为什么会 403 FreeTierError

opencode.ai/inference/v1 服务端有一道 client-fingerprint gate。裸请求会被拒绝：

403 FreeTierError: OpenCode's free tier can only be used from within OpenCode.
Download it at https://opencode.ai and keep building.

服务端要求请求必须同时携带：

要求	值
User-Agent	opencode/<版本>（小写，版本 ≥ 1.18；老版本 → 426，非 opencode → 403）
x-opencode-session	opencode 的 descending identifier：ses_ + 12 位小写 hex + 14 位 base62（见下）
请求体 stream	必须为 true（否则 403）
请求体 tools	必须包含全部四个 bash/glob/grep/read（缺任意一个 → 403）
Authorization	Bearer public（服务端不校验，仅作对齐）

注意：端点必须打到 /inference/v1。/zen/v1 现在已经不通（返回同样的 403 FreeTierError），不要再用。

---

2. 关键结论：session id 可以在纯 JS 里算出来

最容易踩坑的是 x-opencode-session。早期版本以为它带校验和、只能由 opencode 二进制生成——这是错的。它其实就是 opencode 普通的 descending 标识符，结构完全公开。

2.1 算法来自 opencode 源码

SessionID.create() = "ses_" + descending()（packages/schema/src/session-id.ts），而 descending()（packages/schema/src/identifier.ts）就是：

counter++                              // 每毫秒重置的计数器（counter 从 1 开始）
current = BigInt(Date.now()) * 0x1000n + BigInt(counter)
value   = ~current                     // 48 位二补数
hex     = value 的 6 个字节            // == 12 位小写 hex
tail    = 14 位随机 base62 (0-9A-Za-z)

所以真实 id 的形状是 ses_ + 12 位小写 hex + 14 位 base62（共 30 字符）。

（同理，message id = "msg_" + ascending()，即不带取反。）

2.2 服务端到底校验什么（ablation 实测）

对真实端点逐位消融，得到的确切规则：

• 低 12 bit 编码计数器 0xfff - counter，要求 counter ≤ 63（counter 0–63 → 200，64–4095 → 403）；
• 前 12 位必须是小写 hex（大写 / 非 hex → 403）；
• tail 必须恰好 14 位（13/15 → 403），字符集本身不校验；
• 时间戳大小 / 新旧完全不校验（1970、当前、2035 都能过；高 36 bit 随便填）；
• x-opencode-session-id 若存在，必须等于 x-opencode-session（不一致 → 403）；
• x-opencode-client / x-opencode-project / x-opencode-request / x-session-affinity / X-Session-Id 都是装饰性的（乱填也 200）。

没有任何校验和。 只要按上面的算法生成、并保证 counter ∈ [1,63]，就一定通过。

边界精确复现：0xfbf（counter=64）→ 403，0xfc0（counter=63）→ 200，与高 36 bit 无关，多次重复稳定。
UA 版本门槛：opencode/1.17.9 → 426，opencode/1.18.0 → 200，opencode/99.0.0 → 200（无上限）；大小写不敏感。
顺带一提，服务端源码里并没有这道 gate——它是更新的服务端 / 外部推理服务在做校验，所以以实测为准。

---

3. 方案：纯 JS 生成，不再需要 opencode

src/fingerprint.js 现在直接复刻上面的算法：

• encodeIdentifier(timestamp, { descending })：复刻 opencode 的 descending()/ascending()；
• newSessionId() = ses_ + descending id；newMessageId() = msg_ + ascending id；
• counter 超过 63 时自动进位到下一毫秒，保证产出的 id 永远落在合法区间；
• buildFingerprintHeaders()：生成完整 header 组
  （user-agent、x-opencode-session、x-opencode-session-id（与前者相同）、x-opencode-request、x-opencode-client: cli、x-opencode-project: global）。

没有 child_process，没有 MITM / TLS 拦截，没有 openssl，没有一次性 CA。
UA 仍默认 opencode/latest/2.0.22/cli，可用 OPENCODE_UA 覆盖。

---

4. 集成点

文件	职责
src/fingerprint.js	纯 JS 指纹生成：opencode 的 descending()/ascending() 算法、session 模式（per-request/sticky）、header 构造、指纹状态
src/config.js	从 src/fingerprint.js re-export 指纹 API（单一来源）；UA / 工具常量 / 环境变量 / 端点（getZenEndpoints() 默认 inference/v1）
src/upstream.js	fingerprintHeaders() 注入生成的指纹 + 解析出的 Authorization；relayChatCompletions() 汇聚上游 SSE
server.js	启动时打印指纹来源（fingerprint source: generated）
src/routes.js / /__session	暴露指纹来源（generated = 纯 JS 计算）

---

5. Docker：不再需要装 opencode

原来的 Dockerfile 为了 spawn opencode + MITM，必须用 glibc 基础镜像（node:24-bookworm-slim）并安装 @opencode/cli（约 200MB 的原生二进制）+ openssl，镜像约 2.4GB。

现在指纹是纯 JS 算的，所以：

• 不再安装 opencode，不再安装 openssl；
• 镜像体积降到约 245MB。

docker build -t opencode-free-provider .

# v1.0.2 起镜像已默认 inference/v1。若你用的是旧镜像（默认 /zen/v1，会 403），
# 用下面这行强制指向可用端点：
docker run -d --name opencode-free-provider -p 8791:8791 \
  -e OPENCODE_BASE_OVERRIDE='https://opencode.ai/inference/v1' \
  opencode-free-provider

验证：

curl http://127.0.0.1:8791/__session    # 期望 fingerprint.source == "generated"

基础镜像仍保持 node:24-bookworm-slim（Node ≥ 24 才有 NODE_USE_ENV_PROXY，见第 6 节）；
由于不再有原生二进制，理论上也能回到 alpine，这里为稳妥未改。

---

6. 环境变量

变量	默认	说明
ZEN_SESSION_MODE	per-request	per-request（每次请求新 ses_，最稳）或 sticky（进程内复用）
ZEN_SESSION_ROTATE_SECONDS	0	sticky 模式下每隔 N 秒轮换 session
OPENCODE_UA	opencode/latest/2.0.22/cli	发给 gate 的 User-Agent
OPENCODE_BASE_OVERRIDE	(当前源码默认 https://opencode.ai/inference/v1)	强制覆盖 relay 的上游 base URL。旧镜像默认 /zen/v1（已被拒 403），跑旧镜像时用它指向 /inference/v1
ZEN_MODELS_TTL_SECONDS	600	模型列表缓存时长
ZEN_MODELS_TIMEOUT_MS	5000	上游 /models 发现超时
NODE_USE_ENV_PROXY	1（容器内，检测到 http(s) 代理时自动开）	让 Node 内置 fetch 读 https_proxy（Node ≥ 24）。SOCKS5 不支持

已移除：OPENCODE_FP_DISABLE / OPENCODE_FP_TTL_MS / OPENCODE_FP_TIMEOUT_MS（不再有 CLI 抓取）。

---

7. 验证结果

• ✅ 单元测试 50 个全部通过（mock upstream，无网络）。
• ✅ 真实端点：用纯 JS 生成的指纹直接 POST opencode.ai/inference/v1/chat/completions → HTTP 200（同一合法 body/headers，/zen/v1 则 403）。
• ✅ 本地代理端到端：fingerprint.source == "generated"，非流式与流式（以 [DONE] 收尾）均正常返回。
• ✅ 拉取 Actions 构建出的镜像（ghcr.io/jcleng/opencode-free-provider:latest）实测：容器内同样是 generated，端到端 200。
• ✅ 线上服务器（旧镜像跑 /zen/v1 时 403）通过加 OPENCODE_BASE_OVERRIDE='https://opencode.ai/inference/v1' 重建容器后恢复正常。

客户端侧提示：若本机有 ALL_PROXY（如 socks5://127.0.0.1:20170），curl 会把 localhost 请求也走代理导致空响应。测代理时用 curl --noproxy '*'。Node 的 fetch 默认不读 ALL_PROXY，所以代理服务端本身不受影响。

---

8. 后续维护

上游若再次收紧检测、又开始 403，几乎总是集中在 fingerprint 或端点，而不是代理管道：

• 先确认端点有没有变（曾从 /zen/v1 切到 /inference/v1）；改 OPENCODE_BASE_OVERRIDE 或 src/config.js 的 getZenEndpoints()。
• 再确认 gate 是否只改了校验规则：调 src/fingerprint.js（算法、UA、MAX_COUNTER）。
• UA 版本门槛若提高：改 OPENCODE_UA（默认 opencode/latest/2.0.22/cli，本身带 latest，可先观察是否自动兼容）。
• 若 gate 改到超出结构校验（例如真的引入签名），再考虑回到「spawn 真 opencode 抓指纹」的旧方案——相关历史实现见本仓库 8d25b65。