# Stella Ops Reference Architecture Card (Dec 2025)

> **One-Pager** for product managers, architects, and auditors.
> Full specification: `docs/07_HIGH_LEVEL_ARCHITECTURE.md`

---

## Topology & Trust Boundaries

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              TRUST BOUNDARY 1                                │
│  ┌─────────────────┐                                                        │
│  │   EDGE LAYER    │  StellaRouter (Gateway) / UI                           │
│  │                 │  OAuth2/OIDC Authentication                            │
│  └────────┬────────┘                                                        │
│           │ Signed credentials/attestations required                        │
├───────────┼─────────────────────────────────────────────────────────────────┤
│           ▼                      TRUST BOUNDARY 2                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         CONTROL PLANE                                │   │
│  │                                                                      │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │   │
│  │  │Scheduler │  │ Policy   │  │Authority │  │ Attestor │            │   │
│  │  │          │  │ Engine   │  │          │  │          │            │   │
│  │  │ Routes   │  │ Signed   │  │ Keys &   │  │ DSSE +   │            │   │
│  │  │ work     │  │ verdicts │  │ identity │  │ Rekor    │            │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘            │   │
│  │                                                                      │   │
│  │  ┌──────────────────────────────────────┐                           │   │
│  │  │     Timeline / Notify                 │                           │   │
│  │  │     Immutable audit + notifications   │                           │   │
│  │  └──────────────────────────────────────┘                           │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│           │ Only blessed evidence/identities influence decisions           │
├───────────┼─────────────────────────────────────────────────────────────────┤
│           ▼                      TRUST BOUNDARY 3                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        EVIDENCE PLANE                                │   │
│  │                                                                      │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │   │
│  │  │ Sbomer   │  │Excititor │  │Concelier │  │Reachabil-│            │   │
│  │  │          │  │          │  │          │  │ity/Sigs  │            │   │
│  │  │CDX 1.7 / │  │ VEX      │  │Advisory  │  │ Is vuln  │            │   │
│  │  │SPDX 3.0.1│  │ claims   │  │ feeds    │  │reachable?│            │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘            │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│           │ Tamper-evident, separately signed; opinions in Policy only      │
├───────────┼─────────────────────────────────────────────────────────────────┤
│           ▼                      TRUST BOUNDARY 4                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                          DATA PLANE                                  │   │
│  │                                                                      │   │
│  │  ┌──────────────────────────────────────────────────────────────┐   │   │
│  │  │  Workers / Scanners                                           │   │   │
│  │  │  Pull tasks → compute → emit artifacts + attestations         │   │   │
│  │  │  Isolated per tenant; outputs tied to inputs cryptographically│   │   │
│  │  └──────────────────────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Artifact Association (OCI Referrers)

```
   Image Digest (Subject)
         │
         ├──► SBOM (CycloneDX 1.7 / SPDX 3.0.1)
         │         └──► DSSE Attestation
         │                    └──► Rekor Log Entry
         │
         ├──► VEX Claims
         │         └──► DSSE Attestation
         │
         ├──► Reachability Subgraph
         │         └──► DSSE Attestation
         │
         └──► Policy Verdict
                   └──► DSSE Attestation
                              └──► Rekor Log Entry
```

- Every artifact is a **subject** in the registry
- SBOMs, VEX, verdicts attached as **OCI referrers**
- Multiple versioned, signed facts per image without altering the image

---

## Data Flows

### Evidence Flow

```
Workers ──► SBOM (CDX 1.7) ──► DSSE Sign ──► OCI Referrer ──► Registry
        ├─► VEX Claims    ──► DSSE Sign ──► OCI Referrer ──►
        ├─► Reachability  ──► DSSE Sign ──► OCI Referrer ──►
        └─► All wrapped as in-toto attestations
```

### Verdict Flow

```
Policy Engine ──► Ingests SBOM/VEX/Reachability/Signals
              ──► Applies rules (deterministic IR)
              ──► Emits signed verdict
              ──► Verdict attached via OCI referrer
              ──► Replayable: same inputs → same output
```

### Audit Flow

```
Timeline ──► Captures all events (immutable)
         ──► Links to attestation digests
         ──► Enables replay and forensics
```

---

## Tenant Isolation

| Layer | Mechanism |
|-------|-----------|
| Database | PostgreSQL RLS (Row-Level Security) |
| Application | AsyncLocal tenant context |
| Storage | Tenant-scoped paths |
| Crypto | Per-tenant keys & trust roots |
| Network | Tenant header propagation |

---

## Minimal Day-1 Policy

```yaml
rules:
  # Block reachable HIGH/CRITICAL unless VEX says not_affected
  - match: { severity: [CRITICAL, HIGH], reachability: reachable }
    unless: { vexStatus: not_affected }
    action: block

  # Fail on >5% unknowns
  - match: { unknownsRatio: { gt: 0.05 } }
    action: block

  # Require signed SBOM + verdict for production
  - match: { environment: production }
    require: { signedSbom: true, signedVerdict: true }
```

---

## SBOM Format Support

| Format | Generation | Parsing | Notes |
|--------|------------|---------|-------|
| CycloneDX 1.7 | Yes | Yes | Primary format |
| CycloneDX 1.6 | - | Yes | Backward compat |
| SPDX 3.0.1 | Yes | Yes | Alternative format |
| SPDX 2.x | - | Yes | Import only |

---

## Key Capabilities

| Capability | Status | Notes |
|------------|--------|-------|
| Deterministic SBOMs | Complete | Same input → same output |
| Signed Verdicts | Complete | DSSE + in-toto |
| Replayable Verdicts | Complete | Content-addressed proofs |
| OCI Referrers | Complete | Subject digest model |
| Rekor Transparency | Complete | v2 tile-backed |
| Tenant Isolation | Complete | RLS + crypto separation |
| Air-Gap Operation | Complete | Offline bundles |
| CycloneDX 1.7 | Planned | Sprint 3600.0002 |
| SPDX 3.0.1 Generation | Planned | Sprint 3600.0003 |
| Gateway WebService | Planned | Sprint 3600.0001 |
| Proof Chain UI | Planned | Sprint 4200.0001 |

---

## Quick Glossary

| Term | Definition |
|------|------------|
| **SBOM** | Software Bill of Materials (what's inside) |
| **VEX** | Vulnerability Exploitability eXchange (is CVE relevant?) |
| **Reachability** | Graph proof that vulnerable code is (not) callable |
| **DSSE** | Dead Simple Signing Envelope |
| **in-toto** | Supply chain attestation framework |
| **OCI Referrers** | Registry mechanism to link artifacts to image digest |
| **OpTok** | Short-lived operation token from Authority |
| **DPoP** | Demonstrating Proof of Possession (RFC 9449) |

---

## Implementation Sprints

| Sprint | Title | Priority |
|--------|-------|----------|
| 3600.0001.0001 | Gateway WebService | HIGH |
| 3600.0002.0001 | CycloneDX 1.7 Upgrade | HIGH |
| 3600.0003.0001 | SPDX 3.0.1 Generation | MEDIUM |
| 4200.0001.0001 | Proof Chain Verification UI | HIGH |
| 5200.0001.0001 | Starter Policy Template | HIGH |

---

## Audit Checklist

- [ ] All SBOMs have DSSE signatures
- [ ] All verdicts have DSSE signatures
- [ ] Rekor log entries exist for production artifacts
- [ ] Tenant isolation verified (RLS + crypto)
- [ ] Replay tokens verify (same inputs → same verdict)
- [ ] Air-gap bundles include all evidence
- [ ] OCI referrers discoverable for all images

---

**Source**: Reference Architecture Advisory (Dec 2025)
**Last Updated**: 2025-12-21