save work

docs/modules/attestor/transparency.md

@@ -1,6 +1,65 @@
 # Transparency (DOCS-ATTEST-74-002)
 
-- Optional Rekor/witness integration.
-- In sealed mode, use bundled checkpoints and disable live witness fetch.
-- Verification: compare embedded checkpoint with bundled; log discrepancies.
-- Record transparency fields on verification result: `{uuid, logIndex, checkpointHash}`.
+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.