# Verifier Architecture

> Standalone, offline-first CLI tool for cryptographic verification of evidence bundles.

## Overview

Verifier is a single-project, self-contained .NET CLI application published as a trimmed, single-file binary for multiple platforms. It takes an evidence bundle (a gzipped tar archive) as input, extracts it, and runs a six-stage verification pipeline that validates the manifest, signatures, timestamps, digests, and SBOM/DSSE pair integrity. The tool requires no network access, no database, and no running Stella Ops services.

## Components

```
src/Verifier/
  Verifier/                          # Single project (self-contained CLI)
    Program.cs                       # Entry point and CLI argument parsing
    BundleExtractor.cs               # gzip+tar extraction
    ManifestLoader.cs                # manifest.json parsing and validation
    SignatureVerifier.cs             # DSSE signature verification
    TimestampVerifier.cs             # RFC 3161 timestamp verification
    DigestVerifier.cs                # SHA-256 digest checking
    PairVerifier.cs                  # SBOM + DSSE pair matching
    TrustProfile.cs                  # Trusted key whitelisting
    OutputFormatter.cs               # Text / JSON / Markdown output
```

## Bundle Format

The input evidence bundle is a gzipped tar archive with the following structure:

```
bundle.tar.gz
  manifest.json                      # Bundle manifest (pairs, metadata, digests)
  manifest.json.sig                  # DSSE signature over the manifest
  pairs/
    {pairId}/
      sbom.spdx.json                 # SPDX SBOM document
      delta-sig.dsse.json            # DSSE envelope for the delta signature
    {pairId}/
      ...
  timestamps/                        # Optional RFC 3161 timestamps
    *.tsr                            # Timestamp request files
    *.tst                            # Timestamp token files
```

## Verification Pipeline

The verification pipeline executes six stages sequentially. Each stage must pass before the next begins:

| Stage | Name                     | Description                                                  |
|-------|--------------------------|--------------------------------------------------------------|
| 1     | Extract bundle           | Decompress gzip, unpack tar to temporary directory           |
| 2     | Load manifest            | Parse `manifest.json`, validate required fields and structure |
| 3     | Signature verification   | Verify `manifest.json.sig` DSSE signature against trusted key list |
| 4     | Timestamp verification   | Validate RFC 3161 timestamp tokens (`.tsr`/`.tst`) if present |
| 5     | Digest verification      | Recompute SHA-256 digests for all referenced files, compare to manifest |
| 6     | Pair verification        | Verify each SBOM + DSSE pair matches and is internally consistent |

## Data Flow

1. Operator provides a bundle file path and optional trust profile (key whitelist) via CLI arguments.
2. Verifier extracts the bundle to a temporary directory.
3. The manifest is loaded and parsed.
4. The DSSE signature on the manifest is verified against the trust profile's allowed public keys.
5. Any RFC 3161 timestamps are validated for structural and cryptographic correctness.
6. SHA-256 digests are recomputed for every file referenced in the manifest and compared to the declared values.
7. Each SBOM/DSSE pair is validated for internal consistency.
8. A verification report is written to stdout in the requested format (text, JSON, or markdown).

## Database Schema

Not applicable. Verifier is a standalone CLI tool with no persistent storage.

## Endpoints

Not applicable. Verifier is a CLI tool with no HTTP endpoints.

## Cross-Platform Targets

| Runtime Identifier | Platform                          |
|-------------------|-----------------------------------|
| `win-x64`          | Windows x64                       |
| `linux-x64`        | Linux x64 (glibc)                 |
| `linux-musl-x64`   | Linux x64 (musl/Alpine)           |
| `osx-x64`          | macOS x64 (Intel)                 |
| `osx-arm64`        | macOS ARM64 (Apple Silicon)       |

All targets produce a single-file, self-contained, trimmed binary with no external runtime dependencies.

## Dependencies

| Library                             | Purpose                                |
|------------------------------------|----------------------------------------|
| System.CommandLine                  | CLI argument parsing and help generation |
| System.Security.Cryptography        | SHA-256, RSA/ECDSA signature verification |
| System.Formats.Tar                  | Tar archive extraction                 |
| System.IO.Compression               | Gzip decompression                     |
| System.Text.Json                    | JSON parsing for manifests and DSSE envelopes |
| BouncyCastle (optional)             | Extended algorithm support (SM2, EdDSA) |

## Security Considerations

- **Air-gap first**: Verifier requires no network access. All verification is performed locally using only the bundle contents and the trust profile.
- **No key export or generation**: Verifier only reads public keys from the trust profile; it never generates or exports key material.
- **Trust profiles**: Operators define which public keys are trusted for signature verification via a key whitelist file. Bundles signed by unknown keys are rejected.
- **Deterministic output**: Given the same bundle and trust profile, Verifier produces identical verification results, supporting audit reproducibility.
- **Temporary file cleanup**: Extracted bundle contents are written to a temporary directory and cleaned up after verification completes, minimizing residual data on disk.
- **No code execution**: Verifier does not execute any code or scripts from within the bundle. It only reads and verifies data.