Skip to content
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ Versions follow the merge of a `*_release-v*` branch; CI publishes to npm on tag

### Features

- **Session-file encryption at rest behind `BILI_ENCRYPTION_KEY` (#708, PR #711)**: for deployments on untrusted nodes, persisted session files (block summaries plus up to ~16k tokens of folded conversation per session — effectively full conversation content) can now be stored as `BILIENC1` AES-256-GCM over zstd-compressed JSON (zstd via built-in node:zlib on Node ≥ 22.15, raw mode byte on older runtimes; compression also shrinks files ~5–10×). The key is env-only — deliberately NO key-file support, since a key file would sit on the same untrusted filesystem as the data — exactly 32 bytes hex or base64, never written to disk or logs; an invalid value aborts startup (fail fast instead of silently running unencrypted). When enabled, boot takes over legacy plaintext files once: each is re-encoded and atomically replaced in place (the rename IS the old-file deletion; a crash mid-migration self-heals on the next boot), covering `.fb.json` spill files too; unreadable files are left in place with a warning. Wrong key at boot → GCM auth failure → affected sessions skip as corrupt (logged, no crash). Mechanism is the kernel's optional `StateStore` codec hook (acp-kernel#249 → 0.0.64); unset key = zero behavior change.
- **Per-route `passthrough` option for providers (#661, PR #662)**: `"providers": { "mitm://zcode.z.ai": { "passthrough": true } }` forwards matching requests byte-for-byte — no kernel round-trip, no render tags, no `prompt_cache_key` removal, response piped verbatim, no session state — the scoped sibling of the global `passthrough` switch. `mitm://` keys target only MITM (login-client) traffic; plain `https://` host keys cover both MITM and `/bili/` traffic.

- **Round-evidence closure for compress-reasoning drop (#651, #348 twin)**: the closure gate shipped with the reasoning drop — "compress call followed by a genuine user message" — is unreachable in long agentic sessions (no user messages after the opening prompt, observed: 0 drops while 30 compress rounds retained 20.6K/8.4K/10.6K-char thinking floors). A round now closes on tool-result evidence: the compress call's `tool-result` (matching `toolCallId`) exists at a later index and at least one message follows it. In-flight rounds (result missing or still the last message) stay untouched; per-provider `compress.providers.<name>.reasoning.drop=false` escape hatch preserved for reasoning-replay models (GLM). Mirrors billion-context-pi #348 (PR #349).
Expand Down
1 change: 1 addition & 0 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -446,6 +446,7 @@ Environment variables take precedence over the config file. They are useful for
| `BILI_TUNNEL_ALLOWED_HOSTS` | `/bili/<absolute-url>` tunnel admission for **remote clients** (#409): comma-separated `host` or `host:port` entries that unlock loopback/private destinations (e.g. a LAN relay or the machine's own sglang) for non-loopback clients. The proxy itself and link-local/metadata addresses are always denied; local (loopback) clients always pass. |
| `BILI_MAX_SESSIONS` | Max sessions held in memory (default `256`; LRU eviction — disk is the source of truth). |
| `BILI_SESSIONS_DIR` | Directory for persisted session state (default XDG data dir). |
| `BILI_ENCRYPTION_KEY` | Encrypt session files at rest (#708) for deployments on untrusted nodes. Exactly 32 bytes, hex (64 chars) or base64; unset = plain JSON files (default behavior, unchanged). When set: every session file is written as `BILIENC1` AES-256-GCM over zstd-compressed JSON (zstd on Node ≥ 22.15, raw body on older runtimes) — compression also shrinks the file ~5–10×. Existing unencoded files are taken over once at boot: each is re-encoded and atomically replaced in place (the rename IS the old-file deletion; a crash mid-migration self-heals on next boot). The key comes ONLY from this environment variable — never written to disk or logs — so keep it out of the same filesystem's reach. Invalid values abort startup (fail fast, never silently unencrypted). Booting with the wrong key skips the affected sessions as corrupt (logged, no crash). Losing the key makes encrypted sessions permanently unreadable. Symmetric by design (the same process encrypts and decrypts). Threat model (#708, owner-confirmed): it defends against **offline/mechanical** file acquisition — provider disk swaps, offline disk snapshots after node-image drift, stolen volumes, leaked backups, cloud-synced state dirs — where an offline third party cannot read the content without the key. It does NOT defend against targeted adversaries with live access to the node; for that tier move the trust root out of the proxy (KMS / TEE / confidential VMs, hardened permissions) instead of solving it inside the proxy — at that level far more than the key is exposed, so proxy-level key handling is not the boundary to hold (`BILI_PERSIST=0` disables persistence entirely). Double-encrypting the key with a second key from the same process/environment adds nothing: in every offline-theft scenario the attacker lacks exactly one artifact — your off-disk secret — whether it is called the data key or the wrapping key; only a wrapping key in a different trust domain (KMS/TPM/TEE) raises the bar, and that is scenario 2 above. |
| `BILLION_CONTEXT_PROXY` | Exported by the launcher; client-side bili plugins/extensions detect it and self-disable their own compression (no double compression). |
| `BILLION_CONTEXT_PLUGIN` | Set `0` to disable plugin mode entirely (wire-level tool injection resumes). |
| `BILI_LAUNCHER_MODEL_WINDOWS` | Internal: the launcher hands the client's own per-model context windows (pi `models.json`, omp `models.yml`, opencode `models.<id>.limit`, codex `model_context_window`) to the spawned proxy as JSON, so the nudge denominator matches the real window for self-hosted models. Only the launcher sets it — no user configuration. |
Expand Down
1 change: 1 addition & 0 deletions CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -444,6 +444,7 @@
| `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | persist EPERM 告警的重复窗口(毫秒)。`0`(默认)= 只告警一次后静默;`>0` = 失败持续期间最多每这么久重复告警一次。 |
| `BILI_MAX_SESSIONS` | 内存中最多保留的会话数(默认 `256`;LRU 淘汰 —— 磁盘是事实源)。 |
| `BILI_SESSIONS_DIR` | 会话持久化目录(默认 XDG data 目录)。 |
| `BILI_ENCRYPTION_KEY` | 会话文件静态加密(#708),适用于部署在不可信节点的场景。密钥必须恰好 32 字节,hex(64 字符)或 base64;不设置 = 明文 JSON 文件(默认,行为不变)。设置后:每个会话文件以 `BILIENC1` AES-256-GCM 加密 zstd 压缩后的 JSON 写入(Node ≥ 22.15 启用 zstd,旧版本写原始数据)——压缩同时可使文件缩小约 5–10 倍。已有的未编码文件在启动时一次性接管:逐个重新编码并原子替换到原路径(rename 即旧文件的删除;迁移中途崩溃会在下次启动自愈)。密钥只从该环境变量读取——永不落盘、永不进日志——请确保它不受同一文件系统上的其他进程触及。非法值会导致启动中止(快速失败,绝不静默明文运行)。用错误的密钥启动时,受影响的会话按损坏文件跳过(有日志,不崩溃)。丢失密钥将使已加密的会话永久不可读。对称加密为刻意设计(同一进程既加密又解密)。威胁模型(#708,owner 确认):防的是**离线/机械性**的文件获取——云厂商换盘、节点镜像漂移后的离线磁盘快照、磁盘镜像失窃、备份泄露、被云同步的状态目录——离线第三方拿不到密钥即无法读取内容。不防御对活节点有访问权的定向攻击者;那一档应把信任根移出 proxy(KMS / TEE / 机密虚拟机 + 强化权限体系),而不是在 proxy 本身想办法——到了那个程度暴露的远不止密钥,proxy 层不是该守的边界(`BILI_PERSIST=0` 可彻底关闭持久化)。用同一进程/环境中的第二把密钥对密钥做二次加密不增加任何安全性:所有离线失窃场景里攻击者缺的始终只有一个工件——你的非落盘秘密——无论它叫数据密钥还是包裹密钥;只有把包裹密钥放进不同信任域(KMS/TPM/TEE)才能提高门槛,而那属于上面的场景 2。 |
| `BILLION_CONTEXT_PROXY` | launcher 会导出它;客户端侧 bili 插件/扩展检测到后自禁用自身压缩(避免双重压缩)。 |
| `BILLION_CONTEXT_PLUGIN` | 设 `0` 彻底关闭插件模式(恢复 wire 层工具注入)。 |
| `BILI_LAUNCHER_MODEL_WINDOWS` | 内部使用:launcher 把客户端自身配置里的逐模型上下文窗口(pi `models.json`、omp `models.yml`、opencode `models.<id>.limit`、codex `model_context_window`)以 JSON 传给自己拉起的代理,让 nudge 分母对自托管模型也用真实窗口。只有 launcher 会设置,无需用户配置。 |
Expand Down
103 changes: 103 additions & 0 deletions src/encrypt.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
import * as zlib from "node:zlib";
import type { StateStoreCodec } from "acp-kernel/persist";

/**
* Session-file encryption at rest (#708): AES-256-GCM over an optionally
* zstd-compressed JSON envelope, applied around every StateStore write/read.
*
* THREAT MODEL: the proxy may run on untrusted nodes; session files hold
* block summaries plus up to ~16k tokens of folded conversation per session
* — effectively full conversation content (code, pasted credentials). The
* key comes ONLY from the BILI_ENCRYPTION_KEY environment variable: a key
* file next to the data sits on the same untrusted filesystem and defeats
* the purpose.
*
* FORMAT (v1):
* offset 0..7 magic "BILIENC1"
* offset 8 format version (0x01)
* offset 9 body mode (0x00 raw, 0x01 zstd)
* offset 10..21 GCM nonce (random per write)
* offset 22.. AES-256-GCM ciphertext, final 16 bytes = auth tag
*
* Compression runs BEFORE encryption (GCM ciphertext is incompressible).
* node:zlib gained zstd in Node 22.15; on older runtimes the mode byte
* records a raw body so every supported version can still decrypt it.
*/

export const ENCRYPT_MAGIC = Buffer.from("BILIENC1", "utf8");
const FORMAT_VERSION = 0x01;
const MODE_RAW = 0x00;
const MODE_ZSTD = 0x01;
const NONCE_LEN = 12;
const TAG_LEN = 16;
const HEADER_LEN = ENCRYPT_MAGIC.length + 2 + NONCE_LEN;
const MIN_ENCRYPTED_LEN = HEADER_LEN + TAG_LEN;

/** Parse the BILI_ENCRYPTION_KEY value: hex or base64, must decode to
* exactly 32 bytes. Hex wins when both parse (a base64 string made only of
* hex digits is ambiguous — hex-first is the documented rule). Throws with
* an actionable message; the caller surfaces it as a startup crash (fail
* fast — never run silently unencrypted when the operator asked for it). */
export function parseEncryptionKey(value: string): Buffer {
const v = value.trim();
let buf: Buffer | null = null;
if (/^[0-9a-fA-F]+$/.test(v) && v.length % 2 === 0) {
buf = Buffer.from(v, "hex");
} else if (/^[A-Za-z0-9+/]+={0,2}$/.test(v)) {
buf = Buffer.from(v, "base64");
}
if (!buf || buf.length !== 32) {
const got = buf ? `${buf.length} bytes` : "an undecodable value";
throw new Error(
`[encrypt] BILI_ENCRYPTION_KEY must be exactly 32 bytes encoded as hex (64 chars) or base64 — got ${got}`,
);
}
return buf;
}

function zstdAvailable(): boolean {
return typeof zlib.zstdCompressSync === "function" && typeof zlib.zstdDecompressSync === "function";
}

/** Build the StateStore codec for encrypted session files. decode() passes
* buffers without the magic through untouched (legacy plaintext), so mixed
* plaintext+encrypted trees load fine and the boot-time migration can peek
* the magic before rewriting. A decode failure (wrong key, corruption)
* throws and the kernel store treats the file as corrupt (warn + skip). */
export function createSessionCodec(key: Buffer): StateStoreCodec {
return {
encode(data: string): Buffer {
const plain = Buffer.from(data, "utf8");
const useZstd = zstdAvailable();
const body = useZstd ? zlib.zstdCompressSync(plain) : plain;
const nonce = randomBytes(NONCE_LEN);
const cipher = createCipheriv("aes-256-gcm", key, nonce);
const ct = Buffer.concat([cipher.update(body), cipher.final()]);
return Buffer.concat([
ENCRYPT_MAGIC,
Buffer.from([FORMAT_VERSION, useZstd ? MODE_ZSTD : MODE_RAW]),
nonce,
ct,
cipher.getAuthTag(),
]);
},
decode(buf: Buffer): string {
if (buf.length < ENCRYPT_MAGIC.length || !buf.subarray(0, ENCRYPT_MAGIC.length).equals(ENCRYPT_MAGIC)) {
return buf.toString("utf8");
}
if (buf.length < MIN_ENCRYPTED_LEN || buf[ENCRYPT_MAGIC.length] !== FORMAT_VERSION) {
throw new Error(`[encrypt] unsupported session file format version ${buf[ENCRYPT_MAGIC.length]}`);
}
const mode = buf[ENCRYPT_MAGIC.length + 1];
const nonce = buf.subarray(HEADER_LEN - NONCE_LEN, HEADER_LEN);
const tag = buf.subarray(buf.length - TAG_LEN);
const ct = buf.subarray(HEADER_LEN, buf.length - TAG_LEN);
const decipher = createDecipheriv("aes-256-gcm", key, nonce);
decipher.setAuthTag(tag);
const body = Buffer.concat([decipher.update(ct), decipher.final()]);
const plain = mode === MODE_ZSTD ? zlib.zstdDecompressSync(body) : body;
return plain.toString("utf8");
},
};
}
Loading
Loading