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.