geektls

多语言 TLS/HTTP 全栈指纹伪造库：对 ClientHello 逐字节可控，覆盖 TLS（JA3/JA4）、HTTP/2（Akamai 指纹）、HTTP/3 + QUIC、TCP 四层指纹，提供 Python / Node.js / Go 三种语言的一等 API。

当前状态：P0–P7 完成（一期收工）。其中 TLS/H2 已交付并经 E2 外部 oracle 验证；H3/QUIC 机制已建，但预设证据仍为 E4/TODO（H3 尚未做外部验证）；TCP 仅 TTL/MSS 可承诺（window/window_scale/options 仅 Linux 探测模式，不影响真实连接）。P1-T8（nginx 采集端 L2 终审）与 P6-T3（JA4TCP 验收）待 Linux 环境，见文末遗留表。精确现状见 docs/01-fingerprint-dimensions.md 与 docs/capability-matrix.yml。

功能矩阵

安装

pip install geektls          # Python（Windows x64 / Linux x86_64，动态库随 wheel 分发）
npm install geektls          # Node.js（⚠️ 尚未发布到 npm，当前请用仓库内 bindings/nodejs）
go get github.com/geektls/core   # Go（⚠️ 模块尚未推送到公网仓库，当前用本地 replace）

已发布到 PyPI 的 wheel 覆盖 Windows x64 与 Linux x86_64（glibc ≥ 2.34）； macOS / Linux-ARM 的 wheel 待 CI 矩阵补齐（其余平台安装会提示无匹配版本）。

Python 一行自检：

python -c "import geektls,json;print(json.dumps(geektls.version()));print(len(geektls.list_presets()),'presets')"

快速上手

Python（pip install geektls，动态库随包）：

from geektls import Session

with Session(impersonate="chrome_150") as s:
    r = s.get("https://example.com")
    print(r.status_code, r.ok, r.used_protocol)   # 200 True h2
    print(r.headers["content-type"])             # 大小写不敏感
    print(r.text[:200])                          # 直接当文本用
    print(r.selfcheck["ja4"])                    # 本次握手的 JA4 自算
    for line in r.iter_lines():                  # 需要流式时才用迭代
        ...

Node.js（npm install geektls）：

const { Session } = require('geektls');

const s = new Session({ impersonate: 'chrome_150', timeout: 20 });
const r = await s.get('https://example.com', { params: { q: 1 } });
console.log(r.statusCode, r.ok, r.reason);     // 200 true OK
console.log(r.header('content-type'));         // 大小写不敏感
console.log(await r.text());                   // 直接当文本用
console.log((await r.json()).slideshow);       // 直接当 JSON 用
for await (const chunk of r.iterContent()) { ... }   // 需要流式时才迭代
s.close();

Go（import "github.com/geektls/golang"）：

// 引擎直连（要用到响应便捷方法时走这条；只要 net/http 习惯可用上面的 RoundTripper 形态）
p, _ := profiles.Get("chrome_150")
sess, _ := engine.NewSession(p, engine.SessionOptions{})
defer sess.Close()

resp, _ := sess.Do(&engine.Request{Method: "GET", URL: "https://example.com"})
defer resp.Close()
fmt.Println(resp.StatusCode(), resp.OK(), resp.Reason()) // 200 true OK
fmt.Println(resp.Header("content-type"))                 // 大小写不敏感
text, _ := resp.Text()                                   // charset → utf-8 → gb18030 → latin-1
var v map[string]any
_ = resp.JSON(&v)

自校验

每个响应带 selfcheck（实际发出 ClientHello 自算的 JA3/JA4，JA3/JA4R 入口还含期望值比对）；gtls_check_profile 支持 profile JSON / JA3 / JA4R / hex 四入参离线自检。

性能摘要（docs/benchmarks.md）

• FFI 调用开销：gtls_version 6–7µs、gtls_check_profile 26–30µs（<50µs 目标达成）
• 回环吞吐（每请求新连接，10s）：Go 2.6k / Python 3.4k / Node 0.95k req/s（并发 100）
• 冷启动：Session 初始化 0.2ms、首请求 ~3.5ms

已知边界（如实）

文档索引

非目标

• 不做服务端指纹采集（那是隔壁 D:\work\tls nginx 套件的事，两者互为验证端）。
• 不做浏览器级 JS 环境模拟（Canvas/WebGL 等）。
• 不内置任何绕过具体站点防护的"开箱即用"策略——只提供精确的指纹原语。