66 lines
3.2 KiB
Markdown
66 lines
3.2 KiB
Markdown
# 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.
|