Codewhale 的第三方源码治理：从 RFC 8628 设备码移植到 cargo-deny 许可基线

本文以 THIRD_PARTY_NOTICES.md 为核心，解析 Codewhale 如何划分“Cargo 依赖”与“源码级移植”两类许可边界，并以仓库中唯一的 MIT 移植案例（来自 pi-mono 的 RFC 8628 设备码轮询环）为例，逐行拆解 crates/config/src/device_code.rs 的移植细节、deny.toml 的 cargo-deny 许可与来源管控配置。读完本文，你将掌握：一个 Rust 项目如何在不引入额外工具的前提下，让许可义务“跟着代码走”，并理解设备码登录流程中 5 秒默认轮询、slow_down 退避、时钟漂移诊断等行为的实现依据。

文档管辖范围：两级许可边界的划分

THIRD_PARTY_NOTICES.md 开宗明义地声明了自己的管辖范围：除 Cargo 解析的 crate 之外，所有被 vendor 或移植进本仓库的源码。Cargo 依赖的许可由 deny.toml 中的 cargo deny 配置强制执行；而本文件只登记“源码级改编”（source-level adaptations）——这类代码的许可义务随代码本身迁移，而不是随某个包迁移。

这个划分在工程上很重要：crate 依赖的许可面由 Cargo.lock 决定，可以自动化校验；而人肉移植的代码没有任何自动机制能替你记住“这段逻辑来自谁、适用什么许可”，必须靠文档登记 + 文件头注释双重留痕。项目本身的许可是 MIT，见 LICENSE（Copyright (c) 2024-2025 DeepSeek CLI Contributors）。

唯一登记的源码移植：pi-mono（MIT）的设备码轮询环

文档登记了唯一的源码级移植条目：

• 上游项目：pi（pi-mono），作者 Mario Zechner，MIT 许可，Copyright (c) 2025 Mario Zechner；
• 移植目标：crates/config/src/device_code.rs——pi 的 OAuth 设备码轮询环与校验 URI 检查的 Rust 移植；
• 上游对应位置（文档原文给出的坐标，位于 pi-mono 仓库内）：
  • packages/ai/src/auth/oauth/device-code.ts（pollOAuthDeviceCodeFlow，即 RFC 8628 的轮询行为）
  • packages/ai/src/auth/oauth/xai.ts（validateVerificationUri）

该条目完整收录了 MIT 许可证全文：

MIT License

Copyright (c) 2025 Mario Zechner

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.

下面结合源码，看这次移植“搬”过来了哪些行为，以及 Rust 侧做了哪些工程化改造。

移植承载的 RFC 8628 行为

device_code.rs 的模块注释（L1-L21）逐条列出了从 pi 继承下来的行为，这些正是 RFC 8628 设备授权流程（Device Authorization Grant）在真实客户端里最容易被写错的部分：

行为	上游出处	Rust 侧实现
服务器省略 interval 时按 5 秒轮询（RFC 8628 §3.2）	pollOAuthDeviceCodeFlow	常量 DEFAULT_POLL_INTERVAL_SECS: u64 = 5（L28）
slow_down 时优先采用服务器给出的新 interval，而非客户端自维护值；服务器未给时按 §3.5 步进 +5 秒	同上	SLOW_DOWN_STEP_SECS: u64 = 5；run() 中的 SlowDown 分支（L146-L157）
基于 expires_in 的硬截止，slow_down 退避后也不得睡过到期时刻	同上	deadline = Instant::now() + self.lifetime，sleep(interval.min(remaining))（L130）
只要见过至少一次 slow_down 才超时就使用独立的超时文案	同上	slow_down_timeout_message 字段与 timed_out() 分支（L171-L176）

其中第 2、4 条针对的是一个具体故障场景：在 WSL 或挂起过的虚拟机里，客户端自维护的轮询间隔会因时钟漂移而永远提前触发。若只信任客户端值，服务端会持续回 slow_down 形成死循环；把“服务器给出的新 interval 优先”移植过来后，客户端以服务端权威值重置节奏，并且超时时能输出专门的“时钟漂移”提示而不是普通的 timeout，使问题可诊断。这一动机在源码注释中有明确说明（L148-L150）。

DeviceCodePoll 的构建器 API

移植版把轮询环抽象为“泛型于结果类型、自身不做任何 I/O”的纯调度器：调用方注入 sleep 与 poll 两个闭包（L125-L128），T（解析后的 token 材料）对模块完全不透明且绝不 Debug 打印——这是从上游继承的设计纪律，也是该文件“绝不持有、格式化或记录 token”承诺的落地方式。

配置项通过链式构建器设置，取值语义都直接对应 RFC 8628：

• DeviceCodePoll::new(lifetime, timeout_message)：轮询总寿命与超时文案，起始 interval 为 RFC 默认 5 秒；
• interval_seconds(Option<u64>)：透传服务器通告的 interval；None 或 0（RFC 8628 允许缺省）保留 5 秒默认；
• max_interval_seconds(u64)：为 slow_down 后的退避设上限（最小 1 秒）；
• wait_before_first_poll(bool)：xAI 端点首答即 authorization_pending，适合先睡一轮再轮询；Codewhale 账号服务 pending 时返回 HTTP 202、首答已有意义，则立即轮询（L93-L103）；
• slow_down_timeout_message(impl Into<String>)：设置时钟漂移专用超时文案。

此外还有一个硬约束 MINIMUM_INTERVAL = 1s：无论服务器要求多快，轮询频率不超过每秒一次（L31-L32）。

校验 URI：validate_browser_verification_uri 的安全边界

同一文件还移植了 pi 的 validateVerificationUri（L192-L206）。设备码流程的 verification_uri 直接来自网络响应，随后会被交给平台的“打开浏览器”调用；若不校验，恶意或受损的响应可能触发 file: 协议、自定义应用 scheme，甚至以攻击者选择的参数启动辅助程序。移植规则为：

• 仅允许 https:；Codewhale 在 pi（仅 https:）基础上额外放行 loopback 主机的 http:，以兼容自托管 issuer 与设备码测试；
• 任何内嵌凭据（user:pass@host）一律拒绝；
• 实现刻意不带 URL 依赖——codewhale-config 有意不引入 reqwest/url，所以用了一个最小的 scheme/host/凭据拆分函数处理 IPv6 字面量（[::1]:8080）等边界（L208-L249）。

测试与真实调用点

该文件自带 12 个单元测试（L251-L460），用“记录 sleep 时长的假时钟”精确断言行为，例如：

• slow_down_prefers_a_server_supplied_interval：服务器回 slow_down { interval: 30 } 时下一轮直接睡 30 秒（时钟漂移修复的回归用例）；
• never_sleeps_past_the_deadline：30ms 寿命 + 600s interval 的场景下，每次 sleep 都不超过剩余 deadline；
• verification_uri_must_be_https_or_loopback_http：file:///etc/passwd、javascript:alert(1)、vscode://attacker/run、data:text/html,<script> 等对抗性 URI 全部拒绝；
• timing_out_after_slow_down_reports_the_clock_drift_message：见过 slow_down 后超时报时钟漂移文案，否则报普通文案。

仓库中真实的两个调用点印证了文件头注释“被所有 Codewhale 设备码流程共享”的说法：xAI/Grok 设备登录在 crates/tui/src/xai_oauth.rs（先后调用 validate_browser_verification_uri 与 DeviceCodePoll::new），Codewhale 账号/云侧登录在 crates/cli/src/cloud.rs。

Cargo 依赖侧：deny.toml 的许可与来源基线

文档把 Cargo 依赖交给 deny.toml，该文件是标准的 cargo-deny 配置，几个关键区块值得展开：

许可白名单（L83-L105）：confidence-threshold = 0.93，allow 列表包含 MIT、MIT-0、Apache-2.0（及 LLVM-exception 变体）、ISC、Unicode-3.0、Unicode-DFS-2016、Zlib、BSD-2-Clause、BSD-3-Clause、0BSD、MPL-2.0、CC0-1.0、BSL-1.0、CDLA-Permissive-2.0；exceptions 为空，即没有任何 crate 级豁免。这意味着任何引入 AGPL、GPL、SSPL 等非清单许可的传递依赖都会在 cargo deny check 中被拒绝。

来源管控（L74-L81）：unknown-registry = "deny"、unknown-git = "deny"，仅放行 crates.io 官方索引，allow-git 为空——禁止一切未知 git 源，防止“影子依赖”。

安全公告（L8-L20）：unmaintained = "all"、unsound = "all" 全面禁止无人维护与不健全（unsound）crate；ignore 列表逐条注明 RUSTSEC 编号与被忽略原因（如 paste、ttf-parser 无安全升级路径，bincode/yaml-rust 是经 syntect 5.3.0 引入且无新版可升），是“原则禁止 + 逐条留痕豁免”的范例。

重复版本棘轮（L22-L72）：multiple-versions = "warn" 配大段 skip 白名单（reqwest 0.12/0.13、sha2 0.10/0.11、thiserror 1/2、toml 0.8/1.1 等），注释解释了每一组重复被哪个上游 crate 卡住；新出现的重复版本会以警告形式浮出，但不会立即阻塞 CI。仓库的构建性能文档 docs/BUILD_PERFORMANCE.md 也记录了 cargo deny check 在全量 feature 下清点 690 个包的审计用法，可见该配置确实进入了维护流程而非摆设。

留痕模式的补全：文件头注释与内嵌 LICENSE

从仓库结构看，Codewhale 的第三方治理遵循一套“双留痕”模式：

1. 文件头注释指向来源：device_code.rs 的模块文档即注释了上游文件、函数名、许可与版权人，读者不翻文档也能定位出处；
2. 顶层文档集中登记：许可全文在 THIRD_PARTY_NOTICES.md 中复现一次，保证“单点可发现”。

仓库中还存在更完整的姊妹文档 docs/THIRD_PARTY_NOTICES.md，把更早的源码级改编一并列表，可视为登记体系的扩充：crates/tui/src/tui/frame_rate_limiter.rs 改编自 openai/codex 的同名文件、crates/tui/src/tui/display_refresh.rs 来自 Grok CLI 的显示刷新探测、crates/tui/src/config/credential_resolve.rs 与 crates/tui/src/credentials/ 借鉴了 pi-mono packages/ai/src/auth/ 的凭据解析设计（每 provider 一个类型化凭据、modify 唯一序列化写路径、单一优先级规则、可注入 auth context），以及 vendor 补丁目录 patches/unicode-width-0.2.2/——该补丁在上游 LICENSE-MIT 保留在树内的前提下整体保留，无需在文档中重复全文。

对维护者的操作启示

基于上述结构（以下为从仓库现状归纳的做法，非文档明文规程）：

• 新增源码移植时：在目标文件头部注释中写明上游项目、上游文件/函数、许可与版权人；在 THIRD_PARTY_NOTICES.md 追加一节并复现许可全文（若许可要求全文随附）；
• 新增 Cargo 依赖时：许可合规性由 deny.toml 的 allow 白名单与 unknown-git = "deny" 把关，出现新的重复版本会触发 multiple-versions 警告，需要按注释格式说明豁免理由；
• vendoring 第三方源码补丁时：参照 patches/unicode-width-0.2.2/ 的做法，把上游许可文件原样保留在补丁目录内。

小结

Codewhale 的第三方许可治理由三个层次构成：cargo deny 自动约束全部 crate 依赖的许可、来源与安全公告；THIRD_PARTY_NOTICES.md 集中登记少量源码级移植并复现其许可文本；每个被移植文件（如 crates/config/src/device_code.rs）自带指向上游的归因注释，且配套了覆盖 RFC 8628 边界行为与对抗性输入的单元测试。这套“自动基线 + 集中登记 + 文件级留痕”的组合，为同样需要引入外部代码的 Rust 项目提供了一个可复制的合规骨架。