# Offline Verification Guide

This guide explains how to verify Stella Ops releases in air-gapped or offline environments without network access.

## Overview

The Release Evidence Pack is designed for complete offline verification. All cryptographic materials and proofs are bundled together, allowing verification without contacting external services.

## Verification Levels

Stella Ops supports multiple verification levels depending on your security requirements and available tools:

| Level | Tools Required | Network | Security Assurance |
|-------|---------------|---------|-------------------|
| 1 - Checksum | sha256sum | None | Artifact integrity |
| 2 - Signature | sha256sum + cosign | None | Authenticity + integrity |
| 3 - Provenance | sha256sum + cosign + jq | None | Build chain verification |
| 4 - Transparency | sha256sum + cosign + rekor-cli | Optional | Non-repudiation |

## Prerequisites

### Minimal (Level 1)

Standard Unix tools available on most systems:
- `sha256sum` or `shasum`
- `cat`, `diff`

### Full Verification (Levels 2-4)

Install cosign for signature verification:

```bash
# Linux
curl -sSL https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 -o cosign
chmod +x cosign
sudo mv cosign /usr/local/bin/

# macOS
brew install cosign

# Windows (PowerShell)
scoop install cosign
# or download from GitHub releases
```

## Quick Start

### Using the Verification Script

The evidence pack includes a self-contained verification script:

```bash
# Extract the evidence pack
tar -xzf stella-release-2.5.0-evidence-pack.tgz
cd stella-release-2.5.0-evidence-pack

# Run verification
./verify.sh

# For verbose output
./verify.sh --verbose

# For JSON output (CI integration)
./verify.sh --json
```

On Windows (PowerShell 7+):

```powershell
# Extract
Expand-Archive stella-release-2.5.0-evidence-pack.zip -DestinationPath .
cd stella-release-2.5.0-evidence-pack

# Run verification
./verify.ps1
```

### Exit Codes

The verification scripts return specific exit codes:

| Code | Meaning |
|------|---------|
| 0 | All verifications passed |
| 1 | Checksum verification failed |
| 2 | Signature verification failed |
| 3 | Provenance verification failed |
| 4 | Configuration error |

## Manual Verification Steps

### Level 1: Checksum Verification

Verify artifact integrity using SHA-256 checksums:

```bash
cd artifacts/
sha256sum -c ../checksums/SHA256SUMS
```

Expected output:
```
stella-2.5.0-linux-x64.tar.gz: OK
stella-2.5.0-linux-arm64.tar.gz: OK
stella-2.5.0-macos-universal.tar.gz: OK
stella-2.5.0-windows-x64.zip: OK
```

### Level 2: Signature Verification

Verify that artifacts were signed by Stella Ops:

```bash
# Verify the checksums file signature
cosign verify-blob \
  --key cosign.pub \
  --signature checksums/SHA256SUMS.sig \
  checksums/SHA256SUMS

# Verify individual artifact signatures
cosign verify-blob \
  --key cosign.pub \
  --signature artifacts/stella-2.5.0-linux-x64.tar.gz.sig \
  artifacts/stella-2.5.0-linux-x64.tar.gz
```

### Level 3: Provenance Verification

Verify SLSA provenance and inspect build details:

```bash
# Verify provenance signature
cosign verify-blob \
  --key cosign.pub \
  --signature provenance/stella-cli.slsa.intoto.jsonl.sig \
  provenance/stella-cli.slsa.intoto.jsonl

# Inspect provenance contents
cat provenance/stella-cli.slsa.intoto.jsonl | jq '.'

# Verify builder ID
BUILDER_ID=$(cat provenance/stella-cli.slsa.intoto.jsonl | \
  jq -r '.predicate.runDetails.builder.id')
echo "Builder: $BUILDER_ID"

# Verify it matches expected value
if [ "$BUILDER_ID" != "https://ci.stella-ops.org/builder/v1" ]; then
  echo "WARNING: Unexpected builder ID"
fi

# Check source commit
SOURCE_COMMIT=$(cat provenance/stella-cli.slsa.intoto.jsonl | \
  jq -r '.predicate.buildDefinition.resolvedDependencies[0].digest.gitCommit')
echo "Source commit: $SOURCE_COMMIT"
```

### Level 4: Transparency Log Verification

Verify Rekor inclusion proofs (requires network OR pre-fetched proofs):

#### With Network Access

```bash
rekor-cli verify \
  --artifact artifacts/stella-2.5.0-linux-x64.tar.gz \
  --signature artifacts/stella-2.5.0-linux-x64.tar.gz.sig \
  --public-key cosign.pub
```

#### Offline (using bundled proofs)

The evidence pack includes pre-fetched Rekor proofs in `rekor-proofs/`:

```bash
# List included proofs
cat rekor-proofs/inclusion-proofs.json | jq '.proofs'

# View a specific entry
cat rekor-proofs/log-entries/<uuid>.json | jq '.'
```

## SBOM Verification

Verify Software Bill of Materials:

```bash
# Verify SBOM signature
cosign verify-blob \
  --key cosign.pub \
  --signature sbom/stella-cli.cdx.json.sig \
  sbom/stella-cli.cdx.json

# Inspect SBOM contents
cat sbom/stella-cli.cdx.json | jq '.components | length'
```

## Reproducible Build Verification

Stella Ops releases are reproducible. You can rebuild from source and compare:

```bash
# Get the SOURCE_DATE_EPOCH from manifest
SOURCE_DATE_EPOCH=$(cat manifest.json | jq -r '.sourceDateEpoch')
SOURCE_COMMIT=$(cat manifest.json | jq -r '.sourceCommit')

# Clone and checkout
git clone https://git.stella-ops.org/stella-ops.org/git.stella-ops.org.git
cd git.stella-ops.org
git checkout $SOURCE_COMMIT

# Set reproducible timestamp
export SOURCE_DATE_EPOCH

# Build
make release

# Compare checksums
sha256sum dist/stella-* | diff - path/to/evidence-pack/checksums/SHA256SUMS
```

## Verification in CI/CD

For automated verification in pipelines:

```bash
# Download and verify in one step
curl -sSL https://releases.stella-ops.org/v2.5.0/evidence-pack.tgz | tar -xz
cd stella-release-2.5.0-evidence-pack

# Run verification with JSON output
./verify.sh --json > verification-result.json

# Check result
if [ "$(jq -r '.overall' verification-result.json)" != "PASS" ]; then
  echo "Verification failed!"
  jq '.steps[] | select(.status == "FAIL")' verification-result.json
  exit 1
fi
```

## Troubleshooting

### "cosign: command not found"

Install cosign from https://docs.sigstore.dev/cosign/installation/

### Checksum Mismatch

1. Re-download the artifact
2. Verify download completed (check file size)
3. Try a different mirror if available
4. Check for file corruption during transfer

### Signature Verification Failed

1. Ensure you're using `cosign.pub` from the evidence pack
2. Check the signature file hasn't been corrupted
3. Verify the artifact hasn't been modified

### "Error: no matching entries in transparency log"

This can happen if:
- The artifact was signed with key-based signing (not keyless)
- The Rekor server is unreachable
- Use the bundled proofs in `rekor-proofs/` instead

## Security Considerations

1. **Verify the evidence pack itself** - Download only from official sources
2. **Compare public key fingerprint** - Verify `cosign.pub` fingerprint matches published key
3. **Check provenance builder ID** - Ensure it matches expected CI system
4. **Review SBOM for known vulnerabilities** - Scan dependencies before deployment

## Related Documentation

- [Release Evidence Pack](./RELEASE_EVIDENCE_PACK.md)
- [SLSA Compliance](./SLSA_COMPLIANCE.md)
- [Reproducible Builds](./REPRODUCIBLE_BUILDS.md)