claude-cn-flag-check 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shellus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# claude-cn-flag-check
+
+> Would Claude Code covertly flag **your** environment as a "China user"? Run one command and find out.
+
+[中文说明 →](./README.zh-CN.md)
+
+In mid-2026 a [reverse-engineering report](https://www.reddit.com/r/) revealed that Claude Code (the `@anthropic-ai/claude-code` CLI, from **v2.1.91**) silently detects whether a request likely comes from mainland China and encodes the verdict into the system prompt using **Unicode steganography** — with no telemetry field and no mention in the release notes. Anthropic [confirmed it](https://www.ithome.com/0/971/118.htm) as an "experimental" anti-resale / anti-distillation measure and said it would be removed.
+
+This tool does **real detection by default**: it runs Claude Code once against a
+local endpoint and reads the marker it *actually* emits — not a prediction. It
+can also fall back to reproducing the logic locally (`--no-capture`) for a
+computed estimate. It reads nothing but your own environment; nothing is uploaded.
+
+It is **verified against `@anthropic-ai/claude-code@2.1.170`**: the domain / keyword lists are de-obfuscated straight from the installed binary at runtime, so the answer matches the version you actually run.
+
+## How the detection actually works
+
+The check only runs when you point Claude Code at a **third-party endpoint** via `ANTHROPIC_BASE_URL` (a relay/proxy). On the official `api.anthropic.com`, or with no base URL set, it is skipped entirely — *your timezone is irrelevant there*. When it does run, three orthogonal signals are computed:
+
+| Signal | Source | How it is encoded in `Today's date is …` |
+|---|---|---|
+| `cnTZ` | System timezone is `Asia/Shanghai` or `Asia/Urumqi` | Date separator `-` → `/` (e.g. `2026-07-03` → `2026/07/03`) |
+| `known` | Relay hostname matches a built-in **147-entry domain list** (exact or subdomain; the list includes a bare `cn`, so **any `*.cn` host matches**) | Apostrophe → `U+2019` |
+| `labKw` | Relay hostname contains a Chinese **AI-lab keyword** (`deepseek`, `moonshot`, `dashscope`, …) | Apostrophe → `U+02BC` |
+| both `known` + `labKw` | — | Apostrophe → `U+02B9` |
+
+The apostrophe in `Today's` and the date separator together form a 2–3 bit marker that the server reads back — visually identical to the normal line in any editor.
+
+## Install
+
+```bash
+npm install -g claude-cn-flag-check
+# or run once without installing:
+npx claude-cn-flag-check
+```
+
+Requires Node.js ≥ 18. (Node is already present if you have Claude Code installed.)
+
+## Usage
+
+Check your current environment:
+
+```bash
+claude-cn-flag-check
+```
+
+The CLI lists every detection item, reveals each result with a short scan
+animation (like a web scanner), then prints a **0-100 risk score** and a verdict.
+Output is in Chinese (the primary user base); `--json` keeps English keys.
+Example (a China timezone behind a listed relay - the worst case, abridged):
+
+```
+检测项(4 项区域信号)
+  ⚑ 端点类型  第三方中转 · 触发地区检测
+  ✗ 系统时区 (权重 40)  命中 · 中国时区,把日期分隔符 - 改成 /
+  ✗ 中转域名清单 (权重 35)  命中 · 撇号被改成 U+2019
+  ✓ AI 实验室关键词 (权重 25)  未命中
+
+  风险分  75/100  [高]
+
+✗ 会被识别为中国大陆请求。进入封号风控队列的可能性:高
+```
+
+### Risk score
+
+Only the three real CLI signals count toward the score (browser signals like
+fonts or `navigator.language` are irrelevant to the CLI and are excluded).
+`marked` stays a deterministic yes/no; the score grades severity:
+
+| Signal | Weight |
+|---|---|
+| `cnTZ` - China timezone (leaks even through a proxy) | 40 |
+| `known` - relay host on the domain list | 35 |
+| `labKw` - relay host contains an AI-lab keyword | 25 |
+
+Levels: `safe` (0) · `low` (1-30) · `medium` (31-60) · `high` (61-100). A
+first-party endpoint always scores 0.
+
+The process **exits `1` when you would be flagged**, `0` when you are clean — so you can gate a startup script:
+
+```bash
+claude-cn-flag-check >/dev/null || echo "⚠️  this shell would be marked by Claude Code"
+```
+
+### What-if checks
+
+Test a hypothetical relay or timezone without changing your environment:
+
+```bash
+claude-cn-flag-check --base-url https://my-relay.example.com --tz Asia/Tokyo
+```
+
+### Options
+
+| Flag | Meaning |
+|---|---|
+| `--base-url <url>` | Check a hypothetical `ANTHROPIC_BASE_URL` |
+| `--tz <zone>` | Check a hypothetical IANA timezone |
+| `--assume-first-party` | Simulate `_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1` |
+| `--snapshot` | Use the bundled list snapshot, skip live extraction |
+| `--binary <path>` | Path to the `claude` binary to extract lists from |
+| `--show-list` | Print the decoded domain / lab-keyword lists |
+| `--json` | Machine-readable output |
+| `-h`, `--help` / `-v`, `--version` | — |
+
+## Reducing your risk
+
+- **Timezone (`cnTZ`)** — launch Claude Code with a non-China zone: `TZ=Asia/Tokyo claude`. This is the single most effective fix, because your OS timezone leaks even through a proxy.
+- **Relay hostname (`known` / `labKw`)** — use a relay whose hostname is not on the list and does not contain an AI-lab keyword or a `.cn` suffix. Self-hosting on a neutral domain avoids both.
+- **Disable entirely** — `_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1` turns the whole mechanism off (it tells the client to treat your base URL as first-party). Understand the implication before relying on it.
+
+## Use as a library
+
+```js
+const { check, isClaudeChinaUser } = require('claude-cn-flag-check');
+
+isClaudeChinaUser();                                  // boolean, current env
+check({ baseUrl: 'https://r.example.com', timezone: 'Asia/Shanghai' });
+// → { marked, signals: { cnTZ, known, labKw }, carrier: { dateLine, ... }, features: [...] }
+```
+
+## Real detection (default)
+
+By default the tool performs a genuine capture rather than a prediction:
+
+1. It resolves your real relay host from config (see below).
+2. It writes a throwaway `CLAUDE_CONFIG_DIR` pointing `ANTHROPIC_BASE_URL` at a
+   local capture server, and temporarily maps the real relay host →
+   `127.0.0.1` in `/etc/hosts` (backed up and restored, with signal handlers)
+   so Claude Code still sees the **real hostname** while the request lands
+   locally.
+3. It runs `claude -p` once and reads the `Today's date is …` line from the
+   actual request body, extracting the observed apostrophe + date separator.
+
+This needs **root** (to touch `/etc/hosts`) and a working `claude` binary. No
+real credentials are used — the request is intercepted locally — and your real
+`~/.claude` is never modified. Reports show `真实捕获 ✓` (observed) vs
+`计算预测` (computed).
+
+- `--no-capture` — skip the run, use the computed reproduction instead.
+- What-if checks (`--base-url` / `--tz`) and first-party endpoints are always
+  computed / certain (nothing to observe).
+
+## Config resolution (evidence-based)
+
+The tool does **not** trust the current process's environment variables alone —
+those reflect whatever shell spawned it, so `claude` and `claude-cn-flag-check`
+run from different shells can disagree. Instead it resolves what Claude Code
+will *actually* use and prints every source it checked:
+
+- **`ANTHROPIC_BASE_URL`** — merged from `env` blocks across enterprise managed
+  settings, `~/.claude/settings.json`, project `.claude/settings.json`, and
+  `.claude/settings.local.json`, then the live process env (session-dependent,
+  flagged as such). This is why a relay configured only in `settings.json` is
+  correctly detected even when your interactive shell has nothing exported.
+- **Timezone** — a `TZ` override from those same `env` blocks, otherwise the
+  system zone from `/etc/localtime` (or `/etc/timezone`).
+
+`--base-url` / `--tz` still override everything for what-if checks. The
+`--json` output includes the full `resolution` evidence trail. (`ANTHROPIC_AUTH_TOKEN`
+and other secrets are never read or printed.)
+
+## How it stays accurate
+
+By default the lists are extracted from your installed binary at runtime: the tool scans for the XOR-encoded base64 blobs, brute-forces the single-byte key, and validates the decode against known sentinel domains — so it keeps working across minified releases. If extraction fails it falls back to a version-stamped snapshot (currently `2.1.170`: 147 domains, 11 keywords).
+
+## Disclaimer
+
+For transparency and self-audit only. Based on public reverse-engineering; not an official Anthropic statement, and behavior may change between Claude Code versions (Anthropic announced removal of this mechanism). Verify against your own installed version with `--show-list`.
+
+## License
+
+MIT © shellus

package/README.zh-CN.md

@@ -0,0 +1,162 @@
+# claude-cn-flag-check
+
+> Claude Code 会不会把**你**的环境悄悄标记成「中国用户」?一条命令就能自查。
+
+[English →](./README.md)
+
+2026 年年中,有人[逆向](https://www.reddit.com/r/)发现 Claude Code(`@anthropic-ai/claude-code` CLI,自 **v2.1.91** 起)会静默判断一条请求是否来自中国大陆,并用 **Unicode 隐写术**把结果编码进 system prompt——不走任何遥测字段,发布日志里也只字未提。Anthropic 随后[承认](https://www.ithome.com/0/971/118.htm)这是一项「实验性」的防转售 / 防蒸馏措施,并称将移除。
+
+本工具**默认进行真实检测**:实际运行一次 Claude Code、指向本地端点,读取它*真正*
+发出的隐写标记——不是预测;也可退回本地复刻逻辑做计算估算(`--no-capture`)。只读取
+你自己的环境,不上传任何数据。
+
+已针对 **`@anthropic-ai/claude-code@2.1.170` 验证**:域名 / 关键词清单在运行时直接从你已安装的二进制里去混淆解出,因此结论与你实际运行的版本一致。
+
+## 检测机制到底是怎样的
+
+只有当你通过 `ANTHROPIC_BASE_URL` 把 Claude Code 指向**第三方端点**(中转站 / 代理)时才会触发。走官方 `api.anthropic.com`、或没设 base URL 时**完全跳过**——那种情况下**时区无所谓**。触发时会计算三个正交信号:
+
+| 信号 | 来源 | 如何编码进 `Today's date is …` |
+|---|---|---|
+| `cnTZ` | 系统时区为 `Asia/Shanghai` 或 `Asia/Urumqi` | 日期分隔符 `-` → `/`(如 `2026-07-03` → `2026/07/03`) |
+| `known` | 中转 hostname 命中内置 **147 条域名清单**(精确或子域;清单含裸 `cn`,所以**任何 `*.cn` 主机都命中**) | 撇号 → `U+2019` |
+| `labKw` | 中转 hostname 含中国 **AI 实验室关键词**(`deepseek`、`moonshot`、`dashscope` 等) | 撇号 → `U+02BC` |
+| `known` + `labKw` 同时命中 | — | 撇号 → `U+02B9` |
+
+`Today's` 里的撇号 + 日期分隔符共同构成一个 2–3 bit 标记,服务器侧读回——在任何编辑器里都和正常那行长得一模一样。
+
+## 安装
+
+```bash
+npm install -g claude-cn-flag-check
+# 或免安装直接跑一次:
+npx claude-cn-flag-check
+```
+
+需要 Node.js ≥ 18(装了 Claude Code 就一定有 Node)。
+
+## 使用
+
+自查当前环境:
+
+```bash
+claude-cn-flag-check
+```
+
+CLI 会先把所有检测项列出来,再用扫描动画逐项刷新结果(像网页扫描器),最后给出
+**0–100 风险分**与判定。输出为中文;`--json` 保留英文结构化字段。示例(中国时区 +
+命中清单的中转,最坏情况,已省略部分):
+
+```
+检测项(4 项区域信号)
+  ⚑ 端点类型  第三方中转 · 触发地区检测
+  ✗ 系统时区 (权重 40)  命中 · 中国时区,把日期分隔符 - 改成 /
+  ✗ 中转域名清单 (权重 35)  命中 · 撇号被改成 U+2019
+  ✓ AI 实验室关键词 (权重 25)  未命中
+
+  风险分  75/100  ██████████████████░░░░░░  [高]
+
+✗ 会被识别为中国大陆请求。
+  进入封号风控队列的可能性:高
+```
+
+### 风险分
+
+只有三个真正影响 CLI 的信号计入评分(字体、`navigator.language` 等浏览器信号对 CLI
+无意义,已剔除)。`marked` 仍是确定性的是/否,评分只表示严重程度:
+
+| 信号 | 权重 |
+|---|---|
+| `cnTZ` — 中国时区(挂代理也会泄露) | 40 |
+| `known` — 中转主机命中域名清单 | 35 |
+| `labKw` — 中转主机含 AI 实验室关键词 | 25 |
+
+分档:`安全`(0)· `低`(1–30)· `中`(31–60)· `高`(61–100)。第一方端点恒为 0。
+
+**会被标记时进程退出码为 `1`**,干净时为 `0`,便于接进启动脚本做环境门禁:
+
+```bash
+claude-cn-flag-check >/dev/null || echo "⚠️  当前 shell 会被 Claude Code 打标记"
+```
+
+### 假设性检查(What-if)
+
+不改动环境,测试某个中转或时区:
+
+```bash
+claude-cn-flag-check --base-url https://my-relay.example.com --tz Asia/Tokyo
+```
+
+### 选项
+
+| 参数 | 含义 |
+|---|---|
+| `--base-url <url>` | 检查一个假设的 `ANTHROPIC_BASE_URL` |
+| `--tz <zone>` | 检查一个假设的 IANA 时区 |
+| `--assume-first-party` | 模拟 `_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1` |
+| `--snapshot` | 用内置清单快照,跳过实时提取 |
+| `--binary <path>` | 指定用于提取清单的 `claude` 二进制路径 |
+| `--show-list` | 打印解码出的域名 / 关键词清单 |
+| `--json` | 机器可读输出 |
+| `-h`, `--help` / `-v`, `--version` | — |
+
+## 如何降低风控值
+
+- **时区(`cnTZ`)**——用非中国时区启动:`TZ=Asia/Tokyo claude`。这是**最有效**的一招,因为系统时区即使挂了代理也会泄露。
+- **中转 hostname(`known` / `labKw`)**——换一个不在清单、且不含 AI 实验室关键词、也不是 `.cn` 后缀的中转;用中性域名自建可同时避开两者。
+- **彻底关闭**——`_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1` 可关掉整套机制(让客户端把你的 base URL 当作第一方)。依赖前请了解其影响。
+
+## 作为库调用
+
+```js
+const { check, isClaudeChinaUser } = require('claude-cn-flag-check');
+
+isClaudeChinaUser();                                  // 布尔,当前环境
+check({ baseUrl: 'https://r.example.com', timezone: 'Asia/Shanghai' });
+// → { marked, signals: { cnTZ, known, labKw }, carrier: { dateLine, ... }, features: [...] }
+```
+
+## 真实检测(默认)
+
+默认做的是真实捕获,不是预测:
+
+1. 从配置解析出你真实的中转主机(见下节)。
+2. 写一个临时 `CLAUDE_CONFIG_DIR`,把 `ANTHROPIC_BASE_URL` 指向本地捕获服务器,并
+   临时在 `/etc/hosts` 里把真实中转主机映射到 `127.0.0.1`(自动备份+还原+信号兜底),
+   这样 Claude Code 仍**看到真实主机名**,而请求落到本地。
+3. 运行一次 `claude -p`,从真实请求体里读出 `Today's date is …` 那行,提取观测到的
+   撇号 + 日期分隔符。
+
+这需要 **root**(改 `/etc/hosts`)和可用的 `claude`。**不使用真实凭证**(本地拦截),
+**不修改**你真实的 `~/.claude`。报告会标注 `真实捕获 ✓`(观测)或 `计算预测`。
+
+- `--no-capture`——不运行 claude,改用复刻逻辑做计算。
+- what-if(`--base-url` / `--tz`)与第一方端点始终为计算 / 确定(无可观测对象)。
+
+## 配置解析(基于依据)
+
+工具**不只信**当前进程的环境变量——那反映的是启动它的那个 shell,所以从不同 shell
+跑 `claude` 和 `claude-cn-flag-check` 可能不一致。它会解析 Claude Code **实际会用**的
+配置,并把检查过的每个来源都打印出来:
+
+- **`ANTHROPIC_BASE_URL`**——合并企业管理设置、`~/.claude/settings.json`、项目
+  `.claude/settings.json`、`.claude/settings.local.json` 的 `env` 块,再叠加进程环境
+  变量(会话相关,已标注)。所以**只在 `settings.json` 里配了中转、交互 shell 没
+  export** 的情况,也能被正确检出。
+- **时区**——先看上述 `env` 块里的 `TZ` 覆盖,否则读系统 `/etc/localtime`(或
+  `/etc/timezone`)。
+
+`--base-url` / `--tz` 仍可覆盖一切做假设检查。`--json` 输出包含完整的 `resolution`
+依据链。(`ANTHROPIC_AUTH_TOKEN` 等密钥永远不读取、不打印。)
+
+## 准确性如何保证
+
+默认在运行时从你已安装的二进制提取清单:扫描 XOR 编码的 base64 blob,暴力破解单字节密钥,再用已知哨兵域名校验解码结果——因此在混淆变量名逐版本变化的情况下依然可用。提取失败时回退到打了版本戳的内置快照(当前 `2.1.170`:147 域名、11 关键词)。
+
+## 免责声明
+
+仅用于透明性与自查。基于公开逆向分析,非 Anthropic 官方结论,且行为可能随 Claude Code 版本变化(Anthropic 已宣布将移除该机制)。请用 `--show-list` 对照你自己安装的版本。
+
+## 许可证
+
+MIT © shellus