git.stella-ops.org/docs/api/gateway/vex-evidence.md

VEX Evidence Gateway Contract (draft v0.1)

Scope: expose read-only VEX statement and evidence routes through the Web gateway with tenant scoping, deterministic ordering, and export helpers for offline bundles.

Security / headers

• Authorization: Bearer <token> (or DPoP where configured)
• X-Stella-Tenant: <tenantId> (required; see docs/api/gateway/tenant-auth.md)
• X-Stella-Project: <projectId> (optional)
• X-Stella-Trace-Id: <traceId> (optional; clients SHOULD send one)
• Scopes:
  • vex:read for list/detail/evidence
  • vex:export for export handlers

Endpoints

• GET /vex/statements — list statements (tenant-scoped).
  • Query params: vulnId, status, search, limit, continuationToken
• GET /vex/statements/{statementId} — statement detail.
• GET /vex/statements/{statementId}/evidence — evidence links (signed URLs, optional DSSE).
• GET /vex/statements/{statementId}/export?format=json|ndjson|spdx|cyclonedx — export helper returning a signed URL and checksums.

Error codes

Gateway maps upstream/validation errors to stable codes for SDK/UI:

• ERR_AGG_BAD_REQUEST (400)
• ERR_AGG_UNAUTHORIZED (401/403)
• ERR_AGG_NOT_FOUND (404)
• ERR_AGG_RATE_LIMIT (429)
• ERR_AGG_UPSTREAM (5xx)
• ERR_AGG_UNKNOWN (fallback)

Caching & pagination

• limit max: 200.
• Cursor/paging uses continuationToken (opaque string).
• ETag MUST be stable over sorted payload; clients MAY send If-None-Match.

Determinism rules

• Ordering: list responses sorted by (statementId asc) unless specified otherwise; ties break by statementId.
• Timestamps: ISO-8601 UTC.

Samples

• docs/api/gateway/samples/vex-statements-list.json
• docs/api/gateway/samples/vex-statement-detail.json
• docs/api/gateway/samples/vex-evidence-list.json