up

docs/onboarding/dev-quickstart.md

@@ -0,0 +1,326 @@
+# StellaOps Developer Quickstart
+
+> **Audience:** Mid-level .NET developers  
+> **Goal:** Get you productive on StellaOps in 1–2 days, with special focus on determinism, cryptographic attestations, and the canonical data model.
+
+---
+
+This quickstart mirrors the 29-Nov-2025 Developer Onboarding advisory (`docs/product-advisories/29-Nov-2025 - StellaOps – Mid-Level .NET Onboarding (Quick Start).md`) and keeps the determinism-first guidance in sync with that release note.
+
+## 1. What You’re Building (Context)
+
+StellaOps is a sovereign, air-gap-friendly platform that turns **SBOMs → VEX** with a fully **replayable, deterministic trust graph**.
+
+Core concepts:
+
+- **Deterministic scans:** Same inputs → same graph, hashes, and verdicts.
+- **Cryptographic attestations:** DSSE/in-toto envelopes, optional PQC.
+- **Trust lattice:** Merges vendor VEX, runtime signals, configs, etc. into a single deterministic verdict.
+- **Audit trail:** Every decision is reproducible from stored inputs and proofs.
+
+If you think “content-addressed trust pipeline for SBOMs + VEX,” you’re in the right mental model.
+
+---
+
+## 2. Repository & Docs Map
+
+Start by opening these projects **in order**:
+
+1. `src/StellaOps.Scanner.WebService/`  
+   Scanning endpoints, rule plumbing, and calls into the trust lattice.
+2. `src/StellaOps.Vexer/` (a.k.a. *Excititor*)  
+   VEX verdict engine and trust-merge logic.
+3. `src/StellaOps.Sbomer/`  
+   SBOM ingest / normalize (CycloneDX, SPDX).
+4. `src/StellaOps.Authority/`  
+   Key management, DSSE/in-toto attestations, license tokens, Rekor integration.
+5. `src/StellaOps.Scheduler/`  
+   Batch processing, replay orchestration.
+6. `src/StellaOps.Shared/CanonicalModel/`  
+   Canonical entities & graph IDs. **Read this carefully** – it underpins determinism.
+
+Helpful docs:
+
+- `docs/modules/platform/*` – protocols (DSSE envelopes, lattice terms, trust receipts).
+- `docs/architecture/*` – high-level diagrams and flows.
+
+---
+
+## 3. Local Dev Setup
+
+### 3.1 Prerequisites
+
+- **.NET 10 SDK** (preview as specified in repo).  
+- **Docker** (for DB, queues, object storage).  
+- **Node.js** (for Angular UI, if you’re touching the frontend).  
+- **WSL2** (optional but convenient on Windows).
+
+### 3.2 Bring Up Infra
+
+From the repo root:
+
+```bash
+# Bring up core infra for offline / air-gap friendly dev
+docker compose -f compose/offline-kit.yml up -d
+```
+
+This usually includes:
+
+- MongoDB or Postgres (configurable).
+- RabbitMQ (or equivalent queue).
+- MinIO / object storage (depending on profile).
+
+### 3.3 Configure Environment
+
+```bash
+cp env/example.local.env .env
+```
+
+Key settings:
+
+- `STELLAOPS_DB=Mongo` or `Postgres`.
+- `AUTHORITY_*` – key material and config (see comments in `example.local.env`).
+- Optional: `AUTHORITY_PQC=on` to enable post-quantum keys (Dilithium).
+
+### 3.4 Build & Run Backend
+
+```bash
+# Restore & build everything
+dotnet restore
+dotnet build -c Debug
+
+# Run a focused slice for development
+dotnet run --project src/StellaOps.Authority/StellaOps.Authority.csproj
+dotnet run --project src/StellaOps.Scanner.WebService/StellaOps.Scanner.WebService.csproj
+```
+
+Health checks (adjust ports if needed):
+
+```bash
+curl -s http://localhost:5080/health          # Authority
+curl -s http://localhost:5081/health          # Scanner
+```
+
+---
+
+## 4. Deterministic Sanity Tests
+
+These tests prove your local environment is configured correctly for **determinism**. If any of these fail due to snapshot mismatch, fix your environment before writing new features.
+
+### 4.1 SBOM → VEX “Not Affected” (Reachability False)
+
+```bash
+dotnet test tests/Determinism/Det_SbomToVex_NotAffected.csproj
+```
+
+**What it checks:**
+
+- Two consecutive runs with the same SBOM produce identical `GraphRevisionID` and DSSE payload hashes.
+
+If they differ, inspect:
+
+- JSON canonicalization.
+- Locale / culture.
+- Line endings.
+
+### 4.2 In-toto Chain: Source → Build → Image Attestation
+
+```bash
+dotnet test tests/Attestations/Att_InToto_Chain.csproj
+```
+
+**What it checks:**
+
+- DSSE envelope canonicalization is stable.
+- Signature over CBOR-canonical JSON matches the stored hash.
+- Full in-toto chain can be replayed deterministically.
+
+### 4.3 Lattice Merge: Vendor VEX + Runtime Signal
+
+```bash
+dotnet test tests/Lattice/Lattice_VendorPlusRuntime.csproj
+```
+
+**What it checks:**
+
+- Merge verdict is stable regardless of input set order.
+- Resulting `TrustReceipt` is byte-for-byte identical between runs.
+
+If any “golden” snapshots differ, you likely have:
+
+- Non-canonical JSON.
+- Unstable enumeration (e.g., iterating `Dictionary<>` directly).
+- Locale or newline drift.
+
+---
+
+## 5. Coding Conventions (Determinism & Crypto)
+
+These are **non-negotiable** in code that affects trust graphs, proofs, or attestations.
+
+### 5.1 JSON & Canonicalization
+
+- Use the **`CanonicalJson`** helper whenever a payload is hashed, signed, or used for IDs.
+- Rules: UTF-8, sorted keys, no insignificant whitespace, `\n` line endings.
+
+### 5.2 DSSE Envelopes
+
+- `payloadType` must always be `application/vnd.stellaops.trust+json`.
+- Sign over the canonicalized bytes.
+
+```csharp
+var payload = CanonicalJson.Serialize(trustDoc);
+var env = DsseEnvelope.Create("application/vnd.stellaops.trust+json", payload);
+var signed = await keyRing.SignAsync(env.CanonicalizeBytes());
+await rekor.SubmitAsync(signed, RekorMode.OfflineMirrorIfAirgapped);
+```
+
+### 5.3 Hashing
+
+- **BLAKE3** for internal content addressing.
+- **SHA-256** where interop demands it.
+- Never mix algorithms within the same ID type.
+
+### 5.4 Keys & Algorithms
+
+- Default signatures: **Ed25519** via `Authority.KeyRing`.
+- Optional PQC: **Dilithium** when `AUTHORITY_PQC=on`.
+- Always go through the keyring abstraction; never manage raw keys manually.
+
+### 5.5 Time & Clocks
+
+- Use `Instant`/`DateTimeOffset` (UTC), truncated to milliseconds.
+- Never use `DateTime.Now` or local clocks in canonical data.
+
+### 5.6 IDs & Graph Nodes
+
+- Canonical/public IDs derive from hashes of canonical bytes.
+- DB primary keys are implementation details.
+- Do not depend on DB auto-increment or implicit sort order when hashing.
+
+### 5.7 VEX Verdicts
+
+Every VEX verdict must:
+
+- Carry `proofs[]` (reachability, config guards, runtime paths).
+- Emit a `receipt` signed by Authority, covering verdict, proof hashes, and context.
+
+---
+
+## 6. Daily Workflow
+
+1. Pick a focused issue (see starter tasks below).
+2. Write tests first, especially determinism scenarios.
+3. Implement changes with canonicalization boundaries explicit and signing centralized.
+4. Run `dotnet test --filter Category=Determinism`.
+5. Commit with the appropriate prefix (`feat(scanner):`, `feat(vexer):`, `feat(authority):`) and mention the affected `GraphRevisionID` if your change alters the trust graph.
+
+---
+
+## 7. Suggested Starter Tasks
+
+These introduce the canonical data model and determinism mindset.
+
+### 7.1 Normalize CycloneDX Components → Canonical Packages
+
+**Area:** `StellaOps.Sbomer`
+
+**Tests:** `tests/Determinism/Det_SbomMapping`
+
+**Definition of done:**
+
+- Equivalent SBOMs (even if fields shuffle) yield identical package sets and canonical IDs.
+- `CanonicalPackageSet.hash` is stable.
+- Edge cases covered: missing `purl`, duplicate components, case variation.
+
+### 7.2 Implement “Not-Affected by Configuration” Proof
+
+**Area:** `StellaOps.Vexer/Proofs/ConfigSwitchProof.cs`
+
+**Definition of done:**
+
+- With `FeatureX=false`, CVE-1234 reports `status = not_affected` and the proof records `configPath` + `observed=false`.
+- Proof hash is deterministic and included in the DSSE receipt.
+- Lattice merge flips the verdict to `not_affected` when the runtime/config proof weight crosses the threshold, even if the vendor says `affected`.
+
+### 7.3 Authority Offline Rekor Mirror Submitter
+
+**Area:** `StellaOps.Authority/Rekor/RekorMirrorClient.cs`
+
+**Definition of done:**
+
+- `RekorMode.OfflineMirrorIfAirgapped` records canonical entries (JSON + hash path) locally.
+- `rekor sync` replays entries in order, preserving entry IDs.
+- Golden test ensures the same input sequence → same mirror tree hash.
+
+---
+
+## 8. Database Notes (Mongo ↔ Postgres)
+
+- Use `StellaOps.Shared.Persistence` repository interfaces.
+- Canonical/public IDs are hash-derived; DB keys are internal details.
+- Never rely on DB sort order for anything that affects hashes or verdicts; re-canonicalize before hashing and apply deterministic ordering afterwards.
+
+---
+
+## 9. Common Pitfalls
+
+1. Non-canonical JSON (unsorted keys, extra whitespace, mixed `\r\n`).
+2. Local time creeping into proofs (`DateTime.Now`).
+3. Unstable GUIDs in tests or canonical entities.
+4. Unordered collections (`Dictionary<>` iterations, LINQ without `OrderBy`) while hashing or serializing.
+5. Platform drift (Windows vs Linux newline/culture differences) – always use invariant culture and `\n` in canonical data.
+
+---
+
+## 10. Useful Commands
+
+### 10.1 Determinism Pack
+
+```bash
+# Run determinism-tagged fixtures
+dotnet test --filter Category=Determinism
+```
+
+Update golden snapshots deliberately:
+
+```bash
+dotnet test --filter Category=Determinism -- \ 
+  TestRunParameters.Parameter(name="UpdateSnapshots", value="true")
+```
+
+### 10.2 Quick API Smoke
+
+```bash
+curl -s http://localhost:5080/health
+
+curl -s -X POST \
+  http://localhost:5081/scan \
+  -H "Content-Type: application/json" \
+  -d @samples/nginx.sbom.json
+```
+
+### 10.3 Verify DSSE Signature Locally
+
+```bash
+dotnet run --project tools/StellaOps.Tools.Verify -- file trust.receipt.json
+```
+
+---
+
+## 11. Glossary (Ask-Once)
+
+- **SBOM** – Software Bill of Materials (CycloneDX/SPDX).
+- **VEX** – Vulnerability Exploitability eXchange: verdicts include `affected`, `not_affected`, `under_investigation`.
+- **DSSE** – Dead Simple Signing Envelope; we sign canonical bytes.
+- **In-toto** – Supply-chain attestation framework for source → build → artifact chains.
+- **Lattice** – Rule system merging multiple verdicts/proofs into deterministic outcomes.
+- **GraphRevisionID** – Hash of the canonical trust graph; acts like a build number for audits.
+
+Welcome aboard. Your best “map” is:
+
+1. Read the CanonicalModel types.
+2. Run the determinism tests.
+3. Ship one of the starter tasks with deterministic, test-covered changes.
+
+Keep everything **canonical, hashable, and replayable** and you’ll fit right in.