@cryptotaxi247 / documentation
Code Commits Issues Pulls Sessions CI/CD
kartykp/gat-bypass-2fa-docs
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
mdx 177 lines 8.28 KB
Raw
1 ---
2 title: Generating provenance statements
3 ---
4
5 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.
6
7 ## About npm provenance
8
9 npm provenance includes two types of attestations:
10
11 - Provenance attestation
12 - Publish attestation
13
14 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.
15
16 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.
17
18 ### About Sigstore
19
20 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.
21
22 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.
23
24 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.
25
26 ## Provenance limitations
27
28 - 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.
29 - 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][provenance-info]."
30
31 ## Prerequisites
32
33 Before you can publish your packages with provenance, you must:
34
35 - Review the [Linux Foundation Immutable Record notice](https://lfprojects.org/policies/hosted-project-tools-immutable-records/), which applies to the public transparency log.
36
37 - Install the latest version of the npm CLI (ensure you are on `9.5.0+` as older versions don't support npm provenance). For more information, see "[Try the latest stable version of npm][update-npm]."
38
39 - Ensure your `package.json` is configured with a public `repository` that matches (case-sensitive) where you are publishing with provenance from.
40
41 - Set up automation with a supported CI/CD provider to publish your packages to the npm registry. The following providers are supported:
42 - GitHub Actions. For more information, see "[Publishing packages with provenance via GitHub Actions][github-provenance]."
43 - GitLab CI/CD. For more information, see "[Publishing packages with provenance via GitLab CI/CD][gitlab-provenance]."
44
45 **Note:** If you use [trusted publishing](/trusted-publishers), provenance attestations are automatically generated for your packages without requiring the `--provenance` flag. This provides enhanced security and eliminates the need for access tokens in your CI/CD workflows.
46
47 ## Publishing packages with provenance via GitHub Actions
48
49 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][github-actions] in the GitHub documentation.
50
51 To update your GitHub Actions workflow to publish your packages with provenance, you must:
52
53 - Give permission to mint an ID-token:
54
55 ```yaml
56 permissions:
57 id-token: write
58 ```
59
60 - Run on a [GitHub-hosted runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources):
61
62 ```yaml
63 runs-on: ubuntu-latest
64 ```
65
66 - Add the `--provenance` flag to your publish command:
67
68 ```sh
69 npm publish --provenance
70 ```
71
72 - If you are publishing a package for the first time you will also need to explicitly set access to public:
73
74 ```sh
75 npm publish --provenance --access public
76 ```
77
78 ### Example GitHub Actions workflow
79
80 This example workflow publishes a package to the npm registry with provenance.
81
82 ```yaml
83 name: Publish Package to npmjs
84 on:
85 release:
86 types: [published]
87 jobs:
88 build:
89 runs-on: ubuntu-latest
90 permissions:
91 contents: read
92 id-token: write
93 steps:
94 - uses: actions/checkout@v4
95 - uses: actions/setup-node@v4
96 with:
97 node-version: '20.x'
98 registry-url: 'https://registry.npmjs.org'
99 - run: npm ci
100 - run: npm publish --provenance --access public
101 env:
102 NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
103 ```
104
105 ### Using third-party package publishing tools
106
107 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.
108
109 - **Configure environment variables:** In your GitHub Actions workflow, you can use an environment variable called `NPM_CONFIG_PROVENANCE`, and set it to `true`.
110 - **Configure your `package.json` file:** You can add a `publishConfig` block to your `package.json` file:
111
112 ```json
113 "publishConfig": {
114 "provenance": true
115 },
116 ```
117
118 - **Add an `.npmrc` file:** You can add an `.npmrc` file to your project with the following entry:
119
120 ```ini
121 provenance=true
122 ```
123
124 <Note>
125
126 **Note:** To publish packages with provenance using Yarn, [v4.9.0](https://github.com/yarnpkg/berry/releases/tag/%40yarnpkg%2Fcli%2F4.9.0) or greater is required.
127
128 </Note>
129
130 ## Publishing packages with provenance via GitLab CI/CD
131
132 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][gitlab-ci-cd-docs] in the GitLab documentation.
133
134 ### Example GitLab CI job
135
136 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.
137
138 ```yaml
139 publish:
140 image: 'node:20'
141 rules:
142 - if: $CI_COMMIT_TAG
143 id_tokens:
144 SIGSTORE_ID_TOKEN:
145 aud: sigstore
146 script:
147 - npm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
148 - npm publish --provenance --access public
149 ```
150
151 ## Verifying provenance attestations
152
153 You can verify the provenance attestations of downloaded packages with the following `audit` command:
154
155 ```
156 npm audit signatures
157 ```
158
159 Example response showing the count of verified registry signatures and verified attestations for all of the packages in a project:
160
161 ```
162 audited 1267 packages in 6s
163
164 1267 packages have verified registry signatures
165
166 74 packages have verified attestations
167 ```
168
169 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.
170
171 [provenance-info]: /searching-for-and-choosing-packages-to-download#package-provenance
172 [update-npm]: /try-the-latest-stable-version-of-npm
173 [github-provenance]: #publishing-packages-with-provenance-via-github-actions
174 [gitlab-provenance]: #publishing-packages-with-provenance-via-gitlab-cicd
175 [github-actions]: https://docs.github.com/en/actions
176 [understand-actions]: https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions
177 [gitlab-ci-cd-docs]: https://docs.gitlab.com/ee/ci/yaml/signing_examples.html#use-sigstore-and-npm-to-generate-keyless-provenance