feat(sbom): add SBOM attestation cache pipeline

.github/workflows/pages.yml

@@ -50,6 +50,7 @@ jobs:
           path: static/data
           key: github-data-${{ hashFiles('scripts/fetch-*.js') }}
           restore-keys: |
+            github-data-sbom-
             github-data-
 
       - name: Install dependencies

.github/workflows/update-sbom-cache.yml

@@ -10,7 +10,7 @@ concurrency:
   cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
 
 permissions:
-  contents: write # for git commit + push
+  contents: read
 
 jobs:
   update-sbom-cache:
@@ -46,6 +46,15 @@ jobs:
         if: steps.cache-node-modules.outputs.cache-hit != 'true'
         run: npm ci
 
+      - name: Restore existing SBOM data cache (for incremental updates)
+        uses: actions/cache/restore@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
+        with:
+          path: static/data
+          key: github-data-sbom-${{ github.run_id }}
+          restore-keys: |
+            github-data-sbom-
+            github-data-
+
       - name: Install cosign
         uses: sigstore/cosign-installer@d7d6bc7722e3daa8354c50bcb52f4837da5e9b6a # v3.8.1
 
@@ -65,14 +74,8 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.PROJECT_READ_TOKEN }}
         run: npm run fetch-sbom
 
-      - name: Commit updated cache
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add static/data/sbom-attestations.json
-          if git diff --cached --quiet; then
-            echo "No changes to sbom-attestations.json — skipping commit."
-          else
-            git commit -m "chore(sbom): update attestation cache $(date -u +%Y-%m-%d)"
-            git push
-          fi
+      - name: Save SBOM data cache
+        uses: actions/cache/save@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
+        with:
+          path: static/data
+          key: github-data-sbom-${{ github.run_id }}

.gitignore

@@ -12,8 +12,6 @@
 /docs/contributing.md
 /static/feeds/*.json
 /static/data/*.json
-# Seed file for SBOM attestation cache — must exist at build time
-!/static/data/sbom-attestations.json
 
 # Misc
 .DS_Store

docs/devcontainers.md

@@ -40,11 +40,13 @@ docker --version
 
 By default, the Dev Containers extension uses docker.
 To switch to podman, make the following changes in Dev Containers settings:
-```
+
+```json
 "dev.containers.dockerComposePath": "podman-compose"
 "dev.containers.dockerPath": "podman"
 "dev.containers.dockerSocketPath": "/run/user/1000/podman/podman.sock"
 ```
+
 You can use `systemctl --user status podman.socket` to find the socket path corresponding to your user id. Or if you want to run podman in rootful mode, use `/run/podman/podman.sock` instead.
 
 ## Getting Started

scripts/fetch-github-images.js

@@ -210,8 +210,12 @@ function parseFedoraFromImageVersion(imageVersion) {
 
 function latestFeedItem(feeds, source) {
   if (!source) return null;
+  // stable-daily has no dedicated release feed — returning stable metadata would
+  // misrepresent daily-only images as stable releases. Return null so callers
+  // render unknown values instead.
+  if (source.stream === "stable-daily") return null;
   const items = source.feed === "lts" ? feeds.lts.items : feeds.bluefin.items;
-  const stream = source.stream === "stable-daily" ? "stable" : source.stream;
+  const stream = source.stream;
 
   const match = items.find((item) => {
     const title = (item.title || "").toLowerCase();

scripts/fetch-github-sbom.js

@@ -159,8 +159,11 @@
     try {
       batch = await fetchJson(url);
     } catch (err) {
-      console.warn(`  Packages API page ${page} failed: ${err.message}`);
-      break;
+      // Rethrow so the caller (main) can preserve existing cache for this package
+      // rather than silently returning an empty result and clearing all releases.
+      throw new Error(
+        `Packages API page ${page} for ${org}/${pkg} failed: ${err.message}`,
+      );
     }
     if (!Array.isArray(batch) || batch.length === 0) break;
     versions.push(...batch);
@@ -238,7 +241,7 @@
       maxBuffer: 4 * 1024 * 1024,
     });
     stdout = result.stdout;
     stderr = result.stderr;
   } catch (err) {
     const msg = (err.stderr || err.message || "").toLowerCase();
     // cosign exits non-zero when no attestation exists
@@ -254,16 +257,21 @@
         error: "no attestation",
       };
     }
+    // Unexpected tooling/registry/auth failure — do NOT claim present: true.
+    // Callers use present: false (no attestation) vs present: null (error/unknown)
+    // to distinguish absence from verification failure.
     return {
-      present: true,
+      present: null,
       verified: false,
       predicateType: null,
+      errorKind: "tooling",
       error: String(err.stderr || err.message),
     };
   }
 
-  // cosign outputs NDJSON (one JSON object per line)
-  const lines = (stdout + stderr)
+  // cosign outputs NDJSON (one JSON object per line) on stdout only;
+  // stderr carries status messages ("Verification OK") that must not be parsed.
+  const lines = stdout
     .split("\n")
     .map((l) => l.trim())
     .filter((l) => l.startsWith("{"));
@@ -547,6 +555,12 @@
       const dateStr = extractDateFromTag(normalised);
       if (!dateStr) continue;
 
+      // Enforce canonical tag: only exact `<streamPrefix>-YYYYMMDD` is accepted.
+      // Non-canonical variants like lts-hwe-testing-20260331 would normalise to
+      // lts-20260331 and silently overwrite valid canonical entries.
+      const expectedCanonical = `${spec.streamPrefix}-${dateStr}`;
+      if (normalised !== expectedCanonical) continue;
+
       found.push({
         tag: normalised,
         cacheKey: buildCacheKey(spec.streamPrefix, dateStr),
@@ -577,7 +591,18 @@
  */
 async function processStream(spec, allVersionsByPackage, existing) {
   const pkgKey = `${spec.org}/${spec.package}`;
-  const allVersions = allVersionsByPackage.get(pkgKey) || [];
+  // If the key is absent the Packages API fetch failed — preserve existing cache.
+  if (!allVersionsByPackage.has(pkgKey)) {
+    if (existing?.streams?.[spec.id]) {
+      console.log(
+        `  ${spec.id}: Packages API unavailable — keeping existing cache`,
+      );
+      return existing.streams[spec.id];
+    }
+    // No existing cache to fall back to; return empty stream.
+    return { ...spec, releases: {} };
+  }
+  const allVersions = allVersionsByPackage.get(pkgKey);
   const recentTags = findRecentTagsForStream(allVersions, spec);
 
   console.log(
@@ -616,6 +641,9 @@
         verified: attestation.verified,
         predicateType: attestation.predicateType,
         slsaType: SLSA_TYPE,
+        ...(attestation.errorKind !== undefined && {
+          errorKind: attestation.errorKind,
+        }),
         error: attestation.error,
       };
     }
@@ -714,7 +742,8 @@
       console.log(`    ${versions.length} versions fetched`);
     } catch (err) {
       console.error(`  Failed to fetch versions for ${key}: ${err.message}`);
-      allVersionsByPackage.set(key, []);
+      // Do NOT set an empty array — leave the key absent so processStream
+      // detects the fetch failure and preserves the existing cache instead.
     }
   }
 

src/types/sbom-attestations.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Type declaration for the SBOM attestation cache data file.
+ *
+ * static/data/sbom-attestations.json is generated at CI time by
+ * scripts/fetch-github-sbom.js and restored from GitHub Actions cache before
+ * the build runs. It is gitignored and will not exist during local `tsc`
+ * typechecks — this ambient declaration satisfies the compiler without
+ * requiring the file to be present on disk.
+ */
+
+declare module "@site/static/data/sbom-attestations.json" {
+  import type { SbomAttestationsData } from "@site/src/types/sbom";
+  const data: SbomAttestationsData;
+  export default data;
+}

src/types/sbom.ts

@@ -7,19 +7,29 @@
 export interface AttestationResult {
   /**
    * Whether a SLSA provenance attestation was found for this image.
+   * true  = attestation present and verified.
    * false = no attestation published (the command will fail if run).
+   * null  = verification could not complete due to a tooling/registry/auth
+   *         error; attestation existence is unknown.
    */
-  present: boolean;
+  present: boolean | null;
   /**
    * Whether the attestation passed cosign signature verification.
-   * false with present:true = attestation exists but verification failed.
+   * false with present:true  = attestation exists but verification failed.
    * false with present:false = attestation does not exist.
+   * false with present:null  = verification could not be attempted.
    */
   verified: boolean;
   /** SLSA predicate type URI, populated when present:true */
   predicateType: string | null;
   /** SLSA type URL used during verification */
   slsaType: string;
+  /**
+   * Error classification for present:null results.
+   * "tooling" = cosign/oras/registry error (transient or auth failure).
+   * Absent (undefined) for present:true/false results.
+   */
+  errorKind?: "tooling";
   /** Human-readable error string when present:false or verified:false */
   error: string | null;
 }