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.2 and 0.3 by default, and 0.1 when enabled
- 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,
false
);
Verification Options
const verifier = new SigstoreVerifier({
tlogThreshold: 1, // Minimum distinct log operators with a fully verified entry (default: 1)
ctlogThreshold: 1, // Minimum distinct CT log operators with a verified SCT (default: 1)
tsaThreshold: 0, // Minimum distinct TSA operators with a verified timestamp (default: 0)
bundleVersions: ["0.2", "0.3"], // Accepted bundle versions; add "0.1" for legacy bundles that carry only an inclusion promise (default: ["0.2", "0.3"])
});
Thresholds must be non-negative safe integers. Authorities without operator metadata can satisfy a threshold of one, but never add to the count of named operators. Thresholds above one require that many distinct, explicitly named operators.
When isDigestOnly is true, supply exactly 32 bytes containing the artifact's SHA-256 digest and construct the verifier with verifyDigest: verifySignatureOverDigest from @freedomofpress/crypto-browser/noble. Verifiers that always have the artifact can leave it out, and their bundles do not carry @noble/curves.
What Gets Verified
The verifyArtifact method performs the following checks:
- Bundle Validation: Structure, a 16 MiB aggregate encoded-data limit, bounded certificate chains and a supported media type
- Identity Verification: Certificate SAN matches the expected identity
- Issuer Verification: Certificate OIDC issuer matches the expected issuer
- Transparency Log: Every entry from a trusted Rekor log is verified (inclusion promise, Merkle proof, checkpoint, body and logged certificate); the threshold counts distinct log operators
- TSA Timestamp Verification: RFC 3161 timestamps (if present); the threshold counts distinct operators
- Observer Timestamps: At least one verified integrated time or TSA timestamp must anchor the signature
- Certificate Chain: Leaf certificate chains to a Fulcio CA that was trusted at every observer timestamp
- SCT Verification: Signed Certificate Timestamps from CT logs; the threshold counts distinct operators
- Signature Verification: Artifact signature using the certificate's public key
Use verifyArtifactPolicy(policy, bundle, artifactData, isDigestOnly) to enforce a custom VerificationPolicy, including the required identity and issuer checks.
Policies may be synchronous or asynchronous; asynchronous policies are awaited before verification continues.
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: