Restructure solution layout by module
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
This commit is contained in:
root
@@ -1,212 +1,212 @@
|
||||
# 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
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```bash
|
||||
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).*
|
||||
# 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
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```bash
|
||||
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).*
|
||||
|
||||
Reference in New Issue
Block a user