生成来源声明

您可以为发布的包生成来源声明。这使您能够公开确定包的构建位置和发布者，这可以提高包的供应链安全性。

关于 npm 来源

npm 来源包含两种类型的证明

来源证明
发布证明

来源证明通过公开提供指向包源代码和构建环境中构建说明的链接来建立。这使开发人员能够在下载包之前验证包的构建位置和方式。

发布证明在授权用户发布包时由注册表生成。当 npm 包使用来源发布时，它将由 Sigstore 公共利益服务器签名，并记录在公共透明度账本中，用户可以在其中查看此信息。

关于 Sigstore

Sigstore 是一个旨在简化使用短时效、短暂证书签名软件的工具和服务集合。它的三个主要组成部分是 CLI 工具、证书颁发机构和时间戳透明度日志。

证书颁发机构与任何包含可验证构建信息的 OIDC 提供者联合。它充当构建系统和包注册表之间的中介，通过验证 OIDC 令牌的完整性、颁发包含该构建信息的签名证书，然后将签名证书记录到不可变账本中。

透明度日志服务提供一个公开的、可验证的、防篡改的签名证明账本。这确保了公共服务的透明度，并提供了一种方法来检测在包注册表被入侵时篡改包的企图。

来源限制

要使用来源发布包，您必须使用支持的云 CI/CD 提供者和云托管的运行器来构建包。目前，这包括 GitHub Actions 和 GitLab CI/CD。
当 npm 注册表中的包已建立来源时，它不保证该包不包含恶意代码。相反，npm 来源提供指向包源代码和构建说明的可验证链接，开发人员可以审计这些链接并确定是否信任它。有关更多信息，请参阅“搜索和选择要下载的包”。

先决条件

在您可以使用来源发布包之前，您必须

查看Linux 基金会不可变记录通知，该通知适用于公共透明度日志。
安装最新版本的 npm CLI（确保您使用的是 9.5.0+，因为旧版本不支持 npm 来源）。有关更多信息，请参阅“尝试最新稳定版本的 npm”。
确保您的 package.json 配置了与您使用来源发布包的位置匹配的公共 repository。
使用支持的 CI/CD 提供者设置自动化以将您的包发布到 npm 注册表。以下提供者受支持
- GitHub Actions。有关更多信息，请参阅“通过 GitHub Actions 发布具有来源的包”。
- GitLab CI/CD。有关更多信息，请参阅“通过 GitLab CI/CD 发布具有来源的包”。

通过 GitHub Actions 发布具有来源的包

为了建立来源，您必须使用支持的云 CI/CD 提供者和云托管的运行器来发布包。GitHub Actions 是一个受支持的 CI/CD 平台，允许您自动执行软件开发任务。有关更多信息，请参阅 GitHub 文档中的GitHub Actions。

要更新您的 GitHub Actions 工作流程以使用来源发布您的包，您必须

授予创建 ID 令牌的权限
```
permissions:
  id-token: write
```
在GitHub 托管的运行器上运行
```
runs-on: ubuntu-latest
```
将 --provenance 标志添加到您的发布命令
```
npm publish --provenance
```
如果您是第一次发布包，您还需要明确设置对公共的访问权限
```
npm publish --provenance --access public
```

GitHub Actions 工作流程示例

此工作流程示例将使用来源将包发布到 npm 注册表。

name: Publish Package to npmjs
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm install -g npm
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

GitLab CI 作业示例

此作业示例在推送 Git 标签时使用来源将包发布到 npm 注册表。不要忘记在您的 GitLab 项目设置中定义 NPM_TOKEN 变量。

publish:
  image: 'node:20'
  rules:
    - if: $CI_COMMIT_TAG
  id_tokens:
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  script:
    - npm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
    - npm publish --provenance --access public

使用第三方包发布工具

如果您使用不直接调用 npm publish 命令的工具发布包，您可以在您的 GitHub Actions 工作流程中执行以下操作之一以使用来源发布包。

配置环境变量：在您的 GitHub Actions 工作流程中，您可以使用名为 NPM_CONFIG_PROVENANCE 的环境变量，并将其设置为 true。
配置您的 package.json 文件：您可以将 publishConfig 块添加到您的 package.json 文件
```
"publishConfig": {
  "provenance": true
},
```
添加 .npmrc 文件：您可以将 .npmrc 文件添加到您的项目，其中包含以下条目
```
provenance=true
```

注意：目前，yarn 不支持使用来源发布包的工具。

通过 GitLab CI/CD 发布具有来源的包

为了建立来源，您必须使用受支持的云 CI/CD 提供商和云托管的运行器来发布您的软件包。GitLab CI/CD 是一个受支持的 CI/CD 平台，它允许您自动化软件开发任务。有关更多信息，请参阅 GitLab 文档中的在 GitLab CI/CD 中生成来源。

验证来源证明

您可以使用以下 audit 命令验证已下载软件包的来源证明。

npm audit signatures

示例响应显示项目中所有软件包的已验证注册表签名和已验证证明的数量。

audited 1267 packages in 6s

1267 packages have verified registry signatures

74 packages have verified attestations

由于来源证明是一个非常新的功能，因此安全功能可能会随着时间的推移添加到证明格式中（或更改）。为了确保您始终能够验证证明签名，请检查您是否正在运行最新版本的 npm CLI。请注意，这通常意味着将 npm 更新到 Node.js 附带的版本之外。

在 GitHub 上编辑此页面

10 贡献者

最后编辑者：nhedger 2024年4月1日

网站导航

目录