From 152d4f4574daa98ea12caa5e67225c743c099dda Mon Sep 17 00:00:00 2001 From: Monish Chandra Mohan <23190045+monishcm@users.noreply.github.com> Date: Thu, 23 Jan 2025 19:22:42 +0530 Subject: [PATCH 1/9] Update searching-for-and-choosing-packages-to-download.mdx --- ...-for-and-choosing-packages-to-download.mdx | 60 +------------------ 1 file changed, 1 insertion(+), 59 deletions(-) diff --git a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx index 8606be03696..702b29964cc 100644 --- a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx +++ b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx @@ -4,7 +4,7 @@ redirect_from: - /getting-started/searching-for-packages --- -You can use the npm search bar to find packages to use in your projects. The search is performed using content from the package's title, description, readme, and keywords and is powered by [opensearch](https://opensearch.org/). Search results are displayed based on keyword matching from the package's title, description, readme, and keywords. No subjective ranking criteria are applied, except for a minimal boost to deprioritize spammy or entirely new packages, aiming to maintain a neutral stance towards all other packages. +You can use the npm search bar to locate packages for your projects. The search function leverages information from a package's title, description, readme, and keywords, powered by OpenSearch. Results are displayed based on keyword matching from these fields, without subjective ranking criteria. However, adjustments are applied to deprioritise spammy or recently published packages to ensure search neutrality. Please note that newly published packages may take up to one-two week to appear in the search results. Additionally, deprecated packages are excluded from the search results to enhance the user experience. ## Searching for a package @@ -19,61 +19,3 @@ You can use the npm search bar to find packages to use in your projects. The sea 3. In the package search results list, click the name of the package. - -## Package provenance - -When packages have been published with provenance, you can: - -- Verify where and how a package was published. -- Validate that an authorized user published a package. - -You can use this information to audit packages and determine whether or not you want to consume them. For more information about npm provenance, see "[About npm provenance][about-provenance]." - -To view provenance information for a package in the npm registry: - -1. In the npm registry, navigate to a package. - -2. On the package's page, in the **Version** field to the right of the README, look for a green check mark. If there is a green check mark, this means the package was published with provenance. - - - -3. Click on the check mark, then click **View more details**. - -4. View the following information for the package: - - - **Build Environment**: The environment used to build the package. - - **Build Summary**: A link to the workflow run that built the package. - - **Source Commit**: A link to the commit the package was built from. - - **Build File**: A link to the workflow file used to build the package. - - **Public Ledger**: A link to a transparency log entry attesting an authorized user published the package. - - - - - -**Note:** Whenever you access a package's provenance information on [npmjs.com](https://npmjs.com), the linked source commit and repository are checked by npm. If the linked source commit or repository cannot be found, an error message will appear at the top of the page and alongside the provenance information. This is to inform you that the provenance for this package can no longer be established, which may occur when a repository is deleted or made private. - - - - - -### Verifying provenance attestations - -When you download a package from the registry, you can verify the provenance of a package with the following CLI command: - -``` -npm audit signatures -``` - -This command checks the registry signatures and provenance attestations. If a package has missing or invalid signatures or attestations, it returns an error. This could indicate that a package has been tampered with. - - - -**Note:** In order to run the audit command to verify package provenance, you must: - -- Install npm CLI version `v9.5.0` or later: `npm install -g npm@latest` -- Install dependencies with `npm install` or `npm ci` - - - -[about-provenance]: /generating-provenance-statements#about-npm-provenance From f6fc3b54fa3682f59cc716f668c7e11c3ccfe59d Mon Sep 17 00:00:00 2001 From: Monish Chandra Mohan <23190045+monishcm@users.noreply.github.com> Date: Thu, 23 Jan 2025 19:29:26 +0530 Subject: [PATCH 2/9] Create viewing-package-provenance.mdx --- .../viewing-package-provenance.mdx | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 content/packages-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx diff --git a/content/packages-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx b/content/packages-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx new file mode 100644 index 00000000000..9115fe9ba20 --- /dev/null +++ b/content/packages-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx @@ -0,0 +1,63 @@ +--- +title: Viewing package provenance +redirect_from: + - /getting-started/searching-for-packages +--- + +## Viewing package provenance + +When packages have been published with provenance, you can: + +- Verify where and how a package was published. +- Validate that an authorized user published a package. + +You can use this information to audit packages and determine whether or not you want to consume them. For more information about npm provenance, see "[About npm provenance][about-provenance]." + +To view provenance information for a package in the npm registry: + +1. In the npm registry, navigate to a package. + +2. On the package's page, in the **Version** field to the right of the README, look for a green check mark. If there is a green check mark, this means the package was published with provenance. + + + +3. Click on the check mark, then click **View more details**. + +4. View the following information for the package: + + - **Build Environment**: The environment used to build the package. + - **Build Summary**: A link to the workflow run that built the package. + - **Source Commit**: A link to the commit the package was built from. + - **Build File**: A link to the workflow file used to build the package. + - **Public Ledger**: A link to a transparency log entry attesting an authorized user published the package. + + + + + +**Note:** Whenever you access a package's provenance information on [npmjs.com](https://npmjs.com), the linked source commit and repository are checked by npm. If the linked source commit or repository cannot be found, an error message will appear at the top of the page and alongside the provenance information. This is to inform you that the provenance for this package can no longer be established, which may occur when a repository is deleted or made private. + + + + + +### Verifying provenance attestations + +When you download a package from the registry, you can verify the provenance of a package with the following CLI command: + +``` +npm audit signatures +``` + +This command checks the registry signatures and provenance attestations. If a package has missing or invalid signatures or attestations, it returns an error. This could indicate that a package has been tampered with. + + + +**Note:** In order to run the audit command to verify package provenance, you must: + +- Install npm CLI version `v9.5.0` or later: `npm install -g npm@latest` +- Install dependencies with `npm install` or `npm ci` + + + +[about-provenance]: /generating-provenance-statements#about-npm-provenance From 802d736e676b3c37c6fcf1f0596884e61071343c Mon Sep 17 00:00:00 2001 From: Monish Chandra Mohan <23190045+monishcm@users.noreply.github.com> Date: Tue, 4 Feb 2025 21:58:55 +0530 Subject: [PATCH 3/9] Update content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx Updating to suggestions from @leobalter Co-authored-by: Leo Balter <301201+leobalter@users.noreply.github.com> --- .../searching-for-and-choosing-packages-to-download.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx index 702b29964cc..6009e798f75 100644 --- a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx +++ b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx @@ -4,7 +4,9 @@ redirect_from: - /getting-started/searching-for-packages --- -You can use the npm search bar to locate packages for your projects. The search function leverages information from a package's title, description, readme, and keywords, powered by OpenSearch. Results are displayed based on keyword matching from these fields, without subjective ranking criteria. However, adjustments are applied to deprioritise spammy or recently published packages to ensure search neutrality. Please note that newly published packages may take up to one-two week to appear in the search results. Additionally, deprecated packages are excluded from the search results to enhance the user experience. +You can use the npm search bar to find packages to use in your projects. The search is performed using content from the package's title, description, readme, and keywords and is powered by [opensearch](https://opensearch.org/). Search results are displayed based on keyword matching from the package's title, description, readme, and keywords. No subjective ranking criteria are applied, except for a minimal boost to deprioritize spammy or entirely new packages, aiming to maintain a neutral stance towards all other packages. + +Please note that newly published packages may take up to one-two week to appear in the search results. Additionally, deprecated packages are excluded from the search results to enhance the user experience. ## Searching for a package From 6ff2807b8c59074397c6e4b3c4e08625b185e6c7 Mon Sep 17 00:00:00 2001 From: Monish Chandra Mohan <23190045+monishcm@users.noreply.github.com> Date: Wed, 12 Feb 2025 01:54:09 +0530 Subject: [PATCH 4/9] Update content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx Co-authored-by: Chris Patterson --- .../searching-for-and-choosing-packages-to-download.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx index 6009e798f75..49a39c7f8ea 100644 --- a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx +++ b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx @@ -6,7 +6,7 @@ redirect_from: You can use the npm search bar to find packages to use in your projects. The search is performed using content from the package's title, description, readme, and keywords and is powered by [opensearch](https://opensearch.org/). Search results are displayed based on keyword matching from the package's title, description, readme, and keywords. No subjective ranking criteria are applied, except for a minimal boost to deprioritize spammy or entirely new packages, aiming to maintain a neutral stance towards all other packages. -Please note that newly published packages may take up to one-two week to appear in the search results. Additionally, deprecated packages are excluded from the search results to enhance the user experience. +Please note that newly published packages may take up to two weeks to appear in the search results. Additionally, deprecated packages are excluded from the search results to enhance the user experience. ## Searching for a package From 3676414a000f5ea648dd84207dafe3271035f095 Mon Sep 17 00:00:00 2001 From: Monish Chandra Mohan <23190045+monishcm@users.noreply.github.com> Date: Wed, 12 Feb 2025 02:03:54 +0530 Subject: [PATCH 5/9] Add note about package provenance information. --- .../searching-for-and-choosing-packages-to-download.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx index 49a39c7f8ea..19788a0b491 100644 --- a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx +++ b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx @@ -21,3 +21,4 @@ Please note that newly published packages may take up to two weeks to appear in 3. In the package search results list, click the name of the package. +4. The package homepage also displays provenance information when available. For details on how to verify it check [viewing package provenance](/viewing-package-provenance) From d4c09a19ec9724261a60570272bfc815a460ac7d Mon Sep 17 00:00:00 2001 From: Monish Chandra Mohan <23190045+monishcm@users.noreply.github.com> Date: Wed, 12 Feb 2025 02:10:49 +0530 Subject: [PATCH 6/9] Fix typo in package provenance information. --- .../searching-for-and-choosing-packages-to-download.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx index 19788a0b491..c24a6209810 100644 --- a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx +++ b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx @@ -21,4 +21,4 @@ Please note that newly published packages may take up to two weeks to appear in 3. In the package search results list, click the name of the package. -4. The package homepage also displays provenance information when available. For details on how to verify it check [viewing package provenance](/viewing-package-provenance) +4. The package homepage also displays provenance information when available. For details on how to verify this, check [viewing package provenance](/viewing-package-provenance) From 5bfa597a9564459ddfec3e7b0f190462b3fd3859 Mon Sep 17 00:00:00 2001 From: Monish Chandra Mohan <23190045+monishcm@users.noreply.github.com> Date: Wed, 12 Feb 2025 18:21:46 +0530 Subject: [PATCH 7/9] Update content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx Co-authored-by: Leo Balter <301201+leobalter@users.noreply.github.com> --- .../searching-for-and-choosing-packages-to-download.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx index c24a6209810..4236c7188ab 100644 --- a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx +++ b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx @@ -21,4 +21,6 @@ Please note that newly published packages may take up to two weeks to appear in 3. In the package search results list, click the name of the package. -4. The package homepage also displays provenance information when available. For details on how to verify this, check [viewing package provenance](/viewing-package-provenance) +## Package provenance + +The package homepage also displays provenance information when available. For details on how to verify this information, check [viewing package provenance](/viewing-package-provenance). From 7b65c1a6ec382a73dbf0b1198b0453a6333fdfe8 Mon Sep 17 00:00:00 2001 From: Monish Chandra Mohan <23190045+monishcm@users.noreply.github.com> Date: Wed, 12 Feb 2025 18:22:47 +0530 Subject: [PATCH 8/9] Update content/packages-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx Co-authored-by: Leo Balter <301201+leobalter@users.noreply.github.com> --- .../viewing-package-provenance.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/content/packages-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx b/content/packages-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx index 9115fe9ba20..566670ba67f 100644 --- a/content/packages-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx +++ b/content/packages-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx @@ -1,7 +1,5 @@ --- title: Viewing package provenance -redirect_from: - - /getting-started/searching-for-packages --- ## Viewing package provenance From a3b0b3597965c98c1d3c2e675e84db3403733898 Mon Sep 17 00:00:00 2001 From: Monish Chandra Mohan <23190045+monishcm@users.noreply.github.com> Date: Wed, 12 Feb 2025 18:51:36 +0530 Subject: [PATCH 9/9] Fix style issue --- .../searching-for-and-choosing-packages-to-download.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx index 4236c7188ab..bf6c2d19cf0 100644 --- a/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx +++ b/content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx @@ -21,6 +21,7 @@ Please note that newly published packages may take up to two weeks to appear in 3. In the package search results list, click the name of the package. + ## Package provenance The package homepage also displays provenance information when available. For details on how to verify this information, check [viewing package provenance](/viewing-package-provenance).