From 9b5430ffbf9646e9a3b2bc0188c74e7c42137644 Mon Sep 17 00:00:00 2001
From: Ramon Petgrave <ramon.petgrave64@gmail.com>
Date: Mon, 24 Jun 2024 19:04:47 +0000
Subject: [PATCH] docs and npm attestations example

Signed-off-by: Ramon Petgrave <ramon.petgrave64@gmail.com>
---
 README.md   |  2 ++
 docs/npm.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 docs/npm.md

diff --git a/README.md b/README.md
index 9164f18b7..824811398 100644
--- a/README.md
+++ b/README.md
@@ -315,6 +315,8 @@ PASSED: Verified SLSA provenance
 
 Verification of npm packages is currently an experimental feature.
 
+More deetails about npm attestations are in [docs/npm.md](./docs/npm.md)
+
 #### The verify-npm-package command
 
 ```bash
diff --git a/docs/npm.md b/docs/npm.md
new file mode 100644
index 000000000..8bacc3e86
--- /dev/null
+++ b/docs/npm.md
@@ -0,0 +1,83 @@
+# NPM
+
+## Provenance
+
+### V1
+
+Unwrapped and base64-decoded from the Sigstore Bundles and DSSE Envelopes, NPM V1 attestations are actually two parts: SLSA's build provenance and NPM's publish attestations. slsa-verifier will verify the envelopes and bundles around both attestations with the attestations file.
+
+example build attestation
+
+```json
+$ curl -Ss $(npm view gundam-visor@1.0.1 --json | jq -r '.dist.attestations.url') | jq '.attestations[1].bundle.dsseEnvelope.payload' -r | base64 -d | jq
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [
+    {
+      "name": "pkg:npm/gundam-visor@1.0.1",
+      "digest": {
+        "sha512": "8d9d7972f676516c75014aa074e11ae604d98f0b64ec6725a61e2838ff3dab162118fa71433fb31e1550d30bd0dec9d086ce032b94457b583900c507acf39c40"
+      }
+    }
+  ],
+  "predicateType": "https://slsa.dev/provenance/v1",
+  "predicate": {
+    "buildDefinition": {
+      "buildType": "https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1",
+      "externalParameters": {
+        "workflow": {
+          "ref": "refs/tags/v1.0.1",
+          "repository": "https://github.com/ramonpetgrave64/gundam-visor",
+          "path": ".github/workflows/npm-publish.yml"
+        }
+      },
+      "internalParameters": {
+        "github": {
+          "event_name": "release",
+          "repository_id": "810002373",
+          "repository_owner_id": "32398091"
+        }
+      },
+      "resolvedDependencies": [
+        {
+          "uri": "git+https://github.com/ramonpetgrave64/gundam-visor@refs/tags/v1.0.1",
+          "digest": {
+            "gitCommit": "599500821344b070902a7a5666064bfdaba715df"
+          }
+        }
+      ]
+    },
+    "runDetails": {
+      "builder": {
+        "id": "https://github.com/actions/runner/github-hosted"
+      },
+      "metadata": {
+        "invocationId": "https://github.com/ramonpetgrave64/gundam-visor/actions/runs/9358004112/attempts/1"
+      }
+    }
+  }
+}
+```
+
+exmaple publish attestation
+
+```json
+$ curl -Ss $(npm view gundam-visor@1.0.1 --json | jq -r '.dist.attestations.url') | jq '.attestations[0].bundle.dsseEnvelope.payload' -r | base64 -d | jq
+{
+  "_type": "https://in-toto.io/Statement/v0.1",
+  "subject": [
+    {
+      "name": "pkg:npm/gundam-visor@1.0.1",
+      "digest": {
+        "sha512": "8d9d7972f676516c75014aa074e11ae604d98f0b64ec6725a61e2838ff3dab162118fa71433fb31e1550d30bd0dec9d086ce032b94457b583900c507acf39c40"
+      }
+    }
+  ],
+  "predicateType": "https://github.com/npm/attestation/tree/main/specs/publish/v0.1",
+  "predicate": {
+    "name": "gundam-visor",
+    "version": "1.0.1",
+    "registry": "https://registry.npmjs.org"
+  }
+}
+```