目录

生成出处声明

目录

你可以为你发布的包生成出处声明。这使你可以公开确定包的构建位置以及包的发布者，这可以提高包的供应链安全性。

¥You can generate provenance statements for the packages you publish. This allows you to publicly establish where a package was built and who published a package, which can increase supply-chain security for your packages.

关于 npm 出处

¥About npm provenance

npm 出处包括两种类型的证明：

¥npm provenance includes two types of attestations:

  • 出处证明

    ¥Provenance attestation

  • 发布认证

    ¥Publish attestation

出处证明是通过公开提供包源代码的链接和来自构建环境的构建说明来建立的。这允许开发者在下载包之前验证包的构建位置和方式。

¥The provenance attestation is established by publicly providing a link to a package's source code and build instructions from the build environment. This allows developers to verify where and how your package was built before they download it.

当授权用户发布包时，发布证明由注册表生成。当一个 npm 包发布时带有出处，它由 Sigstore 公共产品服务器签名并记录在一个公共透明分类帐中，用户可以在其中查看此信息。

¥Publish attestations are generated by the registry when a package is published by an authorized user. When an npm package is published with provenance, it is signed by Sigstore public good servers and logged in a public transparency ledger, where users can view this information.

关于 Sigstore

¥About Sigstore

Sigstore 是一个工具和服务的集合，旨在使使用短期的、临时的证书来签署软件变得容易。它的三个主要组件是 CLI 工具、证书颁发机构和时间戳透明度日志。

¥Sigstore is a collection of tools and services aimed at making it easy to use short-lived, ephemeral certificates to sign software. Its three main components are a CLI tool, a certificate authority, and a time-stamping transparency log.

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

¥The certificate authority federates with any OIDC provider that includes verifiable build information. It acts as an intermediary between build systems and package registries by verifying the integrity of the OIDC token, issues a signing certificate that contains that build information, and then logging the signing certificate to an immutable ledger.

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

¥The transparency log service provides a public, verifiable, tamper-evident ledger of signed attestations. This ensures transparency of the public service, as well as providing a way to detect attempts to tamper with a package if a package registry were to be compromised.

出处限制

¥Provenance limitations

  • 要发布具有出处的包，你必须使用云托管运行器通过受支持的云 CI/CD 提供商构建包。如今，这包括 GitHub Actions 和 GitLab CI/CD。

    ¥To publish a package with provenance, you must build your package with a supported cloud CI/CD provider using a cloud-hosted runner. Today this includes GitHub Actions and GitLab CI/CD.

  • 当 npm 注册表中的包已确定出处时，它并不能保证该包没有恶意代码。相反，npm provenance 提供了一个指向包源代码和构建说明的可验证链接，开发者随后可以审核并确定是否信任它。欲了解更多信息，请参阅“搜索并选择要下载的包”。

    ¥When a package in the npm registry has established provenance, it does not guarantee the package has no malicious code. Instead, npm provenance provides a verifiable link to the package's source code and build instructions, which developers can then audit and determine whether to trust it or not. For more information, see "Searching for and choosing packages to download."

先决条件

¥Prerequisites

在你可以发布带有出处的包之前，你必须：

¥Before you can publish your packages with provenance, you must:

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

¥Publishing packages with provenance via GitHub Actions

为了确定出处，你必须使用受支持的云 CI/CD 提供商和云托管的运行器来发布你的包。GitHub Actions 是一个受支持的 CI/CD 平台，可让你自动执行软件开发任务。有关详细信息，请参阅 GitHub 文档中的 GitHub Actions。

¥In order to establish provenance, you must use a supported cloud CI/CD provider and a cloud-hosted runner to publish your packages. GitHub Actions is a supported CI/CD platform that allows you to automate software development tasks. For more information, see GitHub Actions in the GitHub documentation.

要更新 GitHub Actions 工作流程以发布带有来源的包，你必须：

¥To update your GitHub Actions workflow to publish your packages with provenance, you must:

  • 授予铸造 ID 令牌的权限：

    ¥Give permission to mint an ID-token:

    permissions:
      id-token: write

  • 在 GitHub 托管的运行器 上运行：

    ¥Run on a GitHub-hosted runner:

    runs-on: ubuntu-latest

  • 将 --provenance 标志添加到你的发布命令：

    ¥Add the --provenance flag to your publish command:

    npm publish --provenance

  • 如果你是第一次发布包，你还需要显式设置对公共的访问：

    ¥If you are publishing a package for the first time you will also need to explicitly set access to public:

    npm publish --provenance --access public

GitHub Actions 工作流程示例

¥Example GitHub Actions workflow

此示例工作流将包发布到 npm 注册表，并附上出处。

¥This example workflow publishes a package to the npm registry with provenance.

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

使用第三方包发布工具

¥Using third-party package publishing tools

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

¥If you publish your packages with tools that do not directly invoke the npm publish command, you can do one of the following in your GitHub Actions workflow to publish your packages with provenance.

  • 配置环境变量：在 GitHub Actions 工作流程中，你可以使用名为 NPM_CONFIG_PROVENANCE 的环境变量，并将其设置为 true。

    ¥Configure environment variables: In your GitHub Actions workflow, you can use an environment variable called NPM_CONFIG_PROVENANCE, and set it to true.

  • 配置你的 package.json 文件：你可以将 publishConfig 块添加到你的 package.json 文件中：

    ¥Configure your package.json file: You can add a publishConfig block to your package.json file:

    "publishConfig": {
      "provenance": true
    },

  • 添加 .npmrc 文件：你可以使用以下条目将 .npmrc 文件添加到你的项目中：

    ¥Add an .npmrc file: You can add an .npmrc file to your project with the following entry:

    provenance=true

注意：目前，yarn 不是用于发布带有来源的包的受支持工具。

¥Note: At this time, yarn is not a supported tool for publishing your packages with provenance.

通过 GitLab CI/CD 发布具有出处的包

¥Publishing packages with provenance via GitLab CI/CD

为了确定出处，你必须使用受支持的云 CI/CD 提供商和云托管的运行器来发布你的包。GitLab CI/CD 是一个受支持的 CI/CD 平台，可让你自动执行软件开发任务。有关更多信息，请参阅 GitLab 文档中的 在 GitLab CI/CD 中生成来源。

¥In order to establish provenance, you must use a supported cloud CI/CD provider and a cloud-hosted runner to publish your packages. GitLab CI/CD is a supported CI/CD platform that allows you to automate software development tasks. For more information, see Generating provenance in GitLab CI/CD in the GitLab documentation.

GitLab CI 作业示例

¥Example GitLab CI job

当推送 git 标签时，此示例作业将包发布到 npm 注册表并提供来源。不要忘记在 GitLab 项目设置中定义 NPM_TOKEN 变量。

¥This example job publishes a package to the npm registry with provenance when a git tag is pushed. Don't forget to define the NPM_TOKEN variable in your GitLab project settings.

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

验证出处证明

¥Verifying provenance attestations

你可以使用以下 audit 命令验证下载的包的出处证明：

¥You can verify the provenance attestations of downloaded packages with the following audit command:

npm audit signatures

显示项目中所有包的已验证注册表签名和已验证证明的计数的示例响应：

¥Example response showing the count of verified registry signatures and verified attestations for all of the packages in a project:

audited 1267 packages in 6s


1267 packages have verified registry signatures


74 packages have verified attestations

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

¥Because provenance attestations are such a new feature, security features may be added to (or changed in) the attestation format over time. To ensure that you're always able to verify attestation signatures check that you're running the latest version of the npm CLI. Please note this often means updating npm beyond the version that ships with Node.js.

npm 中文网 - 粤ICP备13048890号