# Transparency (DOCS-ATTEST-74-002)

Last updated: 2025-12-18

## Purpose

StellaOps uses transparency logs (Sigstore Rekor v2 or equivalent) to provide tamper-evident, timestamped anchoring for DSSE bundles.

This document freezes the **offline verification inputs** used by Attestor in sealed/air-gapped operation and points to the canonical schema for `rekor-receipt.json`.

## Offline Inputs (Air-Gap / Sealed Mode)

Baseline directory layout is defined in `docs/product-advisories/14-Dec-2025 - Offline and Air-Gap Technical Reference.md`:

```
/evidence/
  keys/
    tlog-root/             # pinned transparency log public key(s)
  tlog/
    checkpoint.sig         # signed tree head / checkpoint (note format)
    entries/               # *.jsonl entry pack (leaves + proofs)
```

### Rekor Receipt (`rekor-receipt.json`)

The offline kit (or any offline DSSE evidence pack) may include a Rekor receipt alongside a DSSE statement.

- **Schema:** `docs/schemas/rekor-receipt.schema.json`
- **Source:** `docs/product-advisories/14-Dec-2025 - Rekor Integration Technical Reference.md` (Section 13.1) and `docs/product-advisories/14-Dec-2025 - Offline and Air-Gap Technical Reference.md` (Section 1.4)

Fields:
- `uuid`: Rekor entry UUID.
- `logIndex`: Rekor log index (integer, >= 0).
- `rootHash`: expected Merkle tree root hash (lowercase hex, 32 bytes).
- `hashes`: Merkle inclusion path hashes (lowercase hex, 32 bytes each; ordered as provided by Rekor).
- `checkpoint`: either the signed checkpoint note text (UTF-8) or a relative path (e.g., `checkpoint.sig`, `tlog/checkpoint.sig`) resolved relative to the receipt file.

### Checkpoint (`checkpoint.sig`)

`/evidence/tlog/checkpoint.sig` is the pinned signed tree head used for offline verification.

Contract:
- Content is **UTF-8 text** using **LF** line endings.
- The checkpoint **MUST** parse to the checkpoint body shape used by `CheckpointSignatureVerifier` (origin, tree size, base64 root hash, optional timestamp).
- In offline verification, the checkpoint from receipts SHOULD match the pinned checkpoint (tree size + root hash).

### Entry Pack (`entries/*.jsonl`)

`/evidence/tlog/entries/*.jsonl` is an optional-but-recommended offline mirror snapshot for bulk audit/replay.

Contract:
- Files are **NDJSON** (one JSON object per line).
- Each line uses the "Rekor Entry Structure" defined in `docs/product-advisories/14-Dec-2025 - Rekor Integration Technical Reference.md` (Section 4).
- **Deterministic ordering**:
  - File names sort lexicographically (Ordinal).
  - Within each file, lines sort by `rekor.logIndex` ascending.

## Offline Verification Rules (High Level)

1. Load the pinned Rekor log public key from `/evidence/keys/tlog-root/` (rotation is handled by shipping a new key file alongside the updated checkpoint snapshot).
2. Verify the checkpoint signature (when configured) and extract tree size + root hash.
3. For each `rekor-receipt.json`, verify:
   - inclusion proof path resolves to `rootHash` for the given leaf hash,
   - receipt checkpoint root matches the pinned checkpoint root (same tree head).
4. Optionally, validate that each receipt's UUID/digest appears in the entry pack and that the recomputed Merkle root matches the pinned checkpoint.