StellaOps Console - Downloads Manager

Audience: DevOps guild, Console engineers, enablement writers, and operators who promote releases or maintain offline mirrors.
Scope: /console/downloads workspace covering artifact catalog, signed manifest plumbing, export status handling, CLI parity, automation hooks, and offline guidance (Sprint 23).

The Downloads workspace centralises every artefact required to deploy or validate StellaOps in connected and air-gapped environments. It keeps Console operators aligned with release engineering by surfacing the signed downloads manifest, live export jobs, parity checks against Offline Kit bundles, and automation hooks that mirror the CLI experience.

1 - Access and prerequisites

Route: /console/downloads (list) with detail drawer /console/downloads/:artifactId.
Scopes: downloads.read (baseline) and downloads.manage for cancelling or expiring stale exports. Evidence bundles inherit the originating scope (runs.read, findings.read, etc.).
Dependencies: Web gateway /console/downloads API (WEB-CONSOLE-23-005), DevOps manifest pipeline (deploy/downloads/manifest.json), Offline Kit metadata (manifest/offline-manifest.json), and export orchestrator /console/exports.
Feature flags: downloads.workspace.enabled, downloads.exportQueue, downloads.offlineParity.
Tenancy: Artefacts are tenant-agnostic except evidence bundles, which are tagged with originating tenant and require matching Authority scopes.

2 - Workspace layout

+---------------------------------------------------------------+
| Header: Snapshot timestamp - Manifest signature status        |
+---------------------------------------------------------------+
| Cards: Latest release - Offline kit parity - Export queue     |
+---------------------------------------------------------------+
| Tabs: Artefacts | Exports | Offline Kits | Webhooks           |
+---------------------------------------------------------------+
| Filter bar: Channel - Kind - Architecture - Scope tags        |
+---------------------------------------------------------------+
| Table (virtualised): Artifact | Channel | Digest | Status     |
| Detail drawer: Metadata | Commands | Provenance | History     |
+---------------------------------------------------------------+

Snapshot banner: shows manifest.version, generatedAt, and cosign verification state. If verification fails, the banner turns red and links to troubleshooting guidance.
Quick actions: Copy manifest URL, download attestation bundle, trigger parity check, open CLI parity doc (/docs/cli-vs-ui-parity.md).
Filters: allow narrowing by channel (edge, stable, airgap), artefact kind (container.image, helm.chart, compose.bundle, offline.bundle, export.bundle), architecture (linux/amd64, linux/arm64), and scope tags (console, scheduler, authority).

3 - Artefact catalogue

Category	Artefacts surfaced	Source	Notes
Core containers	`stellaops/web-ui`, `stellaops/web`, `stellaops/concelier`, `stellaops/excititor`, `stellaops/scanner-`, `stellaops/authority`, `stellaops/attestor`, `stellaops/scheduler-`	`deploy/downloads/manifest.json` (`artifacts[].kind = "container.image"`)	Digest-only pulls with copy-to-clipboard `docker pull` and `oras copy` commands; badges show arch availability.
Helm charts	`deploy/helm/stellaops-*.tgz` plus values files	Manifest entries where `kind = "helm.chart"`	Commands reference `helm repo add` (online) and `helm install --values` (offline). UI links to values matrix in `/docs/install/helm-prod.md` when available.
Compose bundles	`deploy/compose/docker-compose.*.yaml`, `.env` seeds	`kind = "compose.bundle"`	Inline diff viewer highlights digest changes vs previous snapshot; `docker compose pull` command copies digest pins.
Offline kit	`stella-ops-offline-kit-<ver>-<channel>.tar.gz` + signatures and manifest	Offline Kit metadata (`manifest/offline-manifest.json`) merged into downloads view	Drawer shows bundle size, signed manifest digest, cosign verification command (mirrors `/docs/24_OFFLINE_KIT.md`).
Evidence exports	Completed jobs from `/console/exports` (findings delta, policy explain, run evidence)	Export orchestrator job queue	Entries expire after retention window; UI exposes `stella runs export` and `stella findings export` parity buttons.
Webhooks & parity	`/downloads/hooks/subscribe` configs, CI parity reports	Manifest extras (`kind = "webhook.config"`, `kind = "parity.report"`)	Operators can download webhook payload templates and review the latest CLI parity check report generated by docs CI.

4 - Manifest structure

The DevOps pipeline publishes a deterministic manifest at deploy/downloads/manifest.json, signed with the release Cosign key (DOWNLOADS-CONSOLE-23-001). The Console fetches it on workspace load and caches it with If-None-Match headers to avoid redundant pulls. The manifest schema:

version - monotonically increasing integer tied to pipeline run.
generatedAt - ISO-8601 UTC timestamp.
signature - URL to detached Cosign signature (manifest.json.sig).
artifacts[] - ordered list keyed by id.

Each artefact contains:

Field	Description
`id`	Stable identifier (`<type>:<name>:<version>`).
`kind`	One of `container.image`, `helm.chart`, `compose.bundle`, `offline.bundle`, `export.bundle`, `webhook.config`, `parity.report`.
`channel`	`edge`, `stable`, or `airgap`.
`version`	Semantic or calendar version (for containers, matches release manifest).
`architectures`	Array of supported platforms (empty for arch-agnostic artefacts).
`digest`	SHA-256 for immutable artefacts; Compose bundles include file hash.
`sizeBytes`	File size (optional for export bundles that stream).
`downloadUrl`	HTTPS endpoint (registry, object store, or mirror).
`signatureUrl`	Detached signature (Cosign, DSSE, or attestation) if available.
`sbomUrl`	Optional SBOM pointer (CycloneDX JSON).
`attestationUrl`	Optional in-toto/SLSA attestation.
`docs`	Array of documentation links (e.g., `/docs/install/docker.md`).
`tags`	Free-form tags (e.g., `["console","ui","offline"]`).

4.1 Example excerpt

{
  "version": 42,
  "generatedAt": "2025-10-27T04:00:00Z",
  "signature": "https://downloads.stella-ops.org/manifest/manifest.json.sig",
  "artifacts": [
    {
      "id": "container.image:web-ui:2025.10.0-edge",
      "kind": "container.image",
      "channel": "edge",
      "version": "2025.10.0-edge",
      "architectures": ["linux/amd64", "linux/arm64"],
      "digest": "sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
      "sizeBytes": 187563210,
      "downloadUrl": "https://registry.stella-ops.org/v2/stellaops/web-ui/manifests/sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
      "signatureUrl": "https://downloads.stella-ops.org/signatures/web-ui-2025.10.0-edge.cosign.sig",
      "sbomUrl": "https://downloads.stella-ops.org/sbom/web-ui-2025.10.0-edge.cdx.json",
      "attestationUrl": "https://downloads.stella-ops.org/attestations/web-ui-2025.10.0-edge.intoto.jsonl",
      "docs": ["/docs/install/docker.md", "/docs/security/console-security.md"],
      "tags": ["console", "ui"]
    },
    {
      "id": "offline.bundle:ouk:2025.10.0-edge",
      "kind": "offline.bundle",
      "channel": "edge",
      "version": "2025.10.0-edge",
      "digest": "sha256:4f7d2f7a8d0cf4b5f3af689f6c74cd213f4c1b3a1d76d24f6f9f3d9075e51f90",
      "downloadUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz",
      "signatureUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig",
      "sbomUrl": "https://downloads.stella-ops.org/offline/offline-manifest-2025.10.0-edge.json",
      "docs": ["/docs/24_OFFLINE_KIT.md"],
      "tags": ["offline", "airgap"]
    }
  ]
}

Console caches the manifest hash and surfaces differences when a new version lands, helping operators confirm digests drift only when expected.

5 - Download workflows and statuses

Status	Applies to	Behaviour
Ready	Immutable artefacts (images, Helm/Compose bundles, offline kit)	Commands available immediately. Digest, size, and last verification timestamp display in the table.
Pending export	Async exports queued via `/console/exports`	Shows job owner, scope, and estimated completion time. UI polls every 15 s and updates progress bar.
Processing	Long-running export (evidence bundle, large SBOM)	Drawer shows current stage (`collecting`, `compressing`, `signing`). Operators can cancel if they own the request and hold `downloads.manage`.
Delivered	Completed export within retention window	Provides download links, resume token, and parity snippet for CLI.
Expired	Export past retention or manually expired	Row grays out; clicking opens housekeeping guidance with CLI command to regenerate (`stella runs export --run <id>`).

Exports inherit retention defaults defined in policy (downloads.retentionDays, min 3, max 30). Operators can override per tenant if they have the appropriate scope.

6 - CLI parity and copy-to-clipboard

Digest pulls: Each container entry exposes docker pull <image>@<digest> and oras copy <image>@<digest> --to-dir ./downloads buttons. Commands include architecture hints for multi-platform images.
Helm/Compose: Buttons output helm pull / helm install with the manifest URL and docker compose --env-file commands referencing the downloaded bundle.
Offline kit: Copy buttons produce the full verification sequence:

curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz
curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig
cosign verify-blob \
  --key https://stella-ops.org/keys/cosign.pub \
  --signature stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig \
  stella-ops-offline-kit-2025.10.0-edge.tar.gz

Exports: Drawer lists CLI equivalents (for example, stella findings export --run <id>). When the CLI supports resume tokens, the command includes --resume-token from the manifest entry.
Automation: Webhook tab copies curl snippets to subscribe to /downloads/hooks/subscribe?topic=<artifact> and includes payload schema for integration tests.

Parity buttons write commands to the clipboard and display a toast confirming scope hints (for example, Requires downloads.read + tenant scope). Accessibility shortcuts (Shift+D) trigger the primary copy action for keyboard users.

7 - Offline and air-gap workflow

Manifest sync: Offline users download manifest/offline-manifest.json plus detached JWS and import it via stella offline kit import. Console highlights if the offline manifest predates the online manifest by more than 7 days.
Artefact staging: The workspace enumerates removable media instructions (export to ./staging/<channel>/) and warns when artefacts exceed configured media size thresholds.
Mirrors: Buttons copy oras copy commands that mirror images to an internal registry (registry.<tenant>.internal). Operators can toggle --insecure-policy if the destination uses custom trust roots.
Parity checks: downloads.offlineParity flag surfaces the latest parity report verifying that Offline Kit contents match the downloads manifest digests. If diff detected, UI raises a banner linking to remediation steps.
Audit logging: Every download command triggered from the UI emits ui.download.commandCopied with artifact ID, digest, and tenant. Logs feed the evidence locker so air-gap imports can demonstrate provenance.

8 - Observability and quotas

Signal	Source	Description
`ui_download_manifest_refresh_seconds`	Console metrics	Measures time to fetch and verify manifest. Targets < 3 s.
`ui_download_export_queue_depth`	`/console/downloads` API	Number of pending exports (per tenant). Surfaces as card and Grafana panel.
`ui_download_command_copied_total`	Console logs	Count of copy actions by artifact type, used to gauge CLI parity adoption.
`downloads.export.duration`	Export orchestrator	Duration histograms for bundle generation; alerts if P95 > 60 s.
`downloads.quota.remaining`	Authority quota service	Anonymous users limited to 33 exports/day, verified users 333/day. Banner turns amber at 90 % usage as per platform policy.

Telemetry entries include correlation IDs that match backend manifest refresh logs and export job records to keep troubleshooting deterministic.

9 - References

/docs/ui/console-overview.md - primary shell, tenant controls, SSE ticker.
/docs/ui/navigation.md - route ownership and keyboard shortcuts.
/docs/ui/sbom-explorer.md - export flows feeding the downloads queue.
/docs/ui/runs.md - evidence bundle integration.
/docs/24_OFFLINE_KIT.md - offline kit packaging and verification.
/docs/security/console-security.md - scopes, CSP, and download token handling.
/docs/cli-vs-ui-parity.md - CLI equivalence checks (pending).
deploy/releases/*.yaml - source of container digests mirrored into the manifest.

10 - Compliance checklist

[ ] Manifest schema documented (fields, signature, caching) and sample kept current.
[ ] Artefact categories mapped to manifest entries and parity workflows.
[ ] Download statuses, retention, and cancellation rules explained.
[ ] CLI copy-to-clipboard commands mirror console actions with scope hints.
[ ] Offline/air-gap parity workflow, mirror commands, and audit logging captured.
[ ] Observability metrics and quota signalling documented.
[ ] References cross-linked to adjacent docs (navigation, exports, offline kit).
[ ] Accessibility shortcuts and copy-to-clipboard behaviour noted with compliance reminder.

Last updated: 2025-10-27 (Sprint 23).