git.stella-ops.org/docs/modules/vexlens/operations/offline-kit.md

# VexLens Offline Kit

> Air-gapped deployment guide for VexLens consensus engine.

---

## 1) Overview

VexLens can operate in fully air-gapped environments with pre-loaded VEX data and issuer directories. This guide covers offline deployment, bundle creation, and operational procedures.

---

## 2) Offline Bundle Structure

### 2.1 Bundle Manifest

```json
{
  "bundleId": "vexlens-bundle-2025-12-06",
  "version": "1.0.0",
  "createdAt": "2025-12-06T00:00:00Z",
  "createdBy": "stellaops-export",
  "checksum": "sha256:abc123...",
  "components": {
    "issuerDirectory": {
      "file": "issuers.json",
      "checksum": "sha256:def456...",
      "count": 150
    },
    "vexStatements": {
      "file": "vex-statements.ndjson.gz",
      "checksum": "sha256:ghi789...",
      "count": 50000
    },
    "projectionSnapshots": {
      "file": "projections.ndjson.gz",
      "checksum": "sha256:jkl012...",
      "count": 25000
    },
    "trustConfiguration": {
      "file": "trust-config.yaml",
      "checksum": "sha256:mno345..."
    }
  },
  "compatibility": {
    "minVersion": "1.0.0",
    "maxVersion": "2.0.0"
  }
}
```

### 2.2 Bundle Contents

```
vexlens-bundle-2025-12-06/
├── manifest.json
├── issuers.json
├── vex-statements.ndjson.gz
├── projections.ndjson.gz
├── trust-config.yaml
├── checksums.sha256
└── signature.dsse
```

---

## 3) Creating Offline Bundles

### 3.1 Export Command

```bash
# Export from online VexLens instance
stellaops vexlens export \
  --output /export/vexlens-bundle-$(date +%Y-%m-%d) \
  --include-issuers \
  --include-statements \
  --include-projections \
  --compress \
  --sign
```

### 3.2 Selective Export

```bash
# Export only specific tenants
stellaops vexlens export \
  --output /export/tenant-bundle \
  --tenant tenant-001,tenant-002 \
  --since 2025-01-01 \
  --compress

# Export only critical vulnerabilities
stellaops vexlens export \
  --output /export/critical-bundle \
  --vulnerability-pattern "CVE-202[45]-*" \
  --status affected,under_investigation \
  --compress
```

### 3.3 Bundle Signing

```bash
# Sign bundle with organization key
stellaops vexlens export sign \
  --bundle /export/vexlens-bundle-2025-12-06 \
  --key /keys/export-signing-key.pem \
  --output /export/vexlens-bundle-2025-12-06/signature.dsse
```

---

## 4) Importing Offline Bundles

### 4.1 Verification

```bash
# Verify bundle integrity and signature
stellaops vexlens import verify \
  --bundle /import/vexlens-bundle-2025-12-06 \
  --trust-root /etc/vexlens/trust-roots.pem

# Output:
# Bundle ID: vexlens-bundle-2025-12-06
# Created: 2025-12-06T00:00:00Z
# Signature: VALID (signed by: StellaOps Export Service)
# Checksums: VALID (all 4 files verified)
# Compatibility: COMPATIBLE (current version: 1.1.0)
```

### 4.2 Import Command

```bash
# Import bundle to offline VexLens
stellaops vexlens import \
  --bundle /import/vexlens-bundle-2025-12-06 \
  --mode merge \
  --verify-signature

# Import modes:
# - merge: Add new data, keep existing
# - replace: Replace all data with bundle contents
# - incremental: Only add data newer than existing
```

### 4.3 Staged Import

For large bundles, use staged import:

```bash
# Stage 1: Import issuers
stellaops vexlens import \
  --bundle /import/bundle \
  --component issuer-directory \
  --dry-run

# Stage 2: Import statements
stellaops vexlens import \
  --bundle /import/bundle \
  --component vex-statements \
  --batch-size 1000

# Stage 3: Import projections
stellaops vexlens import \
  --bundle /import/bundle \
  --component projections \
  --batch-size 5000
```

---

## 5) Offline Configuration

### 5.1 Air-Gap Mode Settings

```yaml
vexlens:
  airgap:
    enabled: true
    # Disable external connectivity checks
    allowExternalConnections: false
    # Use file-based issuer directory
    issuerDirectorySource: file
    # Pre-compute consensus on import
    precomputeConsensus: true

  trust:
    # Stricter settings for air-gap
    allowUnsigned: false
    allowUnknownIssuers: false
    # Use local trust anchors
    trustAnchors: /etc/vexlens/trust-anchors.pem

  storage:
    # Local storage only
    mongodb:
      connectionString: mongodb://localhost:27017
    # No external cache
    redis:
      enabled: false

  time:
    # Use time anchor for staleness checks
    timeAnchorFile: /etc/vexlens/time-anchor.json
    # Maximum allowed drift
    maxDriftDays: 7
```

### 5.2 Time Anchor Configuration

For air-gapped environments, use time anchors:

```json
{
  "anchorTime": "2025-12-06T00:00:00Z",
  "signature": "base64...",
  "validUntil": "2025-12-13T00:00:00Z",
  "signedBy": "stellaops-time-authority"
}
```

---

## 6) Operational Procedures

### 6.1 Bundle Update Cycle

1. **Export** (Online environment):
   ```bash
   stellaops vexlens export --output /export/weekly-bundle --compress --sign
   ```

2. **Transfer** (Secure media):
   - Copy bundle to removable media
   - Verify checksums after transfer
   - Log transfer in custody chain

3. **Verify** (Offline environment):
   ```bash
   stellaops vexlens import verify --bundle /import/weekly-bundle
   ```

4. **Import** (Offline environment):
   ```bash
   stellaops vexlens import --bundle /import/weekly-bundle --mode incremental
   ```

5. **Recompute** (If needed):
   ```bash
   stellaops vexlens consensus recompute --since $(date -d '7 days ago' +%Y-%m-%d)
   ```

### 6.2 Staleness Monitoring

```bash
# Check data freshness
stellaops vexlens status --staleness

# Output:
# Data Freshness Report
# ---------------------
# Issuer Directory: 2 days old (OK)
# VEX Statements: 5 days old (OK)
# Projections: 5 days old (OK)
# Time Anchor: 2 days old (OK)
#
# Overall Status: FRESH
```

### 6.3 Audit Trail

All import operations are logged:

```bash
# View import history
stellaops vexlens import history --limit 10

# Output:
# Import History
# --------------
# 2025-12-06 08:00: vexlens-bundle-2025-12-06 (merge, 50000 statements)
# 2025-11-29 08:00: vexlens-bundle-2025-11-29 (incremental, 12000 statements)
# ...
```

---

## 7) Degraded Mode Operation

### 7.1 Degradation Matrix

| Component | Degradation | Impact | Mitigation |
|-----------|-------------|--------|------------|
| Stale VEX data | >7 days old | Lower accuracy | Schedule bundle update |
| Missing issuers | Unknown issuer | Lower trust scores | Add issuer to directory |
| No projections | Cold start | Slower first queries | Pre-compute on import |
| Time drift | >24 hours | Staleness warnings | Update time anchor |

### 7.2 Emergency Recovery

If bundle import fails:

```bash
# Check bundle integrity
stellaops vexlens import verify --bundle /import/bundle --verbose

# Attempt partial import
stellaops vexlens import --bundle /import/bundle --skip-corrupted

# Rollback to previous state
stellaops vexlens import rollback --to vexlens-bundle-2025-11-29
```

---

## 8) Bundle Management

### 8.1 Retention Policy

```yaml
vexlens:
  bundles:
    # Keep last N bundles
    retentionCount: 5
    # Minimum age before deletion
    minimumAgeDays: 30
    # Archive location
    archivePath: /archive/vexlens-bundles
```

### 8.2 Storage Requirements

| Data Type | Typical Size | Compression Ratio |
|-----------|--------------|-------------------|
| Issuers | 1-5 MB | 5:1 |
| Statements | 100-500 MB | 10:1 |
| Projections | 50-200 MB | 8:1 |
| **Total Bundle** | **150-700 MB** | **8:1** |

### 8.3 Bundle Cleanup

```bash
# Clean old bundles
stellaops vexlens bundles cleanup --keep 5

# Archive bundles older than 30 days
stellaops vexlens bundles archive --older-than 30d --to /archive
```

---

## 9) Security Considerations

### 9.1 Bundle Signing

All bundles should be signed before transfer:

```bash
# Verify signature chain
stellaops vexlens import verify-chain \
  --bundle /import/bundle \
  --trust-root /etc/vexlens/root-ca.pem
```

### 9.2 Transfer Security

1. Use encrypted removable media
2. Maintain custody chain documentation
3. Verify checksums at each transfer point
4. Log all bundle operations

### 9.3 Access Control

```yaml
vexlens:
  security:
    # Require authentication for import
    importRequiresAuth: true
    # Allowed import roles
    importRoles: [vexlens.admin, vexlens.operator]
    # Audit all imports
    auditImports: true
```

---

## 10) Troubleshooting

### 10.1 Common Issues

| Issue | Cause | Resolution |
|-------|-------|------------|
| Import fails | Corrupted bundle | Re-export from source |
| Signature invalid | Wrong trust root | Update trust anchors |
| Time anchor expired | Stale time anchor | Generate new anchor |
| Missing issuers | Incomplete export | Include issuers in export |

### 10.2 Diagnostic Commands

```bash
# Verify bundle contents
stellaops vexlens bundle inspect /import/bundle

# Check import readiness
stellaops vexlens import preflight --bundle /import/bundle

# Generate diagnostic report
stellaops vexlens diagnostics --output /tmp/diag.json
```