Minimal Browser-Compatible Implementation of a Sigstore Verifier

A minimal TypeScript implementation of Sigstore verification, optimized for browser compatibility.

This is a browser-compatible alternative to sigstore-js that focuses on verification functionality needed for secure software updates in browser environments.

Caution

This library has not received an independent security audit. Maintenance is performed by volunteers, and the project is not officially supported or endorsed by the Freedom of the Press Foundation.

Features

• Full Sigstore Verification: Complete verification of Sigstore bundles including certificate chains, transparency logs, and timestamps
• Browser-First: Designed for web browsers using the Web Crypto API
• TUF Integration: Secure trusted root updates via The Update Framework
• Policy Verification: Flexible identity and claim verification adapted from sigstore-python
• Multiple Bundle Formats: Supports Sigstore bundle versions 0.1, 0.2, and 0.3
• Multiple Key Types: RSA, ECDSA, and Ed25519 signature verification via Web Crypto API
• Minimal Dependencies: Only depends on @freedomofpress/crypto-browser, @freedomofpress/tuf-browser, and @noble/curves

Installation

npm install @freedomofpress/sigstore-browser

Usage

Basic Verification

import { SigstoreVerifier } from '@freedomofpress/sigstore-browser';

// Initialize the verifier
const verifier = new SigstoreVerifier();

// Load the Sigstore trusted root via TUF (recommended)
await verifier.loadSigstoreRootWithTUF();

// Or load a trusted root directly
// await verifier.loadSigstoreRoot(trustedRootJson);

// Verify an artifact
const bundle = JSON.parse(bundleJsonString);
const artifactData = new Uint8Array(/* artifact bytes */);

const verified = await verifier.verifyArtifact(
  '[email protected]',           // Expected signer identity (SAN)
  'https://accounts.google.com',    // Expected OIDC issuer
  bundle,
  artifactData
);

Verification Options

const verifier = new SigstoreVerifier({
  tlogThreshold: 1,   // Minimum transparency log entries required (default: 1)
  ctlogThreshold: 1,  // Minimum SCTs required (default: 1)
  tsaThreshold: 0,    // Minimum TSA timestamps required (default: 0)
});

What Gets Verified

The verifyArtifact method performs the following checks:

1. Identity Verification: Certificate SAN matches the expected identity
2. Issuer Verification: Certificate OIDC issuer matches the expected issuer
3. Certificate Chain: Leaf certificate chains to a trusted Fulcio CA
4. SCT Verification: Signed Certificate Timestamps from CT logs
5. Inclusion Promise/Proof: Rekor transparency log inclusion
6. Merkle Tree Verification: Inclusion proof validation (for v0.2+ bundles)
7. TLog Body Verification: Entry body matches bundle content
8. TSA Timestamp Verification: RFC 3161 timestamp verification (if configured)
9. Signature Verification: Artifact signature using certificate's public key

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests (browser environment via Playwright)
npm test

# Lint and format
npm run lint

Related Projects

This library is part of a family of browser-compatible security libraries:

• @freedomofpress/tuf-browser - Browser-compatible TUF client
• @freedomofpress/crypto-browser - Browser-compatible cryptographic primitives

License

Apache License 2.0 - see LICENSE file for details. Portions of this package incorporate code from sigstore-js and sigstore-python.

Acknowledgments

This project is based on the Sigstore specification and adapted from:

• sigstore-js
• sigstore-go
• sigstore-python