# CVSS v4.0 Receipts – Hardening Guide

Source advisory: `docs/product-advisories/25-Nov-2025 - Add CVSS v4.0 Score Receipts for Transparency.md` (CV1–CV10). This guide turns the gaps into implementable rules for Sprint 0190.

## Canonical hashing (CV2)
- Serializer: JSON Canonicalization Scheme (JCS).
- Ordering: lexicographic keys; arrays keep order; drop nulls.
- Numbers: fixed 4-decimal precision; invariant culture; no exponent.
- Time: UTC ISO-8601 `Z`; strip milliseconds unless non-zero.
- Hash: SHA-256 of canonical JSON; store as `inputsHash` and DSSE subject.
- Test vectors: `tests/Policy/StellaOps.Policy.Scoring.Tests/Fixtures/hashing/`.

## Policy replay & backfill (CV1)
- Policies immutable; bump version for any change.
- On change, emit new receipts with `supersedesReceiptId` and retain old ones.
- Backfill job: re-score under new policy, append history, re-sign DSSE.

## Tenant segregation & RBAC (CV4, CV9)
- Storage keys include `tenantId`; hashes/DSSE annotate tenant.
- Roles: Security Engineer (Base), SOC Analyst (Threat), Customer Admin (Env), Viewer (read-only).
- Enforce at API/repo layer and in canonical hash.

## Deterministic exports (CV8)
- JSON export: JCS ordering, UTF-8, UTC timestamps, stable severity palette.
- PDF export: embed fonts (Source Sans 3 + Roboto Mono), A4, fixed margins; hash PDF bytes and persist `exportHash`.

## v3.1 → v4.0 conversion (CV5)
- Deterministic mapping; tag `source: "converted-v3.1"`, set `conversionMethod` + `confidence`; retain vendor vector.

## Evidence provenance (CV6)
- Evidence items use CAS URIs + DSSE refs, include `retentionClass`, `redactionStatus`, `verifiedAt`, `hashMismatch`.

## Immutability & monitoring (CV7, CV10)
- Receipts append-only; amendments create new IDs + DSSE.
- Alerts: DSSE verify failures, policy hash drift, hash mismatch, engine version skew. Prometheus counters: `cvss_receipt_dsse_failures_total`, `cvss_policy_drift_total`, `cvss_hash_mismatch_total`.

## Golden fixtures & locations
- Hashing vectors: `src/Policy/__Tests/StellaOps.Policy.Scoring.Tests/Fixtures/hashing/example-receipt-input.json` with expected hash `example-receipt-input.sha256`.
- Receipts/exports under `tests/Policy/StellaOps.Policy.Scoring.Tests/Fixtures/` (expand as features land).
- Sample PDFs in `Fixtures/exports/` once generated.

## Implementation checklist
- Wire `ReceiptCanonicalizer` to JCS rules above.
- Add backfill job + history persistence.
- Enforce tenant/RBAC and annotate hashes/DSSE.
- Implement deterministic PDF export and record `exportHash`.
- Store conversion metadata for v3.1 sources.
- Verify evidence CAS/DSSE on ingest; fail closed.
- Expose metrics/alerts listed above.