16 供应链硬化 把依赖变更当代码评审：一条从 .npmrc 到 OIDC 的完整链

先记住这一句

这一章值得读的地方不是清单本身，而是清单的完整性。多数项目做前两条就停了；pi 把链条一直拉到「发布时不用本地 npm token」。有意思的是，一个明确拒绝做运行时权限系统的项目（第 15 章），在供应链上却是全书最谨慎的。

这两件事并不矛盾，反而互相解释：pi 认为真正的边界要建在能真正守住的地方。进程内沙箱守不住，所以不做；依赖引入的那一刻能守住，所以守得很紧。

整条链

两个值得单独看的细节

① min-release-age=2。npm 解析依赖时跳过发布不足 2 天的版本。.npmrc:2 这一行专门针对被攻破的维护者账号发布恶意版本这一类事件——这类投毒的典型生命周期是「发布 → 数小时内被发现 → 撤包」，两天的延迟就把绝大部分窗口错开了。代价是拿不到当天的安全补丁，所以发版时要显式 npm_config_min_release_age=0 临时关闭。

② 生命周期脚本白名单只有两条，而且每条写了理由。

const allowedInstallScriptPackages = new Map([
    ["@google/genai@1.52.0", "preinstall is a no-op in the published package"],
    ["protobufjs@7.6.5", "postinstall only warns about protobufjs version scheme mismatches"],
]);

新增带生命周期脚本的依赖会让检查失败，直到有人显式加进这个白名单——AGENTS.md 里配了一条给 agent 的硬规矩：never add one silently。AGENTS.md:45

精确版本是程序化校验的，不是靠自觉

const exactVersionPattern = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;

特定依赖的特殊规矩

AGENTS.md 里点名了一个包：更新 undici 时必须读目标版本的 changelog / release notes，评估是否影响功能后才能应用。AGENTS.md:42

为什么是 undici：它是所有 provider 请求的 HTTP 层，它的行为变化（连接池、超时、流式语义）会以极难诊断的方式影响 agent。把「这一个依赖需要人读 changelog」写进给 agent 的规则文件，比泛泛地说「谨慎升级依赖」有用得多。

为什么这条链值得整条抄

供应链攻击的经济学很特别：攻击者的成本几乎恒定（攻破一个流行包的维护者账号），而收益随下游用户数线性增长。对一个装在开发者机器上、持有 provider API key、能执行任意命令的 CLI 来说，它的下游用户是「有 API key 且有 shell 权限的开发者」——这是攻击者能想到的最好的一批受害者。

所以 pi 在这里的谨慎程度与它在运行时权限上的放任，并不是自相矛盾，而是同一个判断的两面：把有限的防御预算花在真能守住的关口上。依赖引入是一个离散的、可评审的、频率很低的事件；运行时的每一次工具调用不是。

OIDC trusted publishing 消掉的是什么

传统发布流程里，某台机器上存着一个能发布 npm 包的长期 token。那个 token 是整条链上最值钱的东西——拿到它就能发布带后门的新版本，绕过前面所有的锁版本和白名单。

OIDC trusted publishing 把它换成 GitHub Actions 在特定环境下签发的短期身份凭证：没有长期 token，没有 OTP，没有本地 npm publish。AGENTS.md:159 攻击面从「一个可能泄漏的密钥」变成「一个需要攻破的 CI 配置」。

发布流程还有一道后置校验：发布后有专门的 job 逐个确认每个公开工作区包都能按精确发布版本解析、且其 npm tarball 可获取，然后才写「已验证发布」标记；pi.dev/api/latest-version 读的是那个标记。「绝不能在这个 job 成功之前从 npm 宣告新版本」——这句写在 AGENTS.md 里。AGENTS.md:159

代价

精确锁版本 + 2 天延迟 + shrinkwrap（锚点版本），合起来意味着安全补丁的到达速度变慢，而且每次依赖升级都是一次需要人参与的显式操作。对一个由 3 位主要维护者 + 大量偶发贡献者组成的项目，这是可观的持续成本。

他们的对冲是把这些检查全部程序化并塞进 npm run check——成本从「记得要做」变成「不做就红」。这是本章最实用的一条：纪律不可持续，门禁可持续。

• min-release-age=2 挡不住有耐心的攻击者。它针对的是「发布后数小时内被发现」的投毒模式。一个潜伏两周才激活的后门版本，这条规则完全无效。
• 白名单是按 包@版本 锁的，升级即失效——这是特性，但也是摩擦。两条白名单里那两个包每次升版都要重新走一次审。项目一大，这个列表会变成「谁也不敢动」的地方。
• 整条链保护的是「依赖引入」，不保护「依赖已经在跑」。一个通过审查的依赖在运行时做什么，仍然回到 第 15 章 的结论：没有沙箱。
• pre-commit 的 lockfile 拦截可被环境变量绕过。PI_ALLOW_LOCKFILE_CHANGE=1 存在的理由是正当的（发版要改 lockfile），但它同时意味着这道门禁是防手滑，不防有意。

检查过并确认（锚点版本）：npm run check 确实串联了 check:pinned-deps、check:ts-imports、check:shrinkwrap、check:install-lock:coding-agent、check:browser-smoke 五道自定义门禁外加 biome 与 tsgo，且 --error-on-warnings 让警告也算失败。package.json:18

• 设一个「最短发布年龄」再解析依赖。一行 .npmrc 配置，成本几乎为零，挡掉的是最常见的一类投毒窗口。 适用条件：npm 生态。发版当天要临时关闭——否则你自己的新版本也会被自己的规则挡住。
• 生命周期脚本白名单用 包@精确版本 → 理由 的 Map，而不是数组。数据结构强制写理由，升级自动作废旧审查结论。 适用条件：任何允许安装脚本的包管理器。这是全章最容易直接抄的一条。
• 把「某个特定依赖需要人读 changelog」写进规则文件，点名到包。泛泛的「谨慎升级」没人执行；「更新 undici 必须读 release notes」会被执行。 适用条件：你有 1–3 个行为变化会造成难诊断故障的关键依赖。
• 发布用 CI 的短期身份凭证，别用长期 token；并在宣告新版本前先验证包真的可解析、可下载。前者消灭最值钱的攻击目标，后者防的是「宣告了但用户装不上」。 适用条件：有 CI 且 registry 支持 OIDC。手工发版时这两条都无从谈起。