Project node-addon-slsa

Type Aliases§

Source§

type BundleVerifier = Awaited<ReturnType<typeof createVerifier>>

Sigstore bundle verifier created by createVerifier() from the sigstore package.

Source§

type GitHubRepo = `${string}/${string}`

GitHub owner/repo slug.

Source§

type RunInvocationURI = string & { "[___runInvocationURIBrand]": true }

Source§

type SemVerString = `${number}.${number}.${number}${string}`

Strict semver string (no v prefix): major.minor.patch[-pre][+build]. The template literal type is intentionally wider than the runtime check in semVerString because TypeScript cannot express the full regex.

Source§

type Sha256Hex = string & { "[___sha256HexBrand]": true }

Functions§

Source§

githubRepo(value: string): `${string}/${string}`

Validate and brand a string as a GitHubRepo.

throws

if the input is not in owner/repo format.

Source§

isProvenanceError(err: unknown): err is ProvenanceError

Type guard for ProvenanceError. Use in catch blocks to distinguish security failures from transient errors.

Source§

runInvocationURI(value: string): RunInvocationURI

Validate and brand a string as a RunInvocationURI.

throws

if the input is not a valid GitHub Actions run invocation URL.

Source§

semVerString(value: string): `${number}.${number}.${number}${string}`

Validate and brand a string as a SemVerString.

throws

if the input does not match major.minor.patch[-pre][+build].

Source§

sha256Hex(value: string): Sha256Hex

Validate and brand a string as a Sha256Hex.

throws

if the input is not exactly 64 lowercase hex characters.

Source§

verifyAddonProvenance(
    options: {
        repo: `${string}/${string}`;
        runInvocationURI: RunInvocationURI;
        sha256: Sha256Hex;
    } & VerifyOptions,
): Promise<void>

Verify addon binary provenance via the GitHub Attestations API. Confirms the artifact was attested in the expected workflow run and source repository.

Typically called via verifyAddon. Use directly when you already have a RunInvocationURI.

throws

ProvenanceError if no attestation matches the expected workflow run, or all attestations fail cryptographic verification.

throws

Error on transient failures (network timeout, API rate limit) — safe to retry.

example
import {
  verifyAddonProvenance,
  sha256Hex,
  githubRepo,
  runInvocationURI,
} from "node-addon-slsa";

await verifyAddonProvenance({
  sha256: sha256Hex("a".repeat(64)),
  runInvocationURI: runInvocationURI(
    "https://github.com/owner/repo/actions/runs/123/attempts/1",
  ),
  repo: githubRepo("owner/repo"),
});
Source§

verifyPackageProvenance(
    options: {
        packageName: string;
        repo: `${string}/${string}`;
        version: `${number}.${number}.${number}${string}`;
    } & VerifyOptions,
): Promise<PackageProvenance>

Verify npm package provenance via sigstore attestations. Checks the certificate chain, issuer identity, and source repository. Returns a PackageProvenance handle for addon verification.

throws

ProvenanceError if the package has no SLSA provenance attestation, the certificate is invalid, or the source repo does not match.

throws

Error on transient failures (network timeout, API rate limit) — safe to retry.

example
import {
  verifyPackageProvenance,
  semVerString,
  githubRepo,
  sha256Hex,
} from "node-addon-slsa";

const provenance = await verifyPackageProvenance({
  packageName: "my-native-addon",
  version: semVerString("1.0.0"),
  repo: githubRepo("owner/repo"),
});

// Verify the addon binary was produced by the same workflow run.
const addonHash = sha256Hex("a".repeat(64)); // SHA-256 of the binary
await provenance.verifyAddon({ sha256: addonHash });

Classes§

ProvenanceError

Thrown when provenance verification detects a security issue. The message is prefixed with SECURITY: and includes remediation advice.

Interfaces§

FetchOptions

Options controlling HTTP fetch behavior (timeouts, retries, cancellation).

PackageProvenance

Returned by verifyPackageProvenance after npm provenance checks pass.

VerifyOptions

Verification options: extends FetchOptions with attestation-specific limits.