Merge branch 'main' into renovate/npm-dev

.gitignore

@@ -1,2 +1,3 @@
 .idea
+node_modules
 vendor

.golangci.yml

@@ -21,7 +21,6 @@ linters:
   disable-all: true
   enable:
     - asciicheck
-    - deadcode
     - depguard
     - dogsled
     # TODO(https://github.com/slsa-framework/slsa-verifier/issues/363): Restore linter

Makefile

@@ -17,6 +17,10 @@ help: ## Shows all targets and help from the Makefile (this message).
 			} \
 		}'
 
+node_modules/.installed: package.json package-lock.json
+	npm ci
+	touch node_modules/.installed
+
 ## Testing
 #####################################################################
 
@@ -30,7 +34,27 @@ unit-test: ## Runs all unit tests.
 regression-test: ## Runs all regression and unit tests.
 	go mod vendor
 	# NOTE: go test builds packages even if there are no tests.
-	go test -mod=vendor -tags=regression -v -timeout=20m ./...
+	go test -mod=vendor -tags=regression -v -timeout=25m ./...
+
+## Tools
+#####################################################################
+
+.PHONY: markdown-toc
+markdown-toc: node_modules/.installed ## Runs markdown-toc on markdown files.
+	@# NOTE: Do not include issue templates since they contain Front Matter.
+	@# markdown-toc will update Front Matter even if there is no TOC in the file.
+	@# See: https://github.com/jonschlinkert/markdown-toc/issues/151
+	@set -euo pipefail; \
+		md_files=$$( \
+			find . -name '*.md' -type f \
+				-not -iwholename '*/.git/*' \
+				-not -iwholename '*/vendor/*' \
+				-not -iwholename '*/node_modules/*' \
+				-not -iwholename '*/.github/ISSUE_TEMPLATE/*' \
+		); \
+		for filename in $${md_files}; do \
+			npm run markdown-toc "$${filename}"; \
+		done;
 
 ## Linters
 #####################################################################

README.md

@@ -20,7 +20,7 @@
   - [Compilation from source](#compilation-from-source)
     - [Option 1: Install via go](#option-1-install-via-go)
     - [Option 2: Compile manually](#option-2-compile-manually)
-  - [Use the installer Action on GitHub](#use-the-installer-action-on-github-actions)
+  - [Use the installer Action on GitHub Actions](#use-the-installer-action-on-github-actions)
   - [Download the binary](#download-the-binary)
 - [Available options](#available-options)
 - [Option list](#option-list)
@@ -31,6 +31,9 @@
 - [Verification for Google Cloud Build](#verification-for-google-cloud-build)
   - [Artifacts](#artifacts-1)
   - [Containers](#containers-1)
+- [Verification for npm packages](#verification-for-npm-packages)
+  - [The verify-npm-package command](#the-verify-npm-package-command)
+  - [Verify npm packages built using the SLSA3 Node.js builder](#verify-npm-packages-built-using-the-slsa3-nodejs-builder)
 - [Known Issues](#known-issues)
   - [tuf: invalid key](#tuf-invalid-key)
   - [panic: assignment to entry in nil map](#panic-assignment-to-entry-in-nil-map)
@@ -217,11 +220,17 @@ Verified build using builder https://github.com/slsa-framework/slsa-github-gener
 PASSED: Verified SLSA provenance
 ```
 
-The verified in-toto statement may be written to stdout with the `--print-provenance` flag to pipe into policy engines.
+The verified in-toto statement may be written to stdout with the
+`--print-provenance` flag to pipe into policy engines.
 
-Only GitHub URIs are supported with the `--source-uri` flag. A tag should not be specified, even if the provenance was built at some tag. If you intend to do source versioning validation, use `--print-provenance` and inspect the commit SHA of the config source or materials.
+Only GitHub URIs are supported with the `--source-uri` flag. A tag should not
+be specified, even if the provenance was built at some tag. If you intend to do
+source versioning validation, you can use `--source-tag` to validate the
+release tag. For commit SHA validation, use `--print-provenance` and inspect
+the commit SHA of the config source or materials.
 
-Multiple artifacts built from the same GitHub builder can be verified in the same command, by passing them in the same command line as arguments:
+Multiple artifacts built from the same GitHub builder can be verified in the
+same command, by passing them in the same command line as arguments:
 
 ```bash
 $ slsa-verifier verify-artifact \
@@ -316,10 +325,71 @@ You should see that the verification passed in the output.
 PASSED: Verified SLSA provenance
 ```
 
-The verified in-toto statement may be written to stdout with the `--print-provenance` flag to pipe into policy engines.
+The verified in-toto statement may be written to stdout with the
+`--print-provenance` flag to pipe into policy engines.
 
 Note that `--source-uri` supports GitHub repository URIs like `github.com/$OWNER/$REPO` when the build was enabled with a Cloud Build [GitHub trigger](https://cloud.google.com/build/docs/automating-builds/github/build-repos-from-github). Otherwise, the build provenance will contain the name of the Cloud Storage bucket used to host the source files, usually of the form `gs://[PROJECT_ID]_cloudbuild/source` (see [Running build](https://cloud.google.com/build/docs/running-builds/submit-build-via-cli-api#running_builds)). We recommend using GitHub triggers in order to preserve the source provenance and valiate that the source came from an expected, version-controlled repository. You _may_ match on the fully-qualified tar like `gs://[PROJECT_ID]_cloudbuild/source/1665165360.279777-955d1904741e4bbeb3461080299e929a.tgz`.
 
+## Verification for npm packages
+
+Verification of npm packages is currently an experimental feature.
+
+### The verify-npm-package command
+
+```bash
+$ slsa-verifier verify-npm-package --help
+Verifies SLSA provenance for an npm package tarball [experimental]
+
+Usage:
+  slsa-verifier verify-npm-package [flags] tarball
+
+Flags:
+      --attestations-path string      path to a file containing the attestations
+      --build-workflow-input map[]    [optional] a workflow input provided by a user at trigger time in the format 'key=value'. (Only for 'workflow_dispatch' events on GitHub Actions). (default map[])
+      --builder-id string             [optional] the unique builder ID who created the provenance
+  -h, --help                          help for verify-npm-package
+      --package-name string           [optional] the package name
+      --package-version string        [optional] the package version
+      --print-provenance              [optional] print the verified provenance to stdout
+      --source-branch string          [optional] expected branch the binary was compiled from
+      --source-tag string             [optional] expected tag the binary was compiled from
+      --source-uri string             expected source repository that should have produced the binary, e.g. github.com/some/repo
+      --source-versioned-tag string   [optional] expected version the binary was compiled from. Uses semantic version to match the tag
+```
+
+### Verify npm packages built using the SLSA3 Node.js builder
+
+This section describes how to verify packages built using the SLSA Build L3
+[Node.js builder](https://github.com/slsa-framework/slsa-github-generator/blob/main/internal/builders/nodejs/README.md).
+
+To verify a npm packages, first download the package tarball and attestations.
+
+```shell
+curl -Sso attestations.json $(npm view @ianlewis/actions-test@0.1.126 --json | jq -r '.dist.attestations.url') && \
+curl -Sso actions-test.tgz "$(npm view @ianlewis/actions-test@0.1.126 --json | jq -r '.dist.tarball')"
+```
+
+You can then verify the package by running the following command:
+
+```shell
+$ SLSA_VERIFIER_EXPERIMENTAL=1 slsa-verifier verify-npm-package actions-test.tgz \
+  --attestations-path attestations.json \
+  --builder-id "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_nodejs_slsa3.yml" \
+  --package-name "@ianlewis/actions-test" \
+  --package-version 0.1.126 \
+  --source-uri github.com/ianlewis/actions-test
+```
+
+The verified in-toto statement may be written to stdout with the
+`--print-provenance` flag to pipe into policy engines.
+
+Only GitHub URIs are supported with the `--source-uri` flag. A tag should not
+be specified, even if the provenance was built at some tag. If you intend to do
+source versioning validation, you can use `--source-tag` to validate the
+release tag and `--package-version` to validate the package version. For commit
+SHA validation, use `--print-provenance` and inspect the commit SHA of the
+config source or materials.
+
 ## Known Issues
 
 ### tuf: invalid key

errors/errors.go

@@ -12,12 +12,15 @@ var (
 	ErrorMismatchSource            = errors.New("source used to generate the binary does not match provenance")
 	ErrorMismatchWorkflowInputs    = errors.New("workflow input does not match")
 	ErrorMalformedURI              = errors.New("URI is malformed")
+	ErrorMismatchCertificate       = errors.New("certificate and provenance mismatch")
+	ErrorInvalidCertificate        = errors.New("invalid certificate")
 	ErrorMismatchTag               = errors.New("tag used to generate the binary does not match provenance")
 	ErrorInvalidRecipe             = errors.New("the recipe is invalid")
 	ErrorMismatchVersionedTag      = errors.New("tag used to generate the binary does not match provenance")
 	ErrorInvalidSemver             = errors.New("invalid semantic version")
 	ErrorRekorSearch               = errors.New("error searching rekor entries")
 	ErrorMismatchHash              = errors.New("artifact hash does not match provenance subject")
+	ErrorNonVerifiableClaim        = errors.New("provenance claim cannot be verified")
 	ErrorMismatchIntoto            = errors.New("verified intoto provenance does not match text provenance")
 	ErrorInvalidRef                = errors.New("invalid ref")
 	ErrorUntrustedReusableWorkflow = errors.New("untrusted reusable workflow")

go.mod

@@ -147,7 +147,7 @@ require (
 	github.com/sassoftware/relic v7.2.1+incompatible // indirect
 	github.com/segmentio/ksuid v1.0.4 // indirect
 	github.com/shibumi/go-pathspec v1.3.0 // indirect
-	github.com/sigstore/fulcio v1.2.0 // indirect
+	github.com/sigstore/fulcio v1.2.0
 	github.com/sigstore/protobuf-specs v0.1.1-0.20230503063121-91485b44360d
 	github.com/sirupsen/logrus v1.9.0 // indirect
 	github.com/skratchdot/open-golang v0.0.0-20200116055534-eef842397966 // indirect