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

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Robin <[e-mail]>
Co-authored-by: Okinea Dev <[e-mail]>
Co-authored-by: Daniel Roe <[e-mail]>

README.md

···
 - **Fast search** – quick package search with instant results
 - **Package details** – READMEs, versions, dependencies, and metadata
 - **Code viewer** – browse package source code with syntax highlighting and permalink to specific lines
-- **Provenance indicators** – verified build badges for packages with npm provenance
+- **Provenance indicators** – verified build badges and provenance section below the README
 - **Multi-provider repository support** – stars/forks from GitHub, GitLab, Bitbucket, Codeberg, Gitee, Sourcehut, Forgejo, Gitea, Radicle, and Tangled
 - **JSR availability** – see if scoped packages are also available on JSR
 - **Package badges** – module format (ESM/CJS/dual), TypeScript types (with `@types/*` links), and engine constraints

app/components/PackageProvenanceSection.vue

···
+<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>

app/pages/package/[...package].vue

···
 import type {
   NpmVersionDist,
   PackumentVersion,
+  ProvenanceDetails,
   ReadmeResponse,
   SkillsListResponse,
 } from '#shared/types'
···
   packageName,
   () => 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(() => {
···
             >
             <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"
···
             >{{ $t('package.readme.view_on_github') }}</a
           >
         </p>
+
+        <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

i18n/locales/en.json

···
       "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": {
···
     "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",

lunaria/files/en-GB.json

···
       "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": {
···
     "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",

lunaria/files/en-US.json

···
       "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": {
···
     "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",

nuxt.config.ts

···
     '/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,

server/api/registry/provenance/[...pkg].get.ts

···
+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()}`
+    },
+  },
+)

server/utils/provenance.ts

···
+import type { ProvenanceDetails } from '#shared/types'
+
+const SLSA_PROVENANCE_V1 = 'https://slsa.dev/provenance/v1'
+const SLSA_PROVENANCE_V0_2 = 'https://slsa.dev/provenance/v0.2'
+
+const PROVIDER_IDS: Record<string, { provider: string; providerLabel: string }> = {
+  'https://github.com/actions/runner/github-hosted': {
+    provider: 'github',
+    providerLabel: 'GitHub Actions',
+  },
+  'https://github.com/actions/runner': { provider: 'github', providerLabel: 'GitHub Actions' },
+}
+
+/** GitLab uses project-specific builder IDs: https://gitlab.com/<path>/-/runners/<id> */
+function getProviderInfo(builderId: string): { provider: string; providerLabel: string } {
+  const exact = PROVIDER_IDS[builderId]
+  if (exact) return exact
+  if (builderId.includes('gitlab.com') && builderId.includes('/runners/'))
+    return { provider: 'gitlab', providerLabel: 'GitLab CI' }
+  return { provider: 'unknown', providerLabel: builderId ? 'CI' : 'Unknown' }
+}
+
+const SIGSTORE_SEARCH_BASE = 'https://search.sigstore.dev'
+
+/** SLSA provenance v1 predicate; optional v0.2 fields for fallback */
+interface SlsaPredicate {
+  buildDefinition?: {
+    externalParameters?: {
+      workflow?: {
+        repository?: string
+        path?: string
+        ref?: string
+      }
+    }
+    resolvedDependencies?: Array<{
+      uri?: string
+      digest?: { gitCommit?: string }
+    }>
+  }
+  runDetails?: {
+    builder?: { id?: string }
+    metadata?: { invocationId?: string }
+  }
+  /** v0.2 */
+  builder?: { id?: string }
+  /** v0.2 */
+  metadata?: { buildInvocationId?: string }
+}
+
+interface AttestationItem {
+  predicateType?: string
+  bundle?: {
+    dsseEnvelope?: { payload?: string }
+    verificationMaterial?: {
+      tlogEntries?: Array<{ logIndex?: string }>
+    }
+  }
+}
+
+export interface NpmAttestationsResponse {
+  attestations?: AttestationItem[]
+}
+
+function decodePayload(
+  payloadBase64: string | undefined,
+): { predicateType?: string; predicate?: SlsaPredicate } | null {
+  if (!payloadBase64 || typeof payloadBase64 !== 'string') return null
+  try {
+    const decoded = Buffer.from(payloadBase64, 'base64').toString('utf-8')
+    return JSON.parse(decoded) as { predicateType?: string; predicate?: SlsaPredicate }
+  } catch {
+    return null
+  }
+}
+
+function repoUrlToCommitUrl(repository: string, sha: string): string {
+  const normalized = repository.replace(/\/$/, '').replace(/\.git$/, '')
+  if (normalized.includes('github.com')) return `${normalized}/commit/${sha}`
+  if (normalized.includes('gitlab.com')) return `${normalized}/-/commit/${sha}`
+  return `${normalized}/commit/${sha}`
+}
+
+function repoUrlToBlobUrl(repository: string, path: string, ref = 'main'): string {
+  const normalized = repository.replace(/\/$/, '').replace(/\.git$/, '')
+  if (normalized.includes('github.com')) return `${normalized}/blob/${ref}/${path}`
+  if (normalized.includes('gitlab.com')) return `${normalized}/-/blob/${ref}/${path}`
+  return `${normalized}/blob/${ref}/${path}`
+}
+
+/**
+ * Parse npm attestations API response into ProvenanceDetails.
+ * Prefers SLSA provenance v1; falls back to v0.2 for provider label and ledger only (no source commit/build file from v0.2).
+ * @public
+ */
+export function parseAttestationToProvenanceDetails(response: unknown): ProvenanceDetails | null {
+  const body = response as NpmAttestationsResponse
+  const list = body?.attestations
+  if (!Array.isArray(list)) return null
+
+  const slsaAttestation =
+    list.find(a => a.predicateType === SLSA_PROVENANCE_V1) ??
+    list.find(a => a.predicateType === SLSA_PROVENANCE_V0_2)
+  if (!slsaAttestation?.bundle?.dsseEnvelope) return null
+
+  const payload = decodePayload(slsaAttestation.bundle.dsseEnvelope.payload)
+  if (!payload?.predicate) return null
+
+  const pred = payload.predicate as SlsaPredicate
+  const builderId = pred.runDetails?.builder?.id ?? pred.builder?.id ?? ''
+  const providerInfo = getProviderInfo(builderId)
+
+  const workflow = pred.buildDefinition?.externalParameters?.workflow
+  const repo = workflow?.repository?.replace(/\/$/, '').replace(/\.git$/, '') ?? ''
+  const workflowPath = workflow?.path ?? ''
+  const ref = workflow?.ref?.replace(/^refs\/heads\//, '').replace(/^refs\/tags\//, '') ?? 'main'
+
+  const resolved = pred.buildDefinition?.resolvedDependencies?.[0]
+  const commitSha = resolved?.digest?.gitCommit ?? ''
+
+  const rawInvocationId =
+    pred.runDetails?.metadata?.invocationId ?? pred.metadata?.buildInvocationId
+  const buildSummaryUrl =
+    rawInvocationId?.startsWith('http://') || rawInvocationId?.startsWith('https://')
+      ? rawInvocationId
+      : undefined
+  const sourceCommitUrl = repo && commitSha ? repoUrlToCommitUrl(repo, commitSha) : undefined
+  const buildFileUrl = repo && workflowPath ? repoUrlToBlobUrl(repo, workflowPath, ref) : undefined
+
+  const tlogEntries = slsaAttestation.bundle.verificationMaterial?.tlogEntries
+  const logIndex = tlogEntries?.[0]?.logIndex
+  const publicLedgerUrl = logIndex ? `${SIGSTORE_SEARCH_BASE}/?logIndex=${logIndex}` : undefined
+
+  return {
+    provider: providerInfo.provider,
+    providerLabel: providerInfo.providerLabel,
+    buildSummaryUrl,
+    sourceCommitUrl,
+    sourceCommitSha: commitSha || undefined,
+    buildFileUrl,
+    buildFilePath: workflowPath || undefined,
+    publicLedgerUrl,
+  }
+}

shared/types/npm-registry.ts

···
 }
 
 /**
+ * Parsed provenance details for display (from attestation bundle SLSA predicate).
+ * Used by the provenance API and PackageProvenanceSection.
+ * @public
+ */
+export interface ProvenanceDetails {
+  /** Provider ID (e.g. "github", "gitlab") */
+  provider: string
+  /** Human-readable provider label (e.g. "GitHub Actions") */
+  providerLabel: string
+  /** Link to build run summary (e.g. GitHub Actions run URL) */
+  buildSummaryUrl?: string
+  /** Link to source commit in repository */
+  sourceCommitUrl?: string
+  /** Source commit SHA (short or full) */
+  sourceCommitSha?: string
+  /** Link to workflow/build config file in repo */
+  buildFileUrl?: string
+  /** Workflow path (e.g. ".github/workflows/release.yml") */
+  buildFilePath?: string
+  /** Link to transparency log entry (e.g. Sigstore search) */
+  publicLedgerUrl?: string
+}
+
+/**
  * Download counts API response
  * From https://api.npmjs.org/downloads/
  * Note: Not covered by @npm/types

shared/utils/constants.ts

···
 export const NPM_MISSING_README_SENTINEL = 'ERROR: No README data found!'
 export const ERROR_JSR_FETCH_FAILED = 'Failed to fetch package from JSR registry.'
 export const ERROR_NPM_FETCH_FAILED = 'Failed to fetch package from npm registry.'
+export const ERROR_PROVENANCE_FETCH_FAILED = 'Failed to fetch provenance.'
 export const UNSET_NUXT_SESSION_PASSWORD = 'NUXT_SESSION_PASSWORD not set'
 export const ERROR_SUGGESTIONS_FETCH_FAILED = 'Failed to fetch suggestions.'
 export const ERROR_SKILLS_FETCH_FAILED = 'Failed to fetch skills.'

test/nuxt/a11y.spec.ts

···
   HeaderSearchBox,
   LicenseDisplay,
   LoadingSpinner,
+  PackageProvenanceSection,
   OrgMembersPanel,
   OrgOperationsQueue,
   OrgTeamsPanel,
···
         props: {
           packageName: 'test-package',
           open: true,
+        },
+      })
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+  })
+
+  describe('PackageProvenanceSection', () => {
+    it('should have no accessibility violations with minimal details', async () => {
+      const component = await mountSuspended(PackageProvenanceSection, {
+        props: {
+          details: {
+            provider: 'github',
+            providerLabel: 'GitHub Actions',
+          },
+        },
+      })
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+
+    it('should have no accessibility violations with full details', async () => {
+      const component = await mountSuspended(PackageProvenanceSection, {
+        props: {
+          details: {
+            provider: 'github',
+            providerLabel: 'GitHub Actions',
+            buildSummaryUrl: 'https://github.com/owner/repo/actions/runs/123',
+            sourceCommitUrl: 'https://github.com/owner/repo/commit/abc123',
+            sourceCommitSha: 'abc123def456',
+            buildFileUrl: 'https://github.com/owner/repo/blob/main/.github/workflows/release.yml',
+            buildFilePath: '.github/workflows/release.yml',
+            publicLedgerUrl: 'https://search.sigstore.dev/example',
+          },
         },
       })
       const results = await runAxe(component)