@tinfoilsh/verifier

@tinfoilsh/verifier

Browser-compatible TypeScript library for verifying AMD SEV-SNP attestation reports and Sigstore code provenance.

When to Use This Package

Most users should use the main tinfoil package instead. It includes this verifier and handles verification automatically.

Use @tinfoilsh/verifier directly when you need:

• Standalone verification — Verify enclaves without making API requests
• Custom verification flows — Verify before creating clients, or verify arbitrary enclaves
• Lighter dependency — If you only need verification, not the full SDK
• Audit/compliance tooling — Build tools that verify enclaves independently

Installation

npm install @tinfoilsh/verifier

Quick Start

import { Verifier } from '@tinfoilsh/verifier';

const verifier = new Verifier({
  serverURL: 'https://enclave.example.com',
  configRepo: 'tinfoilsh/confidential-model-router',
});
const attestation = await verifier.verify();

console.log(attestation.measurement);
console.log(attestation.tlsPublicKeyFingerprint);
console.log(attestation.hpkePublicKey);

Verifying a Pre-Fetched Bundle

If you already have a complete attestation bundle (for example, fetched via the tinfoil SDK's fetchAttestationBundle() helper), you can verify it directly:

import { Verifier } from '@tinfoilsh/verifier';
import type { AttestationBundle } from '@tinfoilsh/verifier';

const verifier = new Verifier({
  configRepo: 'tinfoilsh/confidential-model-router',
});

const bundle: AttestationBundle = /* fetch bundle from your source */;
await verifier.verifyBundle(bundle);

const doc = verifier.getVerificationDocument();
console.log(doc.securityVerified);

Error Handling

For callers that want structured error handling, these error classes are part of the public API:

• ConfigurationError — client misconfigured (e.g., missing required options)
• FetchError — network or HTTP errors when fetching attestation material
• AttestationError — attestation verification failed (parsing, signatures, certificates, measurement mismatch, policy violation)

Inspecting Verification Results

The verification document contains detailed information about each step:

const doc = verifier.getVerificationDocument();

// Overall result
console.log(doc.securityVerified); // true if all checks passed

// Individual steps
console.log(doc.steps.fetchDigest);       // Fetched release digest from GitHub
console.log(doc.steps.verifyCode);        // Verified code via Sigstore
console.log(doc.steps.verifyEnclave);     // Verified AMD SEV-SNP attestation
console.log(doc.steps.compareMeasurements); // Compared code vs enclave measurements

// Measurements
console.log(doc.codeFingerprint);     // Expected measurement from signed release
console.log(doc.enclaveFingerprint);  // Actual measurement from enclave
console.log(doc.releaseTag);          // GitHub release selected for verification
console.log(doc.verifier);            // Verifier package identity and version
console.log(doc.verifiedAt);           // Local completion time, not evidence freshness

Using Your Own Transport

Verifier does not require callers to use the main SDK transport. After verification, tlsPublicKeyFingerprint contains the attested SHA-256 SPKI fingerprint and can be passed to a separate HTTP implementation:

const attestation = await verifier.verify();
const expectedSpkiFingerprint = attestation.tlsPublicKeyFingerprint;

The custom transport must compare that value with the live peer certificate's SPKI on every new TLS connection and must still perform normal hostname and certificate validation. Merely obtaining the fingerprint does not pin the connection.

What Gets Verified

The Verifier performs a multi-step verification:

1. Fetch Release Digest — Gets the expected code digest from the signed GitHub release
2. Verify Code Provenance — Uses Sigstore (Fulcio + Rekor) to verify the release signature
3. Verify Enclave Attestation — Validates the AMD SEV-SNP attestation report and VCEK certificate chain
4. Compare Measurements — Ensures the enclave is running the exact code from the signed release

Features

• AMD SEV-SNP attestation verification (VCEK certificate chain validation)
• Sigstore code provenance verification (Fulcio + Rekor)
• TUF-based trusted root updates
• Works in Node.js and browsers (uses Web Crypto API)

GitHub Proxy Dependency

This package fetches GitHub release metadata and attestation bundles via Tinfoil-hosted GitHub proxy endpoints (to avoid rate-limits/CORS issues). If your environment cannot reach these endpoints, verification that depends on GitHub release attestations will fail.

Relationship to tinfoil Package

The main tinfoil package includes this verifier and uses it automatically:

// tinfoil package — verification happens automatically
import { TinfoilAI } from 'tinfoil';
const client = new TinfoilAI({ apiKey: 'key' });
// Verification runs when you make your first request

// You can also access the verification document
const doc = await client.getVerificationDocument();

Use @tinfoilsh/verifier directly only if you have specific needs listed in "When to Use This Package" above.

Learn More

• How It Works — Confidential computing overview
• Verifiability — How attestation proves security
• Attestation Architecture — Technical deep-dive
• Overview of Verification — Verification process

Development

npm run build
npm test
npm run test:browser