feat: add provenance to end of README and provenance badge (#436)

AscaL · autofix-ci[bot] · OrbisK · web-flow · commit bf0c8f7afb7e · 2026-02-04T11:57:49.000Z
Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
Co-authored-by: Robin &lt;robin.kehl@singular-it.de&gt;
Co-authored-by: Okinea Dev &lt;hi@okinea.dev&gt;
Co-authored-by: Daniel Roe &lt;daniel@roe.dev&gt;
diff --git a/README.md b/README.md
@@ -44,7 +44,7 @@ What npmx offers:
 - **Fast search** &ndash; quick package search with instant results
 - **Package details** &ndash; READMEs, versions, dependencies, and metadata
 - **Code viewer** &ndash; browse package source code with syntax highlighting and permalink to specific lines
-- **Provenance indicators** &ndash; verified build badges for packages with npm provenance
+- **Provenance indicators** &ndash; verified build badges and provenance section below the README
 - **Multi-provider repository support** &ndash; stars/forks from GitHub, GitLab, Bitbucket, Codeberg, Gitee, Sourcehut, Forgejo, Gitea, Radicle, and Tangled
 - **JSR availability** &ndash; see if scoped packages are also available on JSR
 - **Package badges** &ndash; module format (ESM/CJS/dual), TypeScript types (with `@types/*` links), and engine constraints
diff --git a/app/components/PackageProvenanceSection.vue b/app/components/PackageProvenanceSection.vue
@@ -0,0 +1,96 @@
+<script setup lang="ts">
+import type { ProvenanceDetails } from '#shared/types'
+
+defineProps<{
+  details: ProvenanceDetails
+}>()
+</script>
+
+<template>
+  <section aria-labelledby="provenance-heading" class="scroll-mt-20">
+    <h2 id="provenance-heading" class="group text-xs text-fg-subtle uppercase tracking-wider mb-3">
+      <a
+        href="#provenance"
+        class="inline-flex items-center gap-1.5 text-fg-subtle hover:text-fg-muted transition-colors duration-200 no-underline"
+      >
+        {{ $t('package.provenance_section.title') }}
+        <span
+          class="i-carbon-link w-3 h-3 block opacity-0 group-hover:opacity-100 transition-opacity duration-200"
+          aria-hidden="true"
+        />
+      </a>
+    </h2>
+
+    <div class="space-y-3 border border-border rounded-lg p-5">
+      <p class="flex items-center gap-2 text-sm text-fg m-0">
+        <span class="i-lucide-shield-check w-4 h-4 shrink-0 text-emerald-500" aria-hidden="true" />
+        <i18n-t keypath="package.provenance_section.built_and_signed_on" tag="span">
+          <template #provider>
+            <strong>{{ details.providerLabel }}</strong>
+          </template>
+        </i18n-t>
+      </p>
+      <a
+        v-if="details.buildSummaryUrl"
+        :href="details.buildSummaryUrl"
+        target="_blank"
+        rel="noopener noreferrer"
+        class="link text-sm text-fg-muted block mt-1"
+      >
+        {{ $t('package.provenance_section.view_build_summary') }}
+      </a>
+
+      <dl class="m-0 mt-4 flex justify-between">
+        <div v-if="details.sourceCommitUrl" class="flex flex-col gap-0.5">
+          <dt class="font-mono text-xs text-fg-muted m-0">
+            {{ $t('package.provenance_section.source_commit') }}
+          </dt>
+          <dd class="m-0">
+            <a
+              :href="details.sourceCommitUrl"
+              target="_blank"
+              rel="noopener noreferrer"
+              class="link font-mono text-sm break-all"
+            >
+              {{
+                details.sourceCommitSha
+                  ? `${details.sourceCommitSha.slice(0, 12)}`
+                  : details.sourceCommitUrl
+              }}
+            </a>
+          </dd>
+        </div>
+        <div v-if="details.buildFileUrl" class="flex flex-col gap-0.5">
+          <dt class="font-mono text-xs text-fg-muted m-0">
+            {{ $t('package.provenance_section.build_file') }}
+          </dt>
+          <dd class="m-0">
+            <a
+              :href="details.buildFileUrl"
+              target="_blank"
+              rel="noopener noreferrer"
+              class="link font-mono text-sm break-all"
+            >
+              {{ details.buildFilePath ?? details.buildFileUrl }}
+            </a>
+          </dd>
+        </div>
+        <div v-if="details.publicLedgerUrl" class="flex flex-col gap-0.5">
+          <dt class="font-mono text-xs text-fg-muted m-0">
+            {{ $t('package.provenance_section.public_ledger') }}
+          </dt>
+          <dd class="m-0">
+            <a
+              :href="details.publicLedgerUrl"
+              target="_blank"
+              rel="noopener noreferrer"
+              class="link text-sm"
+            >
+              {{ $t('package.provenance_section.transparency_log_entry') }}
+            </a>
+          </dd>
+        </div>
+      </dl>
+    </div>
+  </section>
+</template>
diff --git a/app/pages/package/[...package].vue b/app/pages/package/[...package].vue
@@ -2,6 +2,7 @@
 import type {
   NpmVersionDist,
   PackumentVersion,
+  ProvenanceDetails,
   ReadmeResponse,
   SkillsListResponse,
 } from '#shared/types'
@@ -158,6 +159,39 @@ const { data: vulnTree, status: vulnTreeStatus } = useDependencyAnalysis(
   () => resolvedVersion.value ?? '',
 )
 
+const {
+  data: provenanceData,
+  status: provenanceStatus,
+  execute: fetchProvenance,
+} = useLazyFetch<ProvenanceDetails | null>(
+  () => {
+    const v = displayVersion.value
+    if (!v || !hasProvenance(v)) return ''
+    return `/api/registry/provenance/${packageName.value}/v/${v.version}`
+  },
+  {
+    default: () => null,
+    server: false,
+    immediate: false,
+  },
+)
+if (import.meta.client) {
+  watch(
+    displayVersion,
+    v => {
+      if (v && hasProvenance(v) && provenanceStatus.value === 'idle') {
+        fetchProvenance()
+      }
+    },
+    { immediate: true },
+  )
+}
+
+const provenanceBadgeMounted = shallowRef(false)
+onMounted(() => {
+  provenanceBadgeMounted.value = true
+})
+
 // Keep latestVersion for comparison (to show "(latest)" badge)
 const latestVersion = computed(() => {
   if (!pkg.value) return null
@@ -523,16 +557,26 @@ defineOgImageComponent('Package', {
             >
             <span v-else>v{{ resolvedVersion }}</span>
 
-            <a
-              v-if="hasProvenance(displayVersion)"
-              :href="`https://www.npmjs.com/package/${pkg.name}/v/${resolvedVersion}#provenance`"
-              target="_blank"
-              rel="noopener noreferrer"
-              class="inline-flex items-center justify-center gap-1.5 text-fg-muted hover:text-fg transition-colors duration-200 min-w-6 min-h-6"
-              :title="$t('package.verified_provenance')"
-            >
-              <span class="i-lucide-shield-check w-3.5 h-3.5 shrink-0" aria-hidden="true" />
-            </a>
+            <template v-if="hasProvenance(displayVersion) && provenanceBadgeMounted">
+              <TooltipApp
+                :text="
+                  provenanceData && provenanceStatus !== 'pending'
+                    ? $t('package.provenance_section.built_and_signed_on', {
+                        provider: provenanceData.providerLabel,
+                      })
+                    : $t('package.verified_provenance')
+                "
+                position="bottom"
+              >
+                <a
+                  href="#provenance"
+                  :aria-label="$t('package.provenance_section.view_more_details')"
+                  class="inline-flex items-center justify-center gap-1.5 text-fg-muted hover:text-emerald-500 transition-colors duration-200 min-w-6 min-h-6"
+                >
+                  <span class="i-lucide-shield-check w-3.5 h-3.5 shrink-0" aria-hidden="true" />
+                </a>
+              </TooltipApp>
+            </template>
             <span
               v-if="requestedVersion && latestVersion && resolvedVersion !== latestVersion.version"
               class="text-fg-subtle text-sm shrink-0"
@@ -1084,8 +1128,37 @@ defineOgImageComponent('Package', {
             >{{ $t('package.readme.view_on_github') }}</a
           >
         </p>
-      </section>
 
+        <section
+          v-if="hasProvenance(displayVersion) && provenanceBadgeMounted"
+          id="provenance"
+          class="scroll-mt-20"
+        >
+          <div
+            v-if="provenanceStatus === 'pending'"
+            class="mt-8 flex items-center gap-2 text-fg-subtle text-sm"
+          >
+            <span
+              class="i-carbon-circle-dash w-4 h-4 motion-safe:animate-spin"
+              aria-hidden="true"
+            />
+            <span>{{ $t('package.provenance_section.title') }}…</span>
+          </div>
+          <PackageProvenanceSection
+            v-else-if="provenanceData"
+            :details="provenanceData"
+            class="mt-8"
+          />
+          <!-- Error state: provenance exists but details failed to load -->
+          <div
+            v-else-if="provenanceStatus === 'error'"
+            class="mt-8 flex items-center gap-2 text-fg-subtle text-sm"
+          >
+            <span class="i-carbon:warning w-4 h-4" aria-hidden="true" />
+            <span>{{ $t('package.provenance_section.error_loading') }}</span>
+          </div>
+        </section>
+      </section>
       <div class="area-sidebar">
         <!-- Sidebar -->
         <div
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
@@ -210,6 +210,17 @@
       "view_on_github": "View on GitHub",
       "toc_title": "Outline"
     },
+    "provenance_section": {
+      "title": "Provenance",
+      "built_and_signed_on": "Built and signed on {provider}",
+      "view_build_summary": "View build summary",
+      "source_commit": "Source Commit",
+      "build_file": "Build File",
+      "public_ledger": "Public Ledger",
+      "transparency_log_entry": "Transparency log entry",
+      "view_more_details": "View more details",
+      "error_loading": "Failed to load provenance details"
+    },
     "keywords_title": "Keywords",
     "compatibility": "Compatibility",
     "card": {
@@ -610,7 +621,8 @@
     "provenance": {
       "verified": "verified",
       "verified_title": "Verified provenance",
-      "verified_via": "Verified: published via {provider}"
+      "verified_via": "Verified: published via {provider}",
+      "view_more_details": "View more details"
     },
     "jsr": {
       "title": "also available on JSR",
diff --git a/lunaria/files/en-GB.json b/lunaria/files/en-GB.json
@@ -210,6 +210,17 @@
       "view_on_github": "View on GitHub",
       "toc_title": "Outline"
     },
+    "provenance_section": {
+      "title": "Provenance",
+      "built_and_signed_on": "Built and signed on {provider}",
+      "view_build_summary": "View build summary",
+      "source_commit": "Source Commit",
+      "build_file": "Build File",
+      "public_ledger": "Public Ledger",
+      "transparency_log_entry": "Transparency log entry",
+      "view_more_details": "View more details",
+      "error_loading": "Failed to load provenance details"
+    },
     "keywords_title": "Keywords",
     "compatibility": "Compatibility",
     "card": {
@@ -610,7 +621,8 @@
     "provenance": {
       "verified": "verified",
       "verified_title": "Verified provenance",
-      "verified_via": "Verified: published via {provider}"
+      "verified_via": "Verified: published via {provider}",
+      "view_more_details": "View more details"
     },
     "jsr": {
       "title": "also available on JSR",
diff --git a/lunaria/files/en-US.json b/lunaria/files/en-US.json
@@ -210,6 +210,17 @@
       "view_on_github": "View on GitHub",
       "toc_title": "Outline"
     },
+    "provenance_section": {
+      "title": "Provenance",
+      "built_and_signed_on": "Built and signed on {provider}",
+      "view_build_summary": "View build summary",
+      "source_commit": "Source Commit",
+      "build_file": "Build File",
+      "public_ledger": "Public Ledger",
+      "transparency_log_entry": "Transparency log entry",
+      "view_more_details": "View more details",
+      "error_loading": "Failed to load provenance details"
+    },
     "keywords_title": "Keywords",
     "compatibility": "Compatibility",
     "card": {
@@ -610,7 +621,8 @@
     "provenance": {
       "verified": "verified",
       "verified_title": "Verified provenance",
-      "verified_via": "Verified: published via {provider}"
+      "verified_via": "Verified: published via {provider}",
+      "view_more_details": "View more details"
     },
     "jsr": {
       "title": "also available on JSR",
diff --git a/nuxt.config.ts b/nuxt.config.ts
@@ -102,6 +102,7 @@ export default defineNuxtConfig({
     '/package-docs/:scope/:pkg/v/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
     '/api/registry/docs/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
     '/api/registry/file/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
+    '/api/registry/provenance/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
     '/api/registry/files/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
     '/_avatar/**': {
       isr: 3600,
diff --git a/server/api/registry/provenance/[...pkg].get.ts b/server/api/registry/provenance/[...pkg].get.ts
@@ -0,0 +1,69 @@
+import * as v from 'valibot'
+import { PackageRouteParamsSchema } from '#shared/schemas/package'
+import type { NpmVersionDist } from '#shared/types'
+import { CACHE_MAX_AGE_ONE_HOUR, ERROR_PROVENANCE_FETCH_FAILED } from '#shared/utils/constants'
+import {
+  parseAttestationToProvenanceDetails,
+  type NpmAttestationsResponse,
+} from '#server/utils/provenance'
+
+/**
+ * GET /api/registry/provenance/:name/v/:version
+ *
+ * Returns parsed provenance details for a package version (build summary, source commit, build file, public ledger).
+ * Version is required. Returns null when the version has no attestations or parsing fails.
+ */
+export default defineCachedEventHandler(
+  async event => {
+    const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
+
+    const { rawPackageName, rawVersion } = parsePackageParams(pkgParamSegments)
+
+    if (!rawVersion) {
+      throw createError({
+        statusCode: 400,
+        message: 'Version is required for provenance.',
+      })
+    }
+
+    try {
+      const parsed = v.parse(PackageRouteParamsSchema, {
+        packageName: rawPackageName,
+        version: rawVersion,
+      }) as { packageName: string; version: string }
+      const { packageName, version } = parsed
+
+      const packument = await fetchNpmPackage(packageName)
+      const versionData = packument.versions[version]
+      if (!versionData) {
+        throw createError({
+          statusCode: 404,
+          message: `Version ${version} not found for package ${packageName}.`,
+        })
+      }
+      const dist = versionData.dist as NpmVersionDist | undefined
+      const attestationsUrl = dist?.attestations?.url
+
+      if (!attestationsUrl) {
+        return null
+      }
+
+      const response = await $fetch<NpmAttestationsResponse>(attestationsUrl)
+      const details = parseAttestationToProvenanceDetails(response)
+      return details
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: ERROR_PROVENANCE_FETCH_FAILED,
+      })
+    }
+  },
+  {
+    maxAge: CACHE_MAX_AGE_ONE_HOUR,
+    swr: true,
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      return `provenance:v1:${pkg.replace(/\/+$/, '').trim()}`
+    },
+  },
+)
diff --git a/server/utils/provenance.ts b/server/utils/provenance.ts
diff --git a/shared/types/npm-registry.ts b/shared/types/npm-registry.ts
diff --git a/shared/utils/constants.ts b/shared/utils/constants.ts
diff --git a/test/nuxt/a11y.spec.ts b/test/nuxt/a11y.spec.ts
