docs consolidation
This commit is contained in:
StellaOps Bot
@@ -1,58 +1,57 @@
|
||||
# Console Search & Downloads · Draft v0.2
|
||||
# Console Search and Downloads
|
||||
|
||||
Scope: unblock WEB-CONSOLE-23-004/005 by defining deterministic ranking, caching rules, and the download manifest structure (including signed metadata option) for console search and offline bundle downloads. Final guild sign-off still required.
|
||||
This document defines deterministic ranking, caching rules, and the download manifest shape used by Console search and export-style workflows.
|
||||
|
||||
## 1) Deterministic search ranking
|
||||
- Primary sort: `severity (desc)` → `exploitScore (desc)` → `reachability (reachable > unknown > unreachable)` → `policyBadge (fail > warn > pass > waived)` → `vexState (under_investigation > fixed > not_affected > unknown)` → `findingId (asc)`.
|
||||
- Secondary tie-breakers (when above fields absent): `advisoryId (asc)` then `product (asc)`.
|
||||
- All pages are pre-sorted server-side; clients MUST NOT re-order.
|
||||
- Primary sort: `severity (desc)` then `exploitScore (desc)` then `reachability (reachable > unknown > unreachable)` then `policyBadge (fail > warn > pass > waived)` then `vexState (under_investigation > fixed > not_affected > unknown)` then `findingId (asc)`.
|
||||
- Secondary tie-breakers (when primary fields are absent): `advisoryId (asc)` then `product (asc)`.
|
||||
- Pages are pre-sorted server-side; clients MUST NOT re-order results.
|
||||
|
||||
## 2) Caching + freshness
|
||||
- Response headers: `Cache-Control: public, max-age=300, stale-while-revalidate=60, stale-if-error=300`.
|
||||
- `ETag` is a stable SHA-256 over the sorted payload; clients send `If-None-Match` for revalidation.
|
||||
- `Last-Modified` reflects the newest `updatedAt` in the result set.
|
||||
- Retry/backoff guidance: honor `Retry-After` when present; default client backoff `1s,2s,4s,8s` capped at 30s.
|
||||
- Deterministic page cursors: opaque base64url, signed; include `sortKeys` and `tenant` to avoid cross-tenant reuse.
|
||||
## 2) Caching and freshness
|
||||
- Response headers (recommended defaults): `Cache-Control: private, max-age=300, stale-while-revalidate=60, stale-if-error=300`.
|
||||
- `ETag` SHOULD be a stable SHA-256 over a canonicalized, sorted payload so identical inputs produce identical validators; clients send `If-None-Match` for revalidation.
|
||||
- `Last-Modified` SHOULD reflect the newest `updatedAt` present in the result set.
|
||||
- Retry/backoff: honor `Retry-After` when present; otherwise use deterministic client backoff (for example `1s, 2s, 4s, 8s` capped at 30s).
|
||||
- Page cursors: opaque base64url, signed; bind to `tenant` and effective sort keys to avoid cross-tenant or cross-sort reuse.
|
||||
|
||||
## 3) Download manifest (for `/console/downloads` and export outputs)
|
||||
Top-level:
|
||||
```jsonc
|
||||
{
|
||||
"version": "2025-12-07",
|
||||
"exportId": "console-export::tenant-default::2025-12-07::0009",
|
||||
"tenantId": "tenant-default",
|
||||
"generatedAt": "2025-12-07T10:15:00Z",
|
||||
"items": [
|
||||
{
|
||||
"type": "vuln", // advisory|vex|policy|scan|chart|bundle
|
||||
"id": "CVE-2024-12345",
|
||||
"format": "json",
|
||||
"url": "https://downloads.local/exports/0009/vuln/CVE-2024-12345.json?sig=...",
|
||||
"sha256": "f1c5…",
|
||||
"size": 18432
|
||||
}
|
||||
],
|
||||
"checksums": {
|
||||
"manifest": "sha256:8bbf…",
|
||||
"bundle": "sha256:12ae…" // optional when a tar/zip bundle is produced
|
||||
},
|
||||
"expiresAt": "2025-12-14T10:15:00Z"
|
||||
}
|
||||
```
|
||||
## 3) Download manifest
|
||||
When a Console workflow produces downloadable artifacts (individual documents or a bundle), services can return a manifest describing:
|
||||
- What items are available,
|
||||
- Where to download them (signed URLs or gateway-relative links),
|
||||
- How to verify them offline (checksums and optional signature metadata).
|
||||
|
||||
### 3.1 Signed metadata
|
||||
- Optional DSSE envelope for `checksums.manifest`, using `sha256` digest and `application/json` payload type `stellaops.console.manifest`.
|
||||
- Envelope is attached as `manifest.dsse` or provided via `Link: <...>; rel="alternate"; type="application/dsse+json"`.
|
||||
- Signers: Authority-issued short-lived key scoped to `console:export`.
|
||||
Top-level fields:
|
||||
- `version` (string): manifest schema/version label used by the producer.
|
||||
- `exportId` (string): stable export identifier (content-addressable or run-id style).
|
||||
- `tenantId` (string): tenant scope for this export.
|
||||
- `generatedAt` (RFC 3339 / ISO-8601 UTC): generation timestamp.
|
||||
- `items[]` (array): downloadable artifacts.
|
||||
- `checksums` (object): checksum(s) for the manifest itself and optional bundle artifact.
|
||||
- `expiresAt` (RFC 3339 / ISO-8601 UTC): optional expiry for signed URLs.
|
||||
|
||||
### 3.2 Error handling
|
||||
- Known error codes: `ERR_CONSOLE_DOWNLOAD_INVALID_CURSOR`, `ERR_CONSOLE_DOWNLOAD_EXPIRED`, `ERR_CONSOLE_DOWNLOAD_RATE_LIMIT`, `ERR_CONSOLE_DOWNLOAD_UNAVAILABLE`.
|
||||
- On error, respond with deterministic JSON body including `requestId` and `retryAfterSeconds` when applicable.
|
||||
Item fields:
|
||||
- `type` (string): artifact type (for example `vuln`, `vex`, `policy`, `scan`, `bundle`).
|
||||
- `id` (string): stable identifier within the type (CVE id, statement id, export id, etc).
|
||||
- `format` (string): `json`, `ndjson`, `tar.gz`, etc.
|
||||
- `url` (string): download URL (often signed).
|
||||
- `sha256` (string): lowercase hex digest of the bytes at `url`.
|
||||
- `size` (int): byte size.
|
||||
|
||||
## 4) Sample manifest
|
||||
- `docs/api/console/samples/console-download-manifest.json` illustrates the exact shape above.
|
||||
### Signed metadata (optional)
|
||||
Producers MAY ship a DSSE envelope for the manifest checksum:
|
||||
- Payload type: `stellaops.console.manifest`
|
||||
- Media type: `application/json`
|
||||
- Distribution: alongside the manifest (for example `manifest.dsse`) or via a link relation (for example `rel=\"alternate\"` with `type=\"application/dsse+json\"`).
|
||||
|
||||
## 4) Error handling
|
||||
Known error codes for download/manifest flows:
|
||||
- `ERR_CONSOLE_DOWNLOAD_INVALID_CURSOR`
|
||||
- `ERR_CONSOLE_DOWNLOAD_EXPIRED`
|
||||
- `ERR_CONSOLE_DOWNLOAD_RATE_LIMIT`
|
||||
- `ERR_CONSOLE_DOWNLOAD_UNAVAILABLE`
|
||||
|
||||
On error, return the standard error envelope with deterministic fields (stable code/message, plus request/trace identifiers).
|
||||
|
||||
## 5) Samples and fixtures
|
||||
- Download manifest example: `docs/api/console/samples/console-download-manifest.json`
|
||||
|
||||
## 5) Open items for guild sign-off
|
||||
- Final TTL values for `max-age` and `stale-*`.
|
||||
- Whether DSSE envelope is mandatory for sealed tenants.
|
||||
- Maximum bundle size / item count caps (proposal: 1000 items, 500 MiB compressed per export).
|
||||
|
||||
Reference in New Issue
Block a user