git.stella-ops.org/docs/api/console/search-downloads.md

Console Search and Downloads

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) 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 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

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).

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.

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.

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