產生來源陳述

您可以為您發布的套件產生來源陳述。這讓您可以公開建立套件的位置，以及發布套件的人員，這可以增加套件的供應鏈安全性。

關於 npm 來源

npm 來源包含兩種證明

來源證明
發佈證明

來源證明是透過公開提供連結至套件的原始碼和建置環境的建置說明而建立。這讓開發人員可以在下載套件之前驗證套件的建置位置和方式。

發佈證明是由註冊表在授權使用者發佈套件時產生。當 npm 套件以來源發佈時，它會由 Sigstore 公共服務伺服器簽署，並記錄在公開透明分類帳中，使用者可以在此查看這些資訊。

關於 Sigstore

Sigstore 是一組工具和服務，旨在讓使用短暫的臨時憑證簽署軟體變得容易。它的三個主要元件是 CLI 工具、憑證授權和時間戳記透明記錄。

憑證授權與任何包含可驗證建置資訊的 OIDC 提供者聯合。它透過驗證 OIDC 令牌的完整性，扮演建置系統和套件註冊表之間的仲介角色，發出包含該建置資訊的簽署憑證，然後將簽署憑證記錄至不可變分類帳。

透明記錄服務提供一個公開、可驗證、防篡改的已簽署證明分類帳。這確保了公共服務的透明性，並提供一種方法來偵測套件註冊表遭到入侵時篡改套件的嘗試。

來源限制

若要發佈具有來源的套件，你必須使用雲端託管執行器，以受支援的雲端 CI/CD 提供者建置套件。目前包括 GitHub Actions 和 GitLab CI/CD。
當 npm 註冊表中的套件建立來源時，並不能保證套件沒有惡意程式碼。相反地，npm 來源提供一個可驗證的連結至套件的原始碼和建置說明，開發人員可以審查並決定是否信任它。如需更多資訊，請參閱「搜尋和選擇要下載的套件」。

先決條件

在你使用來源發佈套件之前，你必須

檢閱Linux Foundation 不可變記錄公告，它適用於公開透明記錄。
安裝最新版本的 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 簽章

範例回應顯示專案中所有套件的已驗證登錄檔簽章和已驗證證明數量

audited 1267 packages in 6s

1267 packages have verified registry signatures

74 packages have verified attestations

由於來源證明是一項新功能，因此安全性功能可能會隨著時間新增至（或變更）證明格式中。為確保您始終能夠驗證證明簽章，請確認您執行的是最新版本的 npm CLI。請注意，這通常表示 npm 更新必須超越隨附 Node.js 的版本。

在 GitHub 上編輯此頁面

10 contributors

上次由 nhedger 於 2024 年 4 月 1 日編輯

網站導覽

目錄