pnpm sbom 仓库 URL 规范化修复让 CycloneDX externalReferences 与 SPDX homepage 输出合法可用的地址【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm导读本文围绕 pnpm 的 SBOM软件物料清单生成能力深入讲解一项针对仓库地址输出的补丁修复pnpm sbom现在会在 CycloneDX 的externalReferences[].url与 SPDX 的homepage字段中发布合法、可被下游消费的 URL而不是像过去那样直接透传 package.json 中的原始值。读完本文你将掌握 pnpm 是如何把 npm shorthand如vercel/ms、scp 风格 git 远程如gitgithub.com:vercel/ms.git展开为完整地址、如何去除 URL 中内嵌的凭据、以及如何在生成 SBOM 时对齐 npm 的仓库地址语义。背景SBOM 中的仓库地址为什么会被拒收SBOMSoftware Bill of Materials是一份描述软件组成成分组件、依赖、许可证、来源地址的结构化清单。pnpm 通过pnpm sbom命令为项目生成两种主流格式CycloneDX每个组件通过externalReferences[]描述外部引用其中vcs类型的引用指向源码仓库SPDX每个包通过homepage字段声明主页/仓库地址。问题在于package.json 的repository字段允许多种写法——完整的 HTTPS URL、npm shorthand如vercel/ms、gitlab:group/subgroup/project、scp 风格 git 远程如gitgithub.com:vercel/ms.git等。CycloneDX 规范要求 URL 必须是合法的iri-reference而 npm shorthand 或 scp 远程并非合法 URL。pnpm 早期版本直接把 manifest 中的原始值写入 SBOM导致生成的文档被 Dependency-Track 等严格校验的消费方拒收对应上游问题 pnpm/pnpm#14773。本次补丁记录于 .changeset/fix-sbom-repository-url.md影响pnpm/deps.compliance.sbom、pnpm/deps.compliance.commands、pacquet、pnpm四个包的核心目标就是让 SBOM 输出的仓库地址与 npm 解析出的地址保持一致且不泄露任何内嵌凭据。修复规则一览五种输入五条明确出路根据 changeset 的表述并结合源码实现getPkgMetadata.ts 中的repositoryFromField与urlWithoutCredentials仓库地址的输出规则可以归纳为下表输入形态示例输出行为npm shorthandowner/repovercel/ms展开为githttps://github.com/vercel/ms.git这类 npm 推导出的githttpsURL带前缀的 shorthandgitlab:group/subgroup/project同样展开为对应的githttpsURLscp 风格远程gitgithub.com:vercel/ms.git展开为与 npm 一致的 HTTPS 地址其他普通 URLhttps://example.com/repo.git以规范化normalized形式输出去除内嵌凭据userinfo 中的用户名/密码/令牌不指向仓库的值邮箱地址、mailto:、file:、无 owner 的gist:等直接省略该字段不写入 SBOM其中最后一条尤为关键任何无法确定指向一个仓库的值都不会被写入 SBOM。例如repository字段填了一个邮箱地址那么在 CycloneDX 中就不会出现对应的vcs引用SPDX 中也不会出现对应的homepage。源码级拆解npm shorthand 如何被展开仓库 URL 规范化的核心逻辑位于 getPkgMetadata.ts 的repositoryFromField函数export function repositoryFromField (field: unknown): string | undefined { const raw urlFieldValue(field) if (!raw) return undefined const absolute absoluteUrl(raw) if (absolute) return absolute const hosted HostedGit.fromUrl(raw) // 无 owner 的 shorthand 会推导出 owner 为 null 的 URL // gist:id 同样无 owner且 pnpm v12 的解析器不支持 gist // 因此这里直接丢弃保证两个版本行为一致。 if (!hosted?.user) return undefined const expanded hosted.https() return expanded ? urlWithoutCredentials(expanded)?.href : undefined }其处理流程是先按绝对 URL 解析absoluteUrl调用urlWithoutCredentials只有带 host 的完整 URL 才被接受。mailto:、file:这类值因为 没有 host 而不构成可访问的仓库地址直接返回undefined。再走 hosted-git-info 展开对于 shorthand 和 scp 远程借助hosted-git-info库见 getPkgMetadata.ts 第 7 行import HostedGit from hosted-git-info解析出托管平台信息调用hosted.https()得到与 npm 一致的githttps地址。无 owner 直接放弃vercel/ms有 ownervercel所以可以展开而gist:id这类无 owner 的 shorthand 会被丢弃——这正是注释中强调的、与 pnpm v12 解析器行为保持一致的关键决策。值得注意repository字段本身也可能是对象形态{ type, url }urlFieldValue会统一提取其中的url字符串再处理兼容{ type: git, url: ... }的常见写法。源码级拆解凭据剥离与非法字符净化SBOM 文档会被分发给第三方审计平台、合规工具绝不能把私有仓库地址中的用户名/密码/令牌写进去。urlWithoutCredentials承担了这一职责function urlWithoutCredentials (raw: string): URL | undefined { let url: URL try { url new URL(raw) } catch { return undefined } // 解析器会保留不以 %XX 转义序列开头的 %而 iri-reference 不允许这种字符。 if (/%(?![0-9a-f]{2})/i.test(url.href)) return undefined // ssh: 与 gitssh: 协议的 host 本身形如 gitgithub.com // 此时无密码的用户名属于地址的一部分其他协议下用户名可能就是密钥本身。 const sshLogin !url.password (url.protocol ssh: || url.protocol gitssh:) if (!sshLogin) { url.username url.password } return url }这里有两层语义合法化WHATWG URL 解析器会做百分号编码等规范化处理例如把空白和控制字符转义这恰好满足了 CycloneDXiri-reference的语法要求同时%后跟非十六进制字符不是合法的%XX转义的值会被直接拒绝因为iri-reference不允许这类裸百分号。去凭据除非是ssh:/gitssh:协议下无密码的用户名此时gitgithub.com中的git是登录用户而非秘密否则一律清空username和password。这样https://user:tokenexample.com/repo.git会被输出为https://example.com/repo.git。此外bugs字段的 URLbugsUrlFromField同样只接受http:/https:协议且剥离凭据后的地址用于 CycloneDX 的issue-tracker引用。源码级拆解git 依赖的下载地址如何规范化除了 manifest 中的repository字段lockfile 中git 依赖的resolution.repo也需要规范化为合法的下载 URL。这由 collectComponents.ts 中的gitDownloadUrl完成export function gitDownloadUrl (resolution: Resolution): string | undefined { if (resolution.type ! git) return undefined const needsGitPlusPrefix resolution.repo.includes(://) !resolution.repo.startsWith(git) const prefix needsGitPlusPrefix ? git : return ${prefix}${resolution.repo}#${resolution.commit} }规则非常直接只有包含://的协议式地址才需要补git前缀且不会重复加前缀gitgithub.com:user/repo.git这类 scp 风格地址保持原样非 git 类型如 tarball 解析返回undefined。测试 gitDownloadUrl.test.ts 覆盖了五种情形https://github.com/stevemao/left-pad.git→githttps://github.com/stevemao/left-pad.git#commitssh://gitgithub.com/user/repo.git→gitssh://gitgithub.com/user/repo.git#commitgitgithub.com:user/repo.gitscp 风格→ 不加git前缀原样追加#commitgitssh://gitgithub.com/user/repo.git已有前缀→ 不重复加前缀tarball 解析 → 返回undefined修复落点字段在两种格式中如何呈现规范化后的仓库地址最终写入两个位置分别对应两种 SBOM 格式CycloneDXserializeCycloneDx.ts组件级和根组件级的externalReferences数组中仓库地址以vcs类型出现homepage作为website类型、bugs作为issue-tracker类型一并输出if (comp.repository) { externalRefs.push({ type: vcs, url: comp.repository, }) }SPDXserializeSpdx.ts仓库地址写入包的homepage字段if (rootComponent.repository) { rootPackage.homepage rootComponent.repository }由于修复后的repository值要么是合法 URL要么是undefined被省略SPDX 中不再会出现homepage被填充成非法值、或者downloadLocation退化的情况——下游工具校验时自然不会再把文档判为非法。如何验证命令行与测试生成 SBOM 的命令如下--sbom-format必选指定cyclonedx或spdx# 生成 CycloneDX 格式 pnpm sbom --sbom-format cyclonedx # 生成 SPDX 格式 pnpm sbom --sbom-format spdx # 仅基于 lockfile 数据生成跳过 store 元数据读取 pnpm sbom --sbom-format cyclonedx --lockfile-only相关的其余选项见 sbom.ts 的cliOptionsTypes还包括--sbom-type library|application根组件类型默认library、--sbom-spec-version 1.5|1.6|1.7CycloneDX 规范版本默认1.7、--sbom-authors、--sbom-supplier、--split、--exclude-peers等。仓库内的测试用例可以直接印证本次修复的行为gitDownloadUrl.test.ts验证 git 解析地址的前缀处理与 scp 风格原样输出getPkgMetadata.test.ts覆盖repositoryFromField对 shorthand、scp 远程、凭据剥离、无 owner 值的处理serializeCycloneDx.test.ts 与 serializeSpdx.test.ts验证两种格式序列化后字段的正确性命令级集成测试位于 commands/test/sbom/ 下其fixtures/中包含sbom-repository、sbom-component-repository等专门用于仓库地址场景的 fixture。兼容性与行为一致性本次修复不仅是把值改对还刻意保持了与 npm 及 pnpm 其他版本的语义对齐与 npm 对齐vercel/ms、gitlab:group/subgroup/project展开出的地址正是 npm 自身推导的githttpsURL与 pnpm v12 对齐对gist:id这类无 owner 的 shorthand 直接丢弃避免产出 owner 为null的畸形 URL跨格式一致同一份规范化后的地址既用于 CycloneDX 的vcsexternalReference也用于 SPDX 的homepage保证两份 SBOM 对仓库来源的描述一致安全默认任何协议下的 URL 都经过凭据剥离ssh 登录用户除外SBOM 不会成为凭据泄露通道。小结pnpm sbom的仓库 URL 修复看似是一处小改动实则是合规性文档必须输出合法、可消费、安全数据这一原则的典型落地通过 hosted-git-info 展开 npm shorthand 与 scp 远程、通过 WHATWG URL 规范化并剥离凭据、对不指向仓库的值整体省略pnpm 让生成的 CycloneDX 与 SPDX 文档能被 Dependency-Track 等严格校验工具顺利接受。对任何使用pnpm sbom做供应链合规审计的团队来说理解这套规范化规则就能预判生成的 SBOM 中每个仓库地址的最终形态。【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
pnpm sbom 仓库 URL 规范化修复让 CycloneDX externalReferences 与 SPDX homepage 输出合法可用的地址【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm导读本文围绕 pnpm 的 SBOM软件物料清单生成能力深入讲解一项针对仓库地址输出的补丁修复pnpm sbom现在会在 CycloneDX 的externalReferences[].url与 SPDX 的homepage字段中发布合法、可被下游消费的 URL而不是像过去那样直接透传 package.json 中的原始值。读完本文你将掌握 pnpm 是如何把 npm shorthand如vercel/ms、scp 风格 git 远程如gitgithub.com:vercel/ms.git展开为完整地址、如何去除 URL 中内嵌的凭据、以及如何在生成 SBOM 时对齐 npm 的仓库地址语义。背景SBOM 中的仓库地址为什么会被拒收SBOMSoftware Bill of Materials是一份描述软件组成成分组件、依赖、许可证、来源地址的结构化清单。pnpm 通过pnpm sbom命令为项目生成两种主流格式CycloneDX每个组件通过externalReferences[]描述外部引用其中vcs类型的引用指向源码仓库SPDX每个包通过homepage字段声明主页/仓库地址。问题在于package.json 的repository字段允许多种写法——完整的 HTTPS URL、npm shorthand如vercel/ms、gitlab:group/subgroup/project、scp 风格 git 远程如gitgithub.com:vercel/ms.git等。CycloneDX 规范要求 URL 必须是合法的iri-reference而 npm shorthand 或 scp 远程并非合法 URL。pnpm 早期版本直接把 manifest 中的原始值写入 SBOM导致生成的文档被 Dependency-Track 等严格校验的消费方拒收对应上游问题 pnpm/pnpm#14773。本次补丁记录于 .changeset/fix-sbom-repository-url.md影响pnpm/deps.compliance.sbom、pnpm/deps.compliance.commands、pacquet、pnpm四个包的核心目标就是让 SBOM 输出的仓库地址与 npm 解析出的地址保持一致且不泄露任何内嵌凭据。修复规则一览五种输入五条明确出路根据 changeset 的表述并结合源码实现getPkgMetadata.ts 中的repositoryFromField与urlWithoutCredentials仓库地址的输出规则可以归纳为下表输入形态示例输出行为npm shorthandowner/repovercel/ms展开为githttps://github.com/vercel/ms.git这类 npm 推导出的githttpsURL带前缀的 shorthandgitlab:group/subgroup/project同样展开为对应的githttpsURLscp 风格远程gitgithub.com:vercel/ms.git展开为与 npm 一致的 HTTPS 地址其他普通 URLhttps://example.com/repo.git以规范化normalized形式输出去除内嵌凭据userinfo 中的用户名/密码/令牌不指向仓库的值邮箱地址、mailto:、file:、无 owner 的gist:等直接省略该字段不写入 SBOM其中最后一条尤为关键任何无法确定指向一个仓库的值都不会被写入 SBOM。例如repository字段填了一个邮箱地址那么在 CycloneDX 中就不会出现对应的vcs引用SPDX 中也不会出现对应的homepage。源码级拆解npm shorthand 如何被展开仓库 URL 规范化的核心逻辑位于 getPkgMetadata.ts 的repositoryFromField函数export function repositoryFromField (field: unknown): string | undefined { const raw urlFieldValue(field) if (!raw) return undefined const absolute absoluteUrl(raw) if (absolute) return absolute const hosted HostedGit.fromUrl(raw) // 无 owner 的 shorthand 会推导出 owner 为 null 的 URL // gist:id 同样无 owner且 pnpm v12 的解析器不支持 gist // 因此这里直接丢弃保证两个版本行为一致。 if (!hosted?.user) return undefined const expanded hosted.https() return expanded ? urlWithoutCredentials(expanded)?.href : undefined }其处理流程是先按绝对 URL 解析absoluteUrl调用urlWithoutCredentials只有带 host 的完整 URL 才被接受。mailto:、file:这类值因为 没有 host 而不构成可访问的仓库地址直接返回undefined。再走 hosted-git-info 展开对于 shorthand 和 scp 远程借助hosted-git-info库见 getPkgMetadata.ts 第 7 行import HostedGit from hosted-git-info解析出托管平台信息调用hosted.https()得到与 npm 一致的githttps地址。无 owner 直接放弃vercel/ms有 ownervercel所以可以展开而gist:id这类无 owner 的 shorthand 会被丢弃——这正是注释中强调的、与 pnpm v12 解析器行为保持一致的关键决策。值得注意repository字段本身也可能是对象形态{ type, url }urlFieldValue会统一提取其中的url字符串再处理兼容{ type: git, url: ... }的常见写法。源码级拆解凭据剥离与非法字符净化SBOM 文档会被分发给第三方审计平台、合规工具绝不能把私有仓库地址中的用户名/密码/令牌写进去。urlWithoutCredentials承担了这一职责function urlWithoutCredentials (raw: string): URL | undefined { let url: URL try { url new URL(raw) } catch { return undefined } // 解析器会保留不以 %XX 转义序列开头的 %而 iri-reference 不允许这种字符。 if (/%(?![0-9a-f]{2})/i.test(url.href)) return undefined // ssh: 与 gitssh: 协议的 host 本身形如 gitgithub.com // 此时无密码的用户名属于地址的一部分其他协议下用户名可能就是密钥本身。 const sshLogin !url.password (url.protocol ssh: || url.protocol gitssh:) if (!sshLogin) { url.username url.password } return url }这里有两层语义合法化WHATWG URL 解析器会做百分号编码等规范化处理例如把空白和控制字符转义这恰好满足了 CycloneDXiri-reference的语法要求同时%后跟非十六进制字符不是合法的%XX转义的值会被直接拒绝因为iri-reference不允许这类裸百分号。去凭据除非是ssh:/gitssh:协议下无密码的用户名此时gitgithub.com中的git是登录用户而非秘密否则一律清空username和password。这样https://user:tokenexample.com/repo.git会被输出为https://example.com/repo.git。此外bugs字段的 URLbugsUrlFromField同样只接受http:/https:协议且剥离凭据后的地址用于 CycloneDX 的issue-tracker引用。源码级拆解git 依赖的下载地址如何规范化除了 manifest 中的repository字段lockfile 中git 依赖的resolution.repo也需要规范化为合法的下载 URL。这由 collectComponents.ts 中的gitDownloadUrl完成export function gitDownloadUrl (resolution: Resolution): string | undefined { if (resolution.type ! git) return undefined const needsGitPlusPrefix resolution.repo.includes(://) !resolution.repo.startsWith(git) const prefix needsGitPlusPrefix ? git : return ${prefix}${resolution.repo}#${resolution.commit} }规则非常直接只有包含://的协议式地址才需要补git前缀且不会重复加前缀gitgithub.com:user/repo.git这类 scp 风格地址保持原样非 git 类型如 tarball 解析返回undefined。测试 gitDownloadUrl.test.ts 覆盖了五种情形https://github.com/stevemao/left-pad.git→githttps://github.com/stevemao/left-pad.git#commitssh://gitgithub.com/user/repo.git→gitssh://gitgithub.com/user/repo.git#commitgitgithub.com:user/repo.gitscp 风格→ 不加git前缀原样追加#commitgitssh://gitgithub.com/user/repo.git已有前缀→ 不重复加前缀tarball 解析 → 返回undefined修复落点字段在两种格式中如何呈现规范化后的仓库地址最终写入两个位置分别对应两种 SBOM 格式CycloneDXserializeCycloneDx.ts组件级和根组件级的externalReferences数组中仓库地址以vcs类型出现homepage作为website类型、bugs作为issue-tracker类型一并输出if (comp.repository) { externalRefs.push({ type: vcs, url: comp.repository, }) }SPDXserializeSpdx.ts仓库地址写入包的homepage字段if (rootComponent.repository) { rootPackage.homepage rootComponent.repository }由于修复后的repository值要么是合法 URL要么是undefined被省略SPDX 中不再会出现homepage被填充成非法值、或者downloadLocation退化的情况——下游工具校验时自然不会再把文档判为非法。如何验证命令行与测试生成 SBOM 的命令如下--sbom-format必选指定cyclonedx或spdx# 生成 CycloneDX 格式 pnpm sbom --sbom-format cyclonedx # 生成 SPDX 格式 pnpm sbom --sbom-format spdx # 仅基于 lockfile 数据生成跳过 store 元数据读取 pnpm sbom --sbom-format cyclonedx --lockfile-only相关的其余选项见 sbom.ts 的cliOptionsTypes还包括--sbom-type library|application根组件类型默认library、--sbom-spec-version 1.5|1.6|1.7CycloneDX 规范版本默认1.7、--sbom-authors、--sbom-supplier、--split、--exclude-peers等。仓库内的测试用例可以直接印证本次修复的行为gitDownloadUrl.test.ts验证 git 解析地址的前缀处理与 scp 风格原样输出getPkgMetadata.test.ts覆盖repositoryFromField对 shorthand、scp 远程、凭据剥离、无 owner 值的处理serializeCycloneDx.test.ts 与 serializeSpdx.test.ts验证两种格式序列化后字段的正确性命令级集成测试位于 commands/test/sbom/ 下其fixtures/中包含sbom-repository、sbom-component-repository等专门用于仓库地址场景的 fixture。兼容性与行为一致性本次修复不仅是把值改对还刻意保持了与 npm 及 pnpm 其他版本的语义对齐与 npm 对齐vercel/ms、gitlab:group/subgroup/project展开出的地址正是 npm 自身推导的githttpsURL与 pnpm v12 对齐对gist:id这类无 owner 的 shorthand 直接丢弃避免产出 owner 为null的畸形 URL跨格式一致同一份规范化后的地址既用于 CycloneDX 的vcsexternalReference也用于 SPDX 的homepage保证两份 SBOM 对仓库来源的描述一致安全默认任何协议下的 URL 都经过凭据剥离ssh 登录用户除外SBOM 不会成为凭据泄露通道。小结pnpm sbom的仓库 URL 修复看似是一处小改动实则是合规性文档必须输出合法、可消费、安全数据这一原则的典型落地通过 hosted-git-info 展开 npm shorthand 与 scp 远程、通过 WHATWG URL 规范化并剥离凭据、对不指向仓库的值整体省略pnpm 让生成的 CycloneDX 与 SPDX 文档能被 Dependency-Track 等严格校验工具顺利接受。对任何使用pnpm sbom做供应链合规审计的团队来说理解这套规范化规则就能预判生成的 SBOM 中每个仓库地址的最终形态。【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
