Advisory Gateway Contract (draft v0.1)

This contract defines a proposed proxy for advisory surfaces through the StellaOps Web gateway: tenant-scoped, deterministic responses with ETag caching and offline-friendly pagination. It is the reference shape for the Console advisory client and offline samples.

Audience: gateway and Console integrators. Read the Status section first — the plain list/detail surface below is a forward design contract, not a live route today.

Status

• Forward design contract — NOT served at this gateway path today. No gateway route table entry maps GET /advisories or GET /advisories/{advisoryId} to a backend; the only consumer of the AdvisoryListResponse / AdvisoryDetail shape described below is the Console client AdvisoryApiHttpClient (src/Web/StellaOps.Web/src/app/core/api/advisories.client.ts), which targets a configurable ADVISORY_API_BASE_URL injection token, plus the offline sample fixtures in samples/. The base URL is currently unwired to a live upstream.
• Live Concelier advisory surface (ground truth, StellaOps.Concelier.WebService/Program.cs):
  • GET /advisories/raw, GET /advisories/raw/{id}, GET /advisories/raw/{id}/provenance
  • GET /advisories/observations, GET /advisories/linksets, GET /advisories/linksets/export
  • GET /advisories/summary, GET /advisories/{advisoryKey}/chunks
  • Canonical advisory service under GET /api/v1/canonical, GET /api/v1/canonical/{id:guid}, POST /api/v1/canonical/ingest/{source} (see Extensions/CanonicalAdvisoryEndpointExtensions.cs).
  • Gateway routes that exist today: ^/advisories/raw(.*) and ^/concelier/advisories/raw(.*) → Concelier, and ^/api/v1/advisory-sources(.*) → Concelier (see GatewayRouteSearchMappingsTests.cs). The plain list/detail contract below is additive and unrouted.
• The field and enum names in this contract are reconciled against the Console models (src/Web/StellaOps.Web/src/app/core/api/advisories.models.ts) and the offline samples; treat them as the canonical shape for the proposed proxy.

Security / headers

• Authorization: Bearer <token> (or DPoP where configured; see docs/api/gateway/tenant-auth.md).
• X-StellaOps-TenantId: <tenantId> (required; see docs/api/gateway/tenant-auth.md).
• X-StellaOps-Project: <projectId> (optional). Header constant StellaOpsHeaders.Project.
• X-StellaOps-TraceId: <traceId> (optional; the Console client always sends one, auto-generated when omitted).
• X-StellaOps-RequestId: <requestId> (the Console client sends this mirroring X-StellaOps-TraceId).
• If-None-Match: <etag> (optional; for conditional GET).
• Scopes: advisory:read (StellaOpsScopes.AdvisoryRead). Ingestion/write surfaces use advisory:ingest (StellaOpsScopes.AdvisoryIngest).

Endpoints

• GET /advisories — list advisories (tenant-scoped).
  • Query params: search, severity, sortBy, sortOrder, limit, continuationToken.
  • severity ∈ critical | high | medium | low | none | unknown.
  • sortBy ∈ updatedAt | publishedAt | severity | advisoryId.
  • sortOrder ∈ asc | desc.
  • Response: AdvisoryListResponse (see fields and sample below).
• GET /advisories/{advisoryId} — advisory detail (tenant-scoped).
  • Response: AdvisoryDetail (see fields and sample below).

Response shapes

Reconciled against advisories.models.ts and the offline samples.

• AdvisoryListResponse:
  • items: AdvisorySummary[]
  • count: number
  • continuationToken: string | null
  • etag?: string
  • traceId?: string
• AdvisorySummary:
  • advisoryId: string
  • source: cve | ghsa | vendor | distro | other
  • title: string
  • severity: critical | high | medium | low | none | unknown
  • publishedAt: string (ISO-8601 UTC)
  • updatedAt?: string
  • cveIds?: string[]
  • affectedPurls?: string[]
  • etag?: string
• AdvisoryDetail extends AdvisorySummary and adds:
  • description?: string
  • references?: { label: string; url: string }[]
  • advisoryUrl?: string

Caching & pagination

• limit max: 200 (enforced client-side as AdvisoryApiHttpClient.MAX_PAGE_SIZE; requests above the cap are rejected before dispatch).
• Cursor/paging uses continuationToken (opaque string); the list response returns the next continuationToken (or null when exhausted).
• ETag MUST be a stable hash over a sorted payload; clients MAY send If-None-Match.
• Recommended headers: Cache-Control: private, max-age=60, stale-if-error=300.

Determinism rules

• Ordering: items sorted by (advisoryId asc) unless sortBy is supplied; ties break by advisoryId.
• Timestamps: ISO-8601 UTC.

Samples

• docs/api/gateway/samples/advisories-list.json
• docs/api/gateway/samples/advisory-detail.json