mtgodot-poc/audit/contracts/network.security-encoding.md

# network.security_encoding

## Scope

完整核对 40250 客户端的握手时间基准、后续 time sync、sequence 表和 `bSeq` 规则、`_IMPROVED_PACKET_ENCRYPTION_` 的 DH2/CTR、未启用 improved encryption 时的 TEA 安全分支、HybridCrypt/pack 注入、locale codepage、定长字符串以及连接清理。判断标准是调用链、分支条件、状态转移顺序、时钟/资源来源和失败副作用是否一致；“当前端有同名算法”不等于已对齐。

## Reference call chain

- `UserInterface/PythonNetworkStreamPhaseHandShake.cpp`
  - `CPythonNetworkStream::HandShakePhase`
  - `CPythonNetworkStream::RecvHandshakePacket`
  - `CPythonNetworkStream::RecvHandshakeOKPacket`
  - `CPythonNetworkStream::RecvHybridCryptKeyPacket`
  - `CPythonNetworkStream::RecvHybridCryptSDBPacket`
  - `CPythonNetworkStream::RecvKeyAgreementPacket`
  - `CPythonNetworkStream::RecvKeyAgreementCompletedPacket`
- `UserInterface/PythonNetworkStreamPhaseLogin.cpp`, `PythonNetworkStreamPhaseSelect.cpp`, `PythonNetworkStreamPhaseGame.cpp`
  - 各阶段 `HEADER_GC_HANDSHAKE`、`HEADER_GC_HANDSHAKE_OK`、HybridCrypt 和 key-agreement allowlist；每个 packet handler 完成后立即从该阶段处理函数返回。
- `UserInterface/AccountConnector.cpp`
  - auth connector 的重复 handshake、ping/sequence、legacy security、登录成功后的 Panama key 和 game stream 切换。
- `EterLib/NetStream.cpp`
  - `CNetworkStream::SetSecurityMode`、`IsSecurityMode`、`SendSequence`、`__SendInternalBuffer`、`Clear`、`Connect`、`ActivateCipher`。
- `EterBase/cipher.cpp`, `cipher.h`
  - DH2 Prepare/Agree、算法选择、密钥/IV 派生和 CTR stream 状态。
- `EterBase/tea.cpp`
  - 未定义 `_IMPROVED_PACKET_ENCRYPTION_` 时的收发 TEA 缓冲区及 8-byte 对齐。
- `EterLocale/StringCodec.cpp`、`UserInterface/Locale*.h/.cpp`
  - Windows `WideCharToMultiByte`/`MultiByteToWideChar`、CP1258 特殊处理和 locale codepage 来源。

40250 的具体时钟语义：初始 handshake 设置全局 `ELTimer_SetServerMSec(dwTime + lDelta)`，回显 `dwTime + 2*lDelta`、`lDelta=0`，之后调用 `CTimer::SetBaseTime()`；Select/Game 的 handshake 保存 `m_kServerTimeSync`，发送 `HEADER_CG_TIME_SYNC` 并追加 sequence；收到 `HEADER_GC_HANDSHAKE_OK` 后用收到 blank 的本地耗时重新设置全局 server msec。这个全局 owner 和二次校准不能用“本地 stream 能计算一个相对时间”替代。

## Current call chain

- `extension/src/net/classic/classic_stream.cpp/.h`
  - `handle_control` 处理 handshake、`HDR_GC_TIME_SYNC`、key agreement/completed、ping、phase；`server_frame_ms` 用 `steady_clock` 与每个 `ClassicStream` 的两个基准值计算。
  - `emit_bytes` 在进入发送队列时立即加密；`flush_send` 只负责写 socket。
- `extension/src/net/classic/classic_cipher.cpp/.h`
  - 当前实现包含 40250 DH2/CTR 所需的 RFC 5114 参数、算法 selector、key/IV 派生和双向 CTR 状态。
- `extension/src/net/classic/sequence_table.h`, `wire_classic.h`
  - 内置 32768-byte sequence 表和 `is_sequence_cg` 规则。
- `extension/src/net/classic/classic_session.cpp`, `extension/src/net/m2_client.cpp`
  - phase/版本发送、time-sync mode 和 Godot 网络生命周期。
- `extension/src/net/secure_cipher.cpp/.h`
  - 另一套 libsodium X25519/XChaCha20-Poly1305 backend；它不是 40250 `EterBase::Cipher` 的替代实现，不能作为 classic improved-encryption 的等价证据。
- `extension/src/net/text_codec.h/.cpp`
  - classic fixed text now crosses one explicit UTF-8 -> GB2312/GBK wire boundary;
    fixed fields are capped after conversion and decoded back to UTF-8.

## Branch matrix

| 场景 | 40250 完整行为 | 当前端实际行为 | 结论 |
|---|---|---|---|
| 初始 handshake | 读取固定包，设置全局 `ELTimer`，回显 `time+2*delta`/`delta=0`，调用 `CTimer::SetBaseTime`；auth connector 也有自己的同类路径 | 保存 `m_server_time_base`/`m_client_time_base`，回显字节基本一致；没有全局 `ELTimer`/`CTimer` owner，auth/game 也没有统一时钟服务 | `PARTIAL`：wire 主体接近，时间副作用和 owner 不同 |
| Select/Game 后续 handshake | 保存 `m_kServerTimeSync`，发 `0xFC + handshake + sequence`；收到 blank `HANDSHAKE_OK` 后按 `changeClientTime` 到达时间重新设置全局 server clock | `ClassicStream` 暂存后续 handshake 的 server/client 基准，发 `0xFC`/sequence；收到 blank 后才提交二次校准 | `PARTIAL`：stream 语义已对齐，仍缺少全局 clock owner/跨 connector fixture |
| improved DH2/CTR | `Prepare`→`Activate`→发送固定 key-agreement reply→收到 completed 后 `ActivateCipher`；completed 前后的缓冲和状态顺序由 `CNetworkStream` 控制 | `ClassicCipher` 的 DH2/selector/派生公式接近 reference；stream 也实现 reply/completed/已缓冲密文解密 | `PARTIAL`：算法可做双端 round-trip，但没有 40250 server fixture、固定边界/失败分支和真实分片互操作证据 |
| improved 发送时点 | 明文先进入 send buffer，`__SendInternalBuffer` 在真正 flush 时按当前 security mode 加密 | `emit_bytes` 在排队时立即加密，随后再 flush | `PARTIAL`：通常字节顺序相同，但队列、重复 flush、切换 security mode 和部分写时点不是同一语义 |
| legacy TEA | 未定义 improved 时 `SetSecurityMode` 保存独立收发 key；接收按 8-byte 缓冲解密，发送按 8-byte 对齐/缓存后发送；auth/game 均可启用 | classic 侧没有完整的 `SetSecurityMode`/TEA 收发缓冲调用链；`classic_cipher` 中的 TEA 只是可选 DH2 algorithm selector，不是 legacy stream mode | `PARTIAL`：分支没有实现为同一协议路径 |
| HybridCrypt keys/SDB | handshake、login、select、game 阶段均允许动态包；消费固定头+精确 stream 长度，并注入 `CEterPackManager` | header 在 wire table 中可识别，但 classic session/parser 没有等价 pack manager 注入，当前会拒绝或忽略该可选资源分支 | `PARTIAL`：动态 framing 不是完整功能等价 |
| Panama pack/login key | auth 成功按 `loginKey XOR g_adwEncryptKey[0..3]` 解密 pack IV，设置 login key，再连接 game stream | 当前登录/资源主链没有 40250 Panama pack IV 解密和同一 auth→game 交接证据 | `PARTIAL`：资源/密钥副作用缺失或未证明 |
| anti-cheat/HackShield/XTrap | 40250 handshake/game allowlist 有条件编译的 HS/XTrap request/response 分支 | header/尺寸部分存在，但没有 Windows anti-cheat provider 或完整 response 处理 | `PARTIAL`：条件分支未等价 |
| sequence table | `SEQUENCE_TABLE_SIZE=32768`，`SendSequence` 在 bSeq 开启后逐包取表项、到末尾回 0；bSeq 来自 packet registration | 当前内置 32768 表并按 `is_sequence_cg` 添加 trailer；代码注释声称 verbatim，但还没有和 40250 源数组的 hash/逐项生成校验 | `PARTIAL`：主路径存在，证据和注册矩阵未闭合 |
| 版本包 | 根据 locale/region 选择 `CG_CLIENT_VERSION2` 或 `CG_CLIENT_VERSION`，固定字段按 Windows locale 字节复制 | 当前已按 `m_locale_is_europe` 选择两个包，字段走 UTF-8 `to_wire` | `PARTIAL`：header/分支存在，非 ASCII 字节语义仍不同 |
| locale 转码 | `LocaleService_GetCodePage` + Windows codepage 转换；中文固定字段使用 GB2312-compatible bytes；固定字段本质是 byte array/`strncpy` | classic 使用 Windows CP936 或 POSIX iconv 的 GB2312/GBK 转码；Godot/Native 内部仍保持 UTF-8；其它 locale codepage 尚未接入 | `PARTIAL`：40250 中文固定字段已对齐，非中文 locale 仍不同 |
| fixed string/NUL | reference 对固定 `char[]` 以字节 cap、NUL 结尾和 struct zero-fill 为准；不可表示字符遵循 Win32 codepage 策略 | classic `to_wire()` 在 GB2312 字节上限后截断且结构体 zero-fill；`wire_text_fits()` 按编码后字节拒绝超长/不可表示值；无系统 codec 的平台拒绝高位字节而不泄漏 UTF-8 | `PARTIAL`：中文字段已对齐，fallback/其它 locale 仍需真实 fixture |
| cleanup/failure | `Clear` 清 cipher、socket、TEA buffer、recv/send positions 和 sequence；key agreement/发送失败按阶段返回并由上层断开 | `disconnect` 清 stream/cipher/buffer/sequence；缺少 legacy buffer、global timer、HybridCrypt/pack 和 auth connector 分层清理矩阵 | `PARTIAL` |

## Equivalence matrix

| 项目 | 状态 | 证据 |
|---|---|---|
| Preconditions | `PARTIAL` | classic 对固定长度、DH2 key-ready、completed 顺序有保护；legacy/hybrid/anti-cheat 和阶段 allowlist 不完整 |
| Branch structure | `PARTIAL` | initial/time-sync/improved 主分支存在；TEA、HybridCrypt、Panama、anti-cheat 分支没有完整等价实现 |
| Algorithms/formulas | `PARTIAL` | `ClassicCipher` 的 DH2/CTR 公式与参数接近 reference；缺少 40250 server 密文 fixture，且 legacy TEA stream 没有主链 |
| State transition order | `PARTIAL` | completed 后激活和已有缓冲解密存在；global clock 二次校准、auth/game 双 connector、flush 时加密时点不同 |
| Constants/units | `PARTIAL` | handshake/header/32768 sequence 常量已定位；locale byte cap、TEA block/buffer 和 optional packet size 规则未闭合 |
| Timing/event sources | `PARTIAL` | 当前每个 stream 使用 `steady_clock`，并在 `HANDSHAKE_OK` 提交暂存基准；40250 使用全局 `ELTimer`，auth/game 共用时钟 owner 仍不同 |
| Resource/data sources | `PARTIAL` | key/sequence/version 来源已定位；当前没有真实 locale codepage 和 EterPack HybridCrypt/Panama 注入来源 |
| Protocol side effects | `PARTIAL` | handshake/key reply/ping/version 有路径；clock、pack IV、HybridCrypt 和 anti-cheat side effect 缺失或未证明 |
| Interruption/failure/cleanup | `PARTIAL` | classic disconnect 会清基本状态；TEA 对齐缓存、auth connector 和可选资源的失败/重入/断开组合未覆盖 |

## Evidence already available

- `extension/tests/net_classic_cipher_test.cpp`：client/server polarity 的 DH2 round-trip、CTR 连续性和新会话密钥差异。
- `extension/tests/net_classic_encstream_test.cpp`：handshake、key agreement、completed、已缓冲密文和 sequence 的 stream happy path。
- `extension/tests/net_text_codec_test.cpp`：12 个中文字符在 24 个 GB2312 字节内 round-trip、13 个字符被拒绝、真实中文名称和 32 字节商店招牌边界。
- `extension/tests/net_classic_session_test.cpp`：角色创建/改名包验证实际写入 GB2312 字节、NUL 结尾和 24 字节边界。
- `extension/src/net/classic/sequence_table.h`：32768 项静态表和编译期长度断言；`audit_sequence_table.py` 已逐字节比对 40250 数组，SHA-256 为 `3f6f31964896e712f1f54cb813c7b488b656f700f6ca948ece3313419f876279`。

## Deep audit round 2026-09-20

本轮重新检查 `ClassicStream::handle_control/emit_bytes`、`ClassicCipher`、sequence 表和文本边界，并重跑当前加密/编码回归：

- `net_classic_cipher_test`、`net_classic_encstream_test` 和 `net_text_codec_test` 均退出码 0；它们证明当前 DH2/CTR round-trip、连续 CTR、key agreement/已缓存密文、sequence trailer 和 UTF-8 codepoint-safe 截断没有回归。
- 当前 `HANDSHAKE_OK` 已提交后续 handshake 的暂存 server clock；`server_frame_ms()` 仍是每个 `ClassicStream` 的 steady-clock 相对计算，尚未接入 40250 `CTimer/ELTimer` 全局 owner。`net_classic_stream_test` 已覆盖 blank 前不跳时钟、blank 后完成校准。
- 当前 `emit_bytes()` 在进入发送队列时加密，参考端在真正 flush internal buffer 时按当前 security mode 加密；在正常单次发送中可能得到相同字节，但切换 security mode、部分写、重复 flush 和失败清理的状态边界不同。
- `classic_cipher` 中的 TEA 仅作为可选算法 selector，当前 classic stream 没有 40250 legacy `SetSecurityMode` 的独立收发 TEA block buffer 主链；HybridCrypt/SDB、Panama pack IV、HS/XTrap 和其它 locale codepage 也没有完整注入/消费路径。中文 40250 fixed text 已由 `text_codec.cpp` 在网络边界转为 GB2312/GBK-compatible bytes。
- 32768 项 sequence 表已通过 reference 数组逐字节校验；主要 `bSeq` 分支仍依赖当前 wire 注册表，未完成所有版本/locale/可选包的生成式矩阵。

结论：改进加密的局部算法和当前 wire framing 可用，但全局时钟、加密时点、legacy/optional security 分支、codepage 和 sequence 参考数据仍未闭合，合同保持 `PARTIAL`。

## Required tests before claiming parity

- 使用 40250 wire fixture 验证初始 handshake、Select/Game handshake、`HANDSHAKE_OK` 二次校准和实际 server-frame 时钟；当前已有 socket-free 二次校准回归。
- 用 40250 server polarity fixture 验证 DH2/CTR：split recv/send、flush 前后加密、重复 key agreement、completed 前后明文、非法长度、失败清理和 reconnect。
- 保持 40250 sequence 数组逐字节校验，并补齐从 `PacketInfo`/`CMainPacketHeaderMap` 生成的完整 `bSeq` 矩阵。
- 为 CP949/CP1252/CP1258 等非中文部署建立 reference byte fixtures；中文 GB2312 已覆盖不可表示字符、NUL、byte cap、固定字段 zero-fill 和反向 decode。
- 对 HybridCrypt keys/SDB、Panama pack、legacy TEA、HS/XTrap 明确支持/拒绝策略，并分别验证不乱 consume、不把包流错位、不产生错误的成功状态。

## Status

`PARTIAL`。

本轮已修复后续 handshake 的二次时钟校准，并加入 40250 sequence table 逐字节审计；DH2/CTR 的局部算法相似性仍不能覆盖全链路差异，在补齐全局 clock、locale、legacy/optional 分支和真实 wire fixture 前，合同保持 `PARTIAL`。

## Implementation fix round 2026-09-21 — Chinese fixed-field wire encoding

按 40250 中文客户端的 `LocaleService_GetCodePage`/固定 `char[]` 语义补齐文本边界：Godot 和 native 业务层继续以 UTF-8 保存文本，`text_codec.cpp` 在 classic 发送前按 Windows CP936 或 POSIX GB2312/GBK 转码；`wire_text_fits()` 在转码后按字节容量校验，`to_wire()` 只写完整的 GB2312 字符并依靠 zero-initialized packet 保留 NUL。接收路径用同一 codepage 解回 UTF-8。没有系统 codepage codec 的平台不会把高位 UTF-8 字节直接发送到 40250 字段，而是将该值标记为不可表示。

角色创建、改名以及聊天、密语、公会、商店等 classic 固定/动态文本发送入口均使用这个边界；地图名、任务名和系统提示仍按各自动态包长度处理，不套用 24 字节角色名限制。

回归：`net_text_codec_test`、`net_classic_session_test`、`net_classic_stream_test`、`net_loopback_test`、CTest 23/23、Godot 生命周期/角色选择/移动回归和 `git diff --check` 通过。中文角色名实际创建/改名包已证明 12 个汉字占 24 个 GB2312 字节，13 个汉字被拒绝。合同仍保持 `PARTIAL`，因为 legacy TEA、可选安全分支、其它 locale codepage 和真实服务端中文建号包序仍未完全闭合。

## Implementation fix round 2026-09-21

按 40250 `RecvHandshakePacket`/`RecvHandshakeOKPacket` 修复 `ClassicStream`：Select/Game 后续 handshake 只保存 pending server/client 基准，发送 `CG_TIME_SYNC` 后等待一字节 `HANDSHAKE_OK`，再按到达耗时提交 server clock；断开时清理 pending 状态，避免下次连接复用旧校准。新增 `audit_sequence_table.py`，对 40250 `EterLib/NetStream.cpp` 的 32768 项 sequence table 与当前静态表逐字节比较，当前两端 SHA-256 完全一致。

回归：`net_classic_stream_test`、`net_classic_session_test`、sequence table audit 和 `git diff --check` 通过。全局 `ELTimer/CTimer` owner、legacy TEA、HybridCrypt/Panama/HS-XTrap、Windows codepage、flush 时加密时点和真实 server fixture 仍保持 `PARTIAL`。