# 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-StellaOps-Tenant: <tenantId>` (required)
- `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`