Attestor Offline Verification Guide

Audience: Attestor operators, AirGap owners, CI/Release engineers
Purpose: Explain how to verify attestations and timestamp evidence in fully offline environments.

Console capability status

The Console does not currently have a portable-bundle upload verification API or a verification-history API. Its Offline Verification Center therefore fails closed: selecting a local file does not upload, parse, or verify it, and the page does not infer a verdict, evidence chain, history row, or exportable report in the browser.

Use the supported stella bundle verify CLI workflow below for actual verification. A future Console verifier must call a contracted backend that validates bundle structure, content digests, signatures, trust roots, revocation evidence, and replay inputs before it can render a result.

1. Offline Inputs

Offline verification expects all evidence to be bundled locally:

DSSE envelopes + certificate chains.
Rekor inclusion proofs + a pinned checkpoint.
RFC3161 timestamp evidence with bundled TSA chain and revocation data:
- tsa/chain/ (PEM certificates, leaf -> root)
- tsa/ocsp/ (stapled OCSP responses)
- tsa/crl/ (CRL snapshots when OCSP is unavailable)

2. Bundle Layout Expectations

Minimum paths for timestamp verification:

manifest.json with timestamps[] entries.
tsa/chain/*.pem for each RFC3161 timestamp.
tsa/ocsp/*.der or tsa/crl/*.crl (revocation evidence).

3. CLI Workflow (Offline)

Use the bundle verification flow aligned to domain operations:

stella bundle verify --bundle /path/to/bundle --offline --trust-root /path/to/tsa-root.pem --rekor-checkpoint /path/to/checkpoint.json
stella bundle verify --bundle /path/to/bundle --offline --signer /path/to/report-key.pem --signer-cert /path/to/report-cert.pem

Notes:

Offline mode fails closed when revocation evidence is missing or invalid.
Trust roots must be provided locally; no network fetches are allowed.
When --signer is set, a DSSE report is written to out/verification.report.json.
Signed report metadata includes verifier.algo, verifier.cert, signed_at.

4. Verification Behavior

TSA chain is validated against the provided trust roots.
Revocation evidence is verified using bundled OCSP/CRL data.
Rekor proofs are verified against the pinned checkpoint when provided.

5. Two-Tier Bundle Modes

Sprint: SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-04, 040-06)

Evidence bundles are exported in one of two modes:

5.1 Light Mode (Default)

Contains only metadata and attestation envelopes. Binary blobs referenced in largeBlobs[] are not embedded.

bundle/
├── manifest.json        # Bundle manifest with exportMode: "light"
├── attestations/
│   └── delta-sig.dsse.json
└── tsa/
    ├── chain/
    └── ocsp/

Advantages: Small size, fast transfer. Limitation: Blob replay requires a source (--blob-source) or network access.

5.2 Full Mode (`--full`)

Includes all binary blobs referenced by attestations, enabling fully self-contained offline verification.

bundle/
├── manifest.json        # Bundle manifest with exportMode: "full"
├── attestations/
│   └── delta-sig.dsse.json
├── blobs/
│   ├── sha256-<hex1>    # Binary patch blob
│   └── sha256-<hex2>    # SBOM fragment blob
└── tsa/
    ├── chain/
    └── ocsp/

Advantages: Fully self-contained, no network needed for replay. Limitation: Larger bundle size.

6. Blob Replay Verification

When --replay is specified, the verifier fetches and checks binary blobs referenced in attestation predicates:

# Full bundle: blobs are embedded, no external source needed
stella bundle verify --bundle full-bundle/ --offline --replay

# Light bundle: provide local blob source
stella bundle verify --bundle light-bundle/ --replay --blob-source /path/to/blobs/

# Light bundle: fetch from registry (requires network)
stella bundle verify --bundle light-bundle/ --replay --blob-source https://registry.example.com/blobs/

6.1 Replay Steps

Parse attestation envelopes in attestations/ directory
Decode DSSE payloads and extract largeBlobs[] references
For each blob reference:
- Resolve content from embedded blobs, local source, or registry
- Compute digest using declared algorithm (sha256/sha384/sha512)
- Compare computed digest against declared digest
Report pass/fail for each blob

6.2 Offline Constraints

In --offline mode, registry blob fetches are blocked
Light bundles in offline mode require --blob-source pointing to a local directory
Full bundles work in offline mode without additional configuration

7. Deterministic Error Triage Guidance

Use stable error classes to route remediation:

signature_untrusted: key not present in authority roster; refresh roster snapshot and retry.
signature_revoked: signing key revoked; rotate signer and regenerate attestation.
tenant_mismatch: authenticated tenant differs from verdict owner; re-run with correct principal context.
verdict_not_found: no verdict exists for requested hash; verify hash source and storage replication.

Operator rule:

Do not treat these as transient network faults unless the error class is explicitly retryable.