Project node-addon-slsaCopy item path

node-addon-slsa

Verifies that an npm package and its prebuilt native addon binary were produced by the same GitHub Actions workflow run. Uses sigstore for npm provenance and the GitHub Attestations API for binary verification. Aborts npm install with a SECURITY error if any check fails.

Threat model

This tool trusts two infrastructure providers: GitHub Actions (build environment and attestation authority) and the sigstore public-good instance (Fulcio CA, Rekor transparency log). If either is compromised, verification may pass for malicious artifacts.

Protected

Threat	Mitigation
Tampered npm package	sigstore provenance verification
Tampered GitHub release	GitHub Attestations API + sigstore
Mismatched artifacts	Same workflow run check via URI
Man-in-the-middle on download	SHA-256 hash verified against signed attestation
Path traversal via addon.path	Resolved path must stay within package directory

Not protected

• Compromised CI workflow — if the workflow itself is malicious, all attestations will be valid for malicious code. This tool verifies provenance, not intent.
• Compromised maintainer account — an attacker with write access to the repository can modify the workflow and produce legitimately attested builds.
• Dependency confusion — the tool verifies a single package, not its transitive dependency tree.
• Version 0.0.0 — all verification is skipped, by design, for local development and CI testing. Never publish version 0.0.0 to npm.

Setup

1. Configure package.json

{
  "name": "my-native-addon",
  "version": "1.0.0",
  "repository": {
    "url": "git+https://github.com/owner/repo.git"
  },
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./package.json": "./package.json"
  },
  "addon": {
    "path": "./dist/my_addon.node",
    "url": "https://github.com/owner/repo/releases/download/v{version}/my_addon-v{version}-{platform}-{arch}.node.gz"
  },
  "scripts": {
    "postinstall": "slsa wget",
    "pack-addon": "slsa pack"
  },
  "dependencies": {
    "node-addon-slsa": "0.6.2"
  }
}
Copy

• addon.path — where the native addon is installed, relative to the package root
• addon.url — download URL template; supports {version}, {platform}, {arch} placeholders
• postinstall — runs slsa wget on npm install: downloads the binary, verifies provenance, installs it
• pack-addon — runs slsa pack in CI: gzip-compresses the binary before uploading to a release
• exports["./package.json"] — required for loading the addon at runtime (see Loading the addon)

2. CI setup

jobs:
  build-addon:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-24.04, macos-15, windows-2025]
    runs-on: ${{ matrix.os }}
    permissions:
      contents: write # release upload
      id-token: write # OIDC token for sigstore
      attestations: write # build provenance
    steps:
      - uses: actions/checkout@v6
      # ... set up toolchain, build native addon ...
      - name: Compress binary for release
        run: npx slsa pack
      - name: Attest binary provenance
        uses: actions/attest-build-provenance@v4
        with:
          subject-path: dist/my_addon-v*.node.gz
      - name: Upload binary to release
        uses: softprops/action-gh-release@v2
        with:
          files: dist/my_addon-v*.node.gz

  publish:
    needs: build-addon
    runs-on: ubuntu-latest
    permissions:
      contents: read # to fetch code
      id-token: write # npm provenance via OIDC
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish --provenance --access public
Copy

Each matrix runner produces a platform-specific binary (e.g. my_addon-v1.0.0-linux-x64.node.gz). The {platform} and {arch} placeholders in addon.url resolve to process.platform and process.arch at install time, so each user downloads the correct binary for their OS.

How verification works

slsa wget runs on npm install:

1. Verifies npm package provenance via sigstore
2. Extracts the Run Invocation URI from the Fulcio certificate
3. Downloads the compressed binary from the GitHub release, computing a SHA-256 hash of the compressed bytes and decompressing into a temp file
4. Verifies the binary's GitHub attestation matches the same workflow run
5. Moves the verified binary to its final location

On failure, the temp file is removed and installation aborts.

API reference

CLI

Command / Option	Purpose
slsa pack	Gzip-compress the native addon for release
slsa wget	Download, verify, and install the native addon
--help, -h	Show usage information

Environment variables

Variable	Purpose
GITHUB_TOKEN	GitHub API auth (required for private repos, increases rate limits)
SLSA_DEBUG=1	Debug logging to stderr

Programmatic API

Types

Type	Constructor	Purpose
GitHubRepo	githubRepo(value)	GitHub owner/repo slug
SemVerString	semVerString(value)	Strict semver (no v prefix)
Sha256Hex	sha256Hex(value)	Lowercase hex-encoded SHA-256 (64 chars)
RunInvocationURI	runInvocationURI(value)	GitHub Actions run invocation URL

Constructors validate at runtime and throw TypeError on invalid input.

Functions

import {
  verifyPackageProvenance,
  verifyAddonProvenance,
  isProvenanceError,
  sha256Hex,
  semVerString,
  githubRepo,
} from "node-addon-slsa";
import type {
  PackageProvenance,
  RunInvocationURI,
  VerifyOptions,
} from "node-addon-slsa";

// Verify npm package provenance via sigstore.
// Returns { runInvocationURI, verifyAddon() }.
const provenance: PackageProvenance = await verifyPackageProvenance({
  packageName: "my-native-addon",
  version: semVerString("1.0.0"),
  repo: githubRepo("owner/repo"),
});

// With custom timeouts (e.g. behind a slow proxy):
const provenance2 = await verifyPackageProvenance({
  packageName: "my-native-addon",
  version: semVerString("1.0.0"),
  repo: githubRepo("owner/repo"),
  timeoutMs: 60_000,
  retryCount: 5,
});

// Verify the addon binary was produced by the same workflow run.
await provenance.verifyAddon({ sha256: sha256Hex(hexHash) });

// Standalone binary verification when you already have a URI.
await verifyAddonProvenance({
  sha256: sha256Hex(hexHash),
  runInvocationURI,
  repo: githubRepo("owner/repo"),
});
Copy

Error handling

• ProvenanceError — verification failed (tampered artifact, mismatched provenance). Do not retry.
• Error — transient issue (network timeout, GitHub API rate limit). Safe to retry.

Use isProvenanceError(err) in catch blocks to distinguish the two.

Non-security errors include a Set SLSA_DEBUG=1 for detailed diagnostics hint. When reporting issues, include the debug output.

Configuration

repository field

The repository field (or repository.url) determines the expected GitHub repository for attestation verification. Both CLI commands read it from package.json in the working directory. Only github.com URLs are supported (HTTPS, SSH, with or without .git suffix).

Loading the addon

import { createRequire } from "node:module";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";

import packageJson from "../package.json" with { type: "json" };

const require = createRequire(import.meta.url);
const root = join(dirname(fileURLToPath(import.meta.url)), "..");
const addon = require(join(root, packageJson.addon.path));
Copy

The "./package.json" export in your exports map is required for this JSON import to resolve under strict ESM exports.

Authentication

Public repositories work without authentication. Private repositories require GITHUB_TOKEN. Unauthenticated requests are limited to 60/hour by GitHub. Set GITHUB_TOKEN to increase:

export GITHUB_TOKEN="$(gh auth token)"
Copy

Requirements

• Node.js ^20.19.0 || >=22.12.0
• npm package published with --provenance
• Binary attested with actions/attest-build-provenance