Merge branch 'main' of https://git.stella-ops.org/stella-ops.org/git.stella-ops.org

docs/modules/scanner/design/cache-key-contract.md

@@ -0,0 +1,34 @@
+# Scanner Cache Key & DSSE Validation Contract
+
+Scope: unblocks SCAN-CACHE-186-013 by defining cache key inputs, validation, and storage layout.
+
+## Cache key
+- Key components (concatenate with `|`, then SHA256):
+  1. `subject_digest` (image digest)
+  2. `manifest_hash` (replay manifest canonical hash)
+  3. `tool.id` + `tool.version`
+  4. `policy.hash`
+  5. feed hashes (sorted, joined with `;`)
+  6. determinism toggles (clock seed, rng seed, max_parallel)
+- Resulting cache key encoded as hex SHA256; used as folder name under CAS: `cache/{tenant}/{cache_key}/`.
+
+## Stored entries
+- `sbom.cdx.json`, `vex.json`, `findings.ndjson`, `entropy.report.json` (when present).
+- `cache-manifest.json`: summary containing all key components, file hashes, created_at UTC.
+- `checksums.txt`: SHA256 for every file in folder.
+- Optional `cache-manifest.json.dsse`: DSSE envelope signed by replay signer profile; payload type `application/vnd.stellaops.cache-manifest+json`.
+
+## Validation on hit
+1. Recompute cache key from incoming request; must match folder name.
+2. Recompute SHA256 over stored files and compare with `checksums.txt`.
+3. If DSSE present, verify signature using replay trust root.
+4. Compare `manifest_hash` in `cache-manifest.json` with current scan manifest.
+5. Reject (miss) on any mismatch; log reason for determinism audit.
+
+## Idempotency & TTL
+- Cache entries are immutable; if folder exists, compare manifests and return existing entry.
+- TTL controlled by policy; default 30 days; purge job removes expired entries by created_at.
+
+## API notes
+- Worker -> WebService: `POST /api/v1/cache/{subjectDigest}` with bundle metadata; returns cache URI or 404 (miss).
+- WebService -> Worker: `GET /api/v1/cache/{subjectDigest}?cacheKey=...` returns cache-manifest + artifacts stream.

docs/modules/scanner/design/entropy-transport.md

@@ -0,0 +1,30 @@
+# Entropy Evidence Transport Contract
+
+Purpose: unblock SCAN-ENTROPY-186-012 by defining worker → webservice transport for entropy reports.
+
+## Endpoint
+- `POST /api/v1/scans/{scanId}/entropy`
+- Headers: `X-Tenant-Id`, `Content-Type: application/json`
+- Body: `EntropyReportRequest`
+
+## EntropyReportRequest (JSON)
+- `subject_digest` (string, required) — image digest.
+- `report_path` (string, required) — relative path inside replay bundle (e.g., `artifacts/entropy.report.json`).
+- `hash` (string, required) — SHA256 hex of the report file.
+- `penalties` (object) — `{ overall: number, layers: [{ digest, score, high_entropy_regions: [ { offset, length, reason } ] }] }`.
+- `created_at` (string, ISO-8601 UTC).
+- `tool`: `{ id, version, rng_seed, max_parallel }`.
+
+## WebService behavior
+- Validate tenant, scanId, subject_digest matches scan record.
+- Validate SHA256 by re-reading report from bundle if available; else accept hash and queue verification job.
+- Persist entropy metadata with scan record and attach to replay manifest.
+- Respond `202 Accepted` with `{ status_url }`; return `409` if entropy already recorded for scanId+subject_digest.
+
+## Error handling
+- `400` malformed request; `401/403` auth; `404` scan not found; `422` hash mismatch; `500` transient CAS/read errors.
+
+## Determinism
+- No clocks added server-side; use provided `created_at`.
+- No recalculation of entropy; only verification.
+- Log deterministic reasons for rejection to aid reproducible replay.

docs/modules/scanner/design/replay-pipeline-contract.md

@@ -0,0 +1,54 @@
+# Replay Pipeline Contract (Scanner ↔ Worker ↔ CAS)
+
+Purpose: unblock Sprint 0186 replay tasks by defining the worker→webservice contract, manifest fields, and CAS layout for record/replay.
+
+## Bundle layout
+- Format: `tar.zst`, deterministic ordering, UTF-8, LF endings.
+- Top-level entries:
+  - `manifest.json` — canonical JSON, UTF-8.
+  - `inputs/` — sealed scan inputs (config, policies, feeds) as provided to the worker.
+  - `artifacts/` — analyzer outputs (SBOM, VEX, findings, entropy, logs), named by subject digest and analyzer id.
+  - `evidence/` — DSSE envelopes and attestations.
+  - `checksums.txt` — SHA256 of every file in bundle (POSIX path + two spaces + hash).
+
+## manifest.json fields
+- `scan_id` (uuid), `tenant`, `subject` (image digest or purl).
+- `tool`: `id`, `version`, `commit`, `invocation_hash`.
+- `policy`: `id`, `version`, `hash`.
+- `feeds`: array of `{ id, version, hash }`.
+- `inputs_hash`: SHA256 of normalized `inputs/`.
+- `artifacts`: array of `{ path, type, analyzer, subject, hash, merkle_root? }`.
+- `entropy`: `{ path, hash, penalties }` when present.
+- `timeline`: ordered event ids + hashes for replay audit.
+- `created_at`: ISO-8601 UTC.
+
+Canonicalization: RFC3339/ISO timestamps, sorted keys (encoder stable), lists sorted by `path` unless natural order documented (timeline).
+
+## Transport
+- Worker POSTs to WebService: `POST /api/v1/replay/runs/{scanId}/bundle`
+  - Headers: `X-Tenant-Id`, `Content-Type: application/zstd`
+  - Body: bundle bytes
+  - Response: `201` with `{ cas_uri, manifest_hash, status_url }`
+- WebService stores bundle at CAS path: `cas/{subject}/{scan_id}/{manifest_hash}.tar.zst`
+  - `manifest_hash` = SHA256(manifest.json canonical bytes)
+  - DSSE envelope optional: `cas/.../{manifest_hash}.tar.zst.dsse`
+
+## DSSE signing
+- Payload type: `application/vnd.stellaops.replay-bundle+json`
+- Body: canonical `manifest.json`
+- Signer: Signer service with replay profile; Authority verifies using replay trust root; Rekor optional.
+
+## Determinism rules
+- Fixed clock from worker (override via env `STELLAOPS_REPLAY_FIXED_CLOCK`).
+- RNG seed carried in manifest (`tool.rng_seed`), replay MUST reuse.
+- Concurrency cap recorded (`tool.max_parallel`), replay must honor <= value.
+- Log filtering: strip non-deterministic timestamps before hashing.
+
+## Error handling
+- 400: missing tenant, bad bundle; 422: manifest invalid; 409: manifest_hash already stored (idempotent); 500: CAS failure -> retry with backoff.
+
+## Validation checklist
+- Verify `checksums.txt` matches bundle.
+- Verify `inputs_hash` recomputes.
+- Verify `manifest_hash` == canonical SHA256(manifest.json).
+- Verify DSSE (if present) against replay trust root.