git.stella-ops.org/EPIC_3.md

Here’s Epic 3 in the same “paste‑into‑repo” format: exhaustive, implementation‑ready, and aligned with the AOC model plus the Policy Engine from the previous epics.

---

# Epic 3: StellaOps Console (Web UI over WebServices)

> Short name: **StellaOps Console**
> Services touched: **Web API Gateway, Authority (authN/Z), Policy Engine, SBOM Service, Conseiller (Feedser), Excitator (Vexer), Scheduler/Workers, Telemetry**
> Data stores used via APIs: **MongoDB (reads only from UI), object storage for traces**, optional **Redis/NATS** for live updates
> Deliverable: **TypeScript/React web application** with a component library and feature modules, packaged as container images and static builds

---

## 1) What it is

**StellaOps Console** is the first‑party Web UI for all Stella WebServices. It provides a cohesive, role‑aware surface for:

* Viewing raw AOC facts (advisories, VEX, SBOMs) without mutation.
* Applying and simulating policies (VEX application rules, advisory normalization) then exploring **effective findings**.
* Navigating SBOMs as graphs, zooming into components, and seeing linked advisories/VEX with clear precedence.
* Running and monitoring evaluations, auditing why decisions were made, and exporting evidence.
* Administering tenants, users and roles, API tokens, and integrations.
* Publishing a self‑hostable Console image and a **Download & Install** page covering all product containers.

The Console is a read‑write client for allowable operations (policy authoring, run orchestration, approvals), and strictly read‑only for **raw facts** per the AOC enforcement. It is **not** a new API; it is a UI over the existing ones with strong guardrails and deterministic behavior.

---

## 2) Why

* Teams need a single, consistent interface to explore SBOMs, advisories, VEX, and policy outcomes.
* Audits require visible provenance, replayable evidence, and explanation chains.
* Policy creation and simulation are safer when you can see deltas and traces.
* Many workflows benefit from visual tools: graph explorers, diff views, and step‑wise wizards.
* Not everyone wants to live in the CLI all day. Parity and choice matter.

---

## 3) How it should work (maximum detail)

### 3.1 Information architecture

Top‑level navigation with a tenant context picker:

1. **Dashboard**: high‑level posture and recent changes.
2. **SBOMs**: catalog, search, and **Graph Explorer**.
3. **Advisories & VEX**: raw fact browsers with aggregation‑not‑merge semantics.
4. **Findings**: policy‑materialized findings with filters and explanations.
5. **Policies**: editor, simulation, versioning, approvals.
6. **Runs**: orchestration, live progress, history, diffs.
7. **Reports & Export**: evidence packages, CSV/JSON exports.
8. **Admin**: users/roles, tokens, SSO, tenants, registries, settings.
9. **Downloads**: product containers and installation instructions.

Global elements:

* **Global Filters**: policy version, environment profile, severity band, time window.
* **Search Bar**: PURL, CVE/GHSA IDs, SBOM IDs.
* **Live Status**: background jobs, queue lag, last sync cursors.
* **Help & Docs**: contextual deep links into `/docs/*`.

### 3.2 Navigation & routes

```
/dashboard
/sboms
/sboms/:sbomId
/sboms/:sbomId/graph
/advisories
/advisories/:advisoryId (shows all linked sources; aggregation only)
/vex
/vex/:vexId
/findings?policy=:pid&sbom=:sid&status=:st&severity=:sev
/findings/:findingId/explain
/policies
/policies/:policyId/versions/:v
/policies/:policyId/simulate
/runs
/runs/:runId
/reports
/admin/users
/admin/roles
/admin/tenants
/admin/integrations
/admin/tokens
/downloads
```

### 3.3 Core feature modules

#### 3.3.1 Dashboard

* Cards: “Findings by severity,” “VEX overrides in last 24h,” “New advisories linked,” “Run health,” “Policy changes.”
* Click‑through to filtered views.
* Data sources: aggregated endpoints exposed by Web API (no client‑side aggregation over large sets).

#### 3.3.2 SBOM Explorer (catalog + graph)

* **Catalog**: table with SBOM ID, artifact name/version, source, ingest time, component count, last evaluation per policy.
* **Detail**: components tabular view with paging; filters by package type, license, scope.
* **Graph Explorer**:

  * Interactive canvas with pan/zoom, focus on component, dependency paths, reachability placeholders.
  * Overlay toggles: highlight components with affected findings; show VEX “not_affected” zones; show licenses risk overlay.
  * **Policy overlays**: toggle between policy versions to see in‑place severity/status changes.
* **Actions**: export component list, copy PURL, open related findings.

**AOC alignment**: SBOM content is immutable; any edits are proposed as new SBOM versions upstream. UI displays raw SBOM JSON in a read‑only side panel.

#### 3.3.3 Advisories & VEX browsers

* **Advisories list**:

  * Left panel: filters by source (OSV, GHSA, CSAF vendors, NVD), published/modified time, affected ecosystem.
  * Middle panel: **aggregation group** keyed by linkset identity (same vulnerability across sources). No merging; show a roll‑up with per‑source chips.
  * Right panel: selected advisory source view with raw JSON, references, CVSS vectors, and “linked SBOM components” sample.
  * Severity shown three ways: vendor‑reported, normalized (per mapping), and **effective** under the currently selected policy.
* **VEX list**:

  * Filters by vendor, product, status, justification, scope.
  * Detail panel: all statements applying to the same `(component, advisory)` tuple, with precedence logic visualization and the statement that won under the current policy.
  * Raw JSON viewer for each document.

**Strict rule**: Conseiller and Excitator are visualized as **aggregators only**. No UI affordance suggests server‑side merging. All links route to raw documents with reference IDs.

#### 3.3.4 Findings

* Virtualized table supporting millions of rows via server‑side pagination and cursoring.
* Columns: policy, SBOM, component PURL, advisory IDs (chips for each source), status, severity, last updated, rationale count.
* Row click → **Explain** view with rule hits in order, references to advisories/VEX used, and links to raw docs and trace blobs.
* Bulk export with query replay (the export API re‑runs the same filters on the server and streams CSV/JSON).

#### 3.3.5 Policies

* Embedded **Policy Editor** (from Epic 2) with Monaco features, simulation panel, diffs, and approval workflow.
* Pre‑commit lint and compile; cannot submit with syntax errors.
* Simulation results show increase/decrease unchanged counts, top rules impacting results, and sample affected components.

#### 3.3.6 Runs

* Queue view: queued/running/succeeded/failed with timestamps and SLA hints.
* Live progress with **SSE/WebSocket** updates: tuples processed, rules fired, findings materialized.
* Diff view between runs for the same policy and SBOM set.
* Retry and cancel actions as allowed by RBAC.

#### 3.3.7 Reports & Export

* Evidence bundle creation: include policy version, run ID, sample traces, and result slices.
* Export templates (CSV for management, JSON/NDJSON for SIEM ingestion).
* Signed export manifests with checksums.

#### 3.3.8 Admin

* Users & Roles: invite, disable, role mapping.
* Tenants: create, switch, default policy bindings.
* Tokens: create scoped API tokens with expirations.
* Integrations: configure SSO (OIDC), registries, webhooks.
* Settings: environment defaults for policy evaluation (exposure, runtime hints).

#### 3.3.9 Downloads

* List of official Docker images: `stella-console`, `stella-api`, `conseiller`, `excitator`, `sbom-svc`, `policy-engine`, etc.
* Version matrix, pull commands, Helm chart snippet, offline tarballs, and system requirements.
* Link to `/docs/install/docker.md` and `/docs/deploy/console.md`.

### 3.4 UX flows (key tasks)

* **Triage a vulnerability**: search CVE → open roll‑up → view all sources → jump to affected findings → open Explain → see VEX precedence → decide if policy change is needed → simulate policy → if good, submit and request approval → run → verify new findings.
* **Investigate SBOM**: open SBOM → Graph Explorer → highlight affected nodes under policy P‑X vN → click a node → see linked advisories + VEX → open Explain for a specific finding.
* **Audit evidence**: open run → download evidence bundle with policy, run metadata, traces, and effective finding slice.
* **Onboard team**: invite users, set roles, define default tenant policies, give read‑only access to auditors.

### 3.5 CLI vs UI parity

Create `/docs/cli-vs-ui-parity.md` with a matrix. Principle:

* All **read** capabilities must exist in both CLI and UI.
* All **policy lifecycle** actions exist in both.
* Long‑running operations can be initiated in UI and monitored in either surface.

### 3.6 Security & auth

* Auth: OIDC with PKCE; short‑lived ID tokens; silent refresh.
* RBAC enforced by the API; UI only gates affordances and never trusts itself.
* CSRF not applicable for token‑based APIs; still set robust **CSP**, **X‑Frame‑Options**, and **Referrer‑Policy**.
* Tenancy: every API call includes tenant header; UI shows explicit tenant badge.
* Sensitive pages require **fresh auth** (re‑prompt).

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

### 3.7 Accessibility & i18n

* WCAG 2.1 AA: keyboard nav, focus indicators, ARIA for tables and graphs, color‑contrast tests.
* i18n scaffolding via ICU messages; English shipped first; content keys stored in code, translations as JSON resources.

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

### 3.8 Performance

* Use server‑side pagination and cursoring everywhere; never fetch unbounded lists.
* Virtualized tables and lazy panels.
* Graph Explorer loads neighborhood windows, not whole graphs.
* Cache with TanStack Query; deduplicate requests; stale‑while‑revalidate.
* Performance budgets in CI (Lighthouse): TTI < 3.5s on reference hardware.

### 3.9 Error handling & offline

* Error boundaries per feature; retry buttons; copyable request IDs.
* Network loss → banner + read‑only cached views where safe.
* Clear messages for **AOC** constraints: raw facts cannot be edited.

### 3.10 Telemetry & observability

* UI event telemetry to internal sink (no third‑party beacons by default).
* Metrics: UI API latency percentiles, error rates, SSE subscription health.
* Feature flags to dark‑launch modules.

---

## 4) APIs consumed (representative)

* `GET /sboms`, `GET /sboms/{id}`, `GET /sboms/{id}/components?cursor=...`
* `GET /advisories?source=...`, `GET /advisories/{id}`, `GET /advisories/{id}/linked`
* `GET /vex?status=...`, `GET /vex/{id}`
* `GET /findings/{policyId}` and `GET /findings/{policyId}/{findingId}/explain`
* `POST /policies`, `POST /policies/{id}/compile`, `POST /policies/{id}/simulate`, `POST /policies/{id}/approve`
* `POST /policies/{id}/runs`, `GET /policies/{id}/runs/{runId}` with SSE for progress
* `POST /exports` for evidence bundles
* `GET /auth/user`, `GET /auth/tenants`, `POST /admin/users`, `POST /admin/tokens`

All calls include tenant scope headers and bearer tokens from Authority.

---

## 5) Implementation plan

### 5.1 Frontend architecture

* **Framework**: Next.js 14 (App Router) with TypeScript.
* **State/data**: TanStack Query for server state; Redux only if a global app state proves necessary.
* **UI toolkit**: Internal **Stella UI** component library (headless + primitives) with CSS variables and design tokens.
* **Visualization**: D3 for graph, Monaco for policy editing.
* **Testing**: Playwright (E2E), Vitest/Jest (unit), Storybook (components), Lighthouse (perf).
* **i18n**: `@formatjs/intl` + message catalogs.
* **Packaging**: static build served by Node adapter behind the API gateway; also a `stella-console` Docker image.

**Repo layout**

```
/console
  /apps/web
  /packages/ui         # design system & components
  /packages/api        # typed API clients (OpenAPI codegen)
  /packages/features   # feature modules (sboms, advisories, vex, findings, policies, runs, admin)
  /packages/utils
  /e2e
  /storybook
```

### 5.2 Design System (packages/ui)

* Foundation tokens: color, spacing, typography, elevation; dark/light modes.
* Components: AppShell, Nav, DataTable (virtualized), Badge/Chip, Tabs, Drawer, GraphCanvas, CodeViewer (read‑only JSON), Form primitives, Modal, Toast, Pill filters.
* Accessibility baked into components; snapshot and interaction tests in Storybook.

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

### 5.3 Feature modules

Each module has:

* `routes.tsx` pages, `api` data hooks, `components`, `tests`, `docs link`.
* Query keys standardized for caching and invalidation.

**SBOMs**

* Hooks: `useSboms`, `useSbom(id)`, `useComponents(sbomId, query)`.
* GraphCanvas using neighborhood loaders: `/sboms/:id/graph?center=:purl&depth=1..3`.

**Advisories**

* `useAdvisories(filters)` and `useAdvisory(id)` plus `useLinkedAdvisories(id)`.
* UI explicitly shows aggregation groups; never collapses sources into one record.

**VEX**

* `useVex(filters)`, `useVexDoc(id)`, `useVexForTuple(purl, advisoryId)` for precedence views.

**Findings**

* `useFindings(policyId, filters, cursor)` and `useFinding(findingId)`.
* Explain viewer reading `/findings/:policyId/:findingId/explain`.

**Policies**

* Monaco editor wrapper; compile/simulate actions; approval dialog.
* Diff viewer using the compiler’s diagnostics and rule stats.

**Runs**

* `useRuns`, `useRun(runId)` + SSE hook `useRunProgress(runId)`.

**Admin**

* `useUsers`, `useRoles`, `useTenants`, `useTokens`, `useIntegrations`.

**Downloads**

* Static page with dynamic image tags fetched from registry metadata endpoint; copy‑able commands and Helm snippets.

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

### 5.4 Live updates

* SSE/WebSocket client with backoff, heartbeat, and re‑subscribe logic.
* Only Runs and slim “ticker” endpoints use live channels; everything else is HTTP pull with caching.

### 5.5 Security

* OIDC PKCE flow; token storage in memory; refresh via hidden iframe or refresh endpoint.
* CSP locked to same‑origin, with hashes for inline scripts from Next.
* Feature flags control admin features visibility; RBAC double‑checked on server responses.

### 5.6 Packaging & distribution

* `stella-console:<version>` image built in CI; Nginx or Node serve.
* Helm chart values include Authority issuer, API base URL, tenant defaults.
* Offline bundle artifact for air‑gapped deployments.

---

## 6) Documentation changes (create/update)

1. **`/docs/ui/console-overview.md`**

   * Purpose, IA, tenant model, role mapping, AOC alignment.
2. **`/docs/ui/navigation.md`**

   * Route map, global filters, keyboard shortcuts, deep links.
3. **`/docs/ui/sbom-explorer.md`**

   * Catalog, detail, Graph Explorer, overlays, exports.
4. **`/docs/ui/advisories-and-vex.md`**

   * Aggregation‑not‑merge, multi‑source roll‑ups, raw viewers.
5. **`/docs/ui/findings.md`**

   * Filters, table semantics, explain view, exports.
6. **`/docs/ui/policies.md`**

   * Editor, simulation, diffs, approvals, links to DSL docs.
7. **`/docs/ui/runs.md`**

   * Queue, live progress, diffs, retries, evidence bundles.
8. **`/docs/ui/admin.md`**

   * Users, roles, tenants, tokens, integrations.
9. **`/docs/ui/downloads.md`**

   * Containers list, versions, pull/install commands, air‑gapped flow.
10. **`/docs/deploy/console.md`**

    * Helm, ingress, TLS, CSP, environment variables, health checks.
11. **`/docs/install/docker.md`**

    * All container images, pull commands, compose/Helm examples.
12. **`/docs/security/console-security.md`**

    * OIDC, RBAC, CSP, tenancy, evidence of least privilege.
13. **`/docs/observability/ui-telemetry.md`**

    * UI metrics, logs, dashboards, feature flags.
14. **`/docs/cli-vs-ui-parity.md`**

    * Matrix of operations and surfaces.
15. **`/docs/architecture/console.md`**

    * Frontend architecture, packages, data flow diagrams, SSE design.
16. **`/docs/accessibility.md`**

    * WCAG checklist, testing tools, color tokens.
17. **`/docs/examples/ui-tours.md`**

    * Task‑centric walkthroughs: triage, audit, policy rollout.

> Each document includes a “Compliance checklist” section.
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

---

## 7) Tasks (tracked per team)

### 7.1 Console scaffold & infra

* [ ] Initialize Next.js 14 TypeScript app with App Router.
* [ ] Set up TanStack Query, Auth context, Error boundaries, Toasts.
* [ ] Integrate OIDC client; implement login/logout, tenant picker.
* [ ] Add design tokens and base components in `packages/ui`.
* [ ] Configure CI: build, test, lint, type‑check, Lighthouse budgets.
* [ ] Build `stella-console` container image and Helm chart.

### 7.2 Typed API client

* [ ] Generate clients from OpenAPI; wrap with hooks in `packages/api`.
* [ ] Centralize retry, error mapping, tenant header injection.

### 7.3 Feature delivery

**SBOMs**

* [ ] Catalog page with filters, server pagination.
* [ ] SBOM detail with components table.
* [ ] Graph Explorer with overlays and neighborhood loaders.
* [ ] Raw JSON viewer drawer.

**Advisories & VEX**

* [ ] Advisory aggregation list; per‑source chips; raw view.
* [ ] VEX list with filters; precedence explainer per tuple.
* [ ] Link outs to Findings and SBOMs.

**Findings**

* [ ] Virtualized table; filters; saved views.
* [ ] Explain view: rules fired, references, trace links.
* [ ] Export actions (CSV/JSON stream).

**Policies**

* [ ] Monaco editor with syntax/diagnostics; compile and simulate.
* [ ] Diff and impact panel; submit and approve workflow.
* [ ] Run from simulation context.

**Runs**

* [ ] Runs list; run detail with SSE progress.
* [ ] Diff between runs; evidence bundle download.

**Admin**

* [ ] Users/roles CRUD; token issuance; tenant management.
* [ ] Integrations: OIDC config form; registry connections.
* [ ] Settings for environment defaults.

**Downloads**

* [ ] Registry tag fetch, pull commands, Helm snippet generator.
* [ ] Air‑gapped instructions and offline bundle download.

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

### 7.4 Quality gates

* [ ] Playwright E2E for core flows: triage, simulate, approve, run, explain.
* [ ] Storybook with a11y addon and interaction tests.
* [ ] Lighthouse CI budgets met; perf regressions block merges.
* [ ] i18n scaffolding ready; all strings externalized.
* [ ] Security checks: CSP effective, OIDC flows tested, RBAC enforced.

### 7.5 Docs tasks

* [ ] Populate all docs listed in section 6 with screenshots and animated GIFs.
* [ ] Add “CLI vs UI” parity matrix and keep it in CI to detect drift.
* [ ] Add “AOC user guide” callouts explaining raw fact immutability across pages.

---

## 8) Feature flags

* `ui.graph-explorer`
* `ui.policy-editor`
* `ui.ai-assist` (off by default; when enabled, renders a right‑rail for human‑in‑the‑loop summaries)
* `ui.downloads`

Flag definitions and defaults live in `/docs/observability/ui-telemetry.md` and config map.

---

## 9) Acceptance criteria

* Console ships as a container image with Helm deployment and a static build option.
* SBOM Explorer visualizes graphs and overlays policy outcomes without page crashes on large SBOMs.
* Advisories/VEX browsers display **aggregation only**, never merge sources; raw document viewers are present.
* Findings view supports server‑side pagination and Explain with rule traces.
* Policy Editor compiles, simulates, diffs, and supports approval workflows.
* Runs page shows live progress and enables evidence exports.
* Admin handles users, roles, tenants, tokens, and OIDC configuration.
* Downloads page lists all images and installation paths.
* All pages meet a11y checks and pass Lighthouse budgets.
* RBAC enforced in UI affordances and validated by API responses.

---

## 10) Risks and mitigations

* **Graph performance** on very large SBOMs → use neighborhood windows and server filters; cap depth.
* **UI/CLI drift** → parity matrix in CI; failing check blocks release.
* **Overfetching** → TanStack caching, cursor‑based endpoints, and strict data‑layer reviews.
* **Scope creep** in Admin → feature‑flag granular sections, ship iteratively.
* **AOC confusion** → constant raw/derived labeling and “view raw” toggles.

---

## 11) Test plan

* **Unit**: hooks and components; data adapters; graph layout utils.
* **E2E**: Playwright flows for triage, simulation→approval→run→explain, admin RBAC.
* **A11y**: axe‑core in CI and manual keyboard checks.
* **Perf**: Lighthouse against seeded data; visual regression on Storybook.
* **Security**: OIDC happy and unhappy paths, CSP violation tests, SSRF resistance for downloads metadata.
* **Resilience**: simulate API timeouts; verify error boundaries and retries.

---

## 12) Non‑goals (this epic)

* No server‑side report authoring engine beyond export templates.
* No proprietary graph database; server remains RESTful with indexed queries.
* No speculative automatic policy changes; all edits remain human‑driven.

---

## 13) Philosophy and guiding principles

* **AOC first**: the UI respects facts vs decisions. Raw content is immutable and visible.
* **Deterministic outcomes**: what you see equals what the Policy Engine produced, with an explanation you can export.
* **Explainability** over cleverness: every badge, color, and status maps to a rule and a source.
* **Parity**: UI is not a second‑class citizen, and the CLI is not an afterthought.
* **Composability**: modules are independent packages with clear contracts and tests.

> Final reminder: **Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.**