# ExportCenter OAS Prep — PREP-EXPORT-OAS-61-001

Status: **Ready for implementation** (2025-11-20)
Owners: Exporter Service Guild · API Contracts Guild
Scope: Freeze ExportCenter v1 OpenAPI surface (profiles/runs/downloads) with deterministic headers, ETag/versioning, and standard error envelope.

## Design targets
- Cover the baseline export capabilities required for Wave 160.B: air-gap evidence exports, attestation exports, mirror/bootstrap exports, and discovery.
- Keep payloads deterministic; avoid wall-clock dependence outside stamped fields returned by the service.
- Provide strong cache/discovery signals: `ETag`, `Last-Modified`, `Cache-Control: private, must-revalidate`, plus `/.well-known/openapi` entry.

## Paths to include in v1 spec
- `GET /.well-known/openapi` — returns OpenAPI document with `ETag` and `X-Export-Oas-Version` (value `v1`).
- Evidence exports (portable bundles):
  - `POST /v1/exports/airgap/evidence/{bundleId}` → `202 Accepted` with `exportId`, `status=pending`.
  - `GET /v1/exports/airgap/evidence/{exportId}` → status document (`status`, `rootHash`, `artifactSha256`, `portableVersion`, `downloadUri`).
  - `GET /v1/exports/airgap/evidence/{exportId}/download` → `application/gzip`, filename `export-portable-bundle-v1.tgz`, `ETag` = archive SHA-256.
- Attestation exports:
  - `POST /v1/exports/attestations/{attestationId}` → `202 Accepted` with `exportId`.
  - `GET /v1/exports/attestations/{exportId}` → status + `downloadUri`, `rootHash`, `statementDigest`.
  - `GET /v1/exports/attestations/{exportId}/download` → `application/gzip`, filename `export-attestation-bundle-v1.tgz`, `ETag` = archive SHA-256.
- Mirror/bootstrap (profiles only, no payload schema change):
  - `GET /v1/exports/profiles` — lists available export profiles (e.g., `mirror`, `bootstrap`, `airgap-evidence`, `attestation`). Supports pagination (`limit`, `cursor`) and filtering by `kind`.
  - `GET /v1/exports/runs` — list export runs with status filters, tenant scoping, paging.
- Observability hooks (metadata only):
  - `GET /v1/exports/runs/{exportId}/events` — optional timeline/event stream pointer (when notifications enabled). Can remain `x-stub: true` until envelopes land.

## Components
- **Schemas**
  - `ExportStatus`: `{ exportId, profileId, status: pending|running|completed|failed, artifactSha256, rootHash, portableVersion?, attestationId?, bundleId?, createdAt, completedAt?, downloadUri }`
  - `ExportProfile`: `{ id, kind, description, version, retentionDays }`
  - `ErrorEnvelope`: `{ error: { code, message, correlationId, retryAfterSeconds? } }` with deterministic key order.
- **Security**
  - OAuth2 client credentials; scopes: `export:write` (POST), `export:read` (GET/Download). Tenants enforced via claims.
- **Headers**
  - `ETag` on all download/status responses; `Last-Modified` on status/download reflecting deterministic creation time.
  - Quota headers `X-Stella-Quota-*` retained for consistency with EvidenceLocker/ExportCenter.

## Versioning & determinism
- OAS document served with `version: 1.0.0` and `x-stella-oas-revision` (UTC date string). No inline examples with non-deterministic timestamps; examples use `2025-01-01T00:00:00Z`.
- All example hashes use fixed placeholder `sha256:0123...deadbeef` to keep docs repeatable.

## Deliverables
- Publish OpenAPI YAML at `docs/modules/export-center/openapi/export-center.v1.yaml` matching the paths/schemas above.
- Link the `.yaml` from Sprint 0162 Delivery Tracker P10 and set status to DONE once published.

## Acceptance criteria
- All listed endpoints present in the YAML with request/response schemas and security scopes.
- Deterministic examples (fixed timestamps/hashes) and `ETag`/`Last-Modified` response headers documented.
- `/.well-known/openapi` discovery endpoint described with `ETag` and version headers.

## Next steps
- Generate the YAML (can seed from EvidenceLocker/Orchestrator style) and check into `docs/modules/export-center/openapi/export-center.v1.yaml`.
- Update SDK generator task (62-001) to depend on this OAS once merged.