# 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.

## 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:

```bash
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:

```bash
# 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

1. Parse attestation envelopes in `attestations/` directory
2. Decode DSSE payloads and extract `largeBlobs[]` references
3. 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
4. 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. References

- `docs/modules/attestor/guides/timestamp-policy.md`
- `docs/modules/attestor/airgap.md`
- `docs/modules/airgap/guides/staleness-and-time.md`