# Export Center Gateway Contract (draft placeholder)

**Status:** Draft v0.2 · owner-proposed

## Scope
- Profile, run, download, and distribution routes proxied via Web gateway.
- Tenant scoping, RBAC/ABAC, streaming limits, retention/encryption parameters, signed URL policy.

## Endpoints
- `GET /export-center/profiles` — list export profiles (tenant-scoped).
- `POST /export-center/runs` — start an export run.
- `GET /export-center/runs/{runId}` — run status and artifacts.
- `GET /export-center/runs/{runId}/events` — SSE for run progress.
- `GET /export-center/distributions/{id}` — fetch signed URLs for OCI/object storage distribution.

## Security / headers
- `Authorization: DPoP <token>`; `DPoP: <proof>`
- `X-StellaOps-Tenant: <tenantId>` (required)
- `X-StellaOps-Project: <projectId>` (optional)
- `Idempotency-Key` (recommended for POST)
- Required scopes (proposal): `export:read`, `export:write`.

## Request: POST /export-center/runs
```jsonc
{
  "profileId": "export-profile::tenant-default::daily-vex",
  "targets": ["vex", "advisory", "policy"],
  "formats": ["json", "ndjson"],
  "distribution": {
    "type": "oci",
    "ref": "registry.local/exports/daily",
    "signing": { "enabled": true, "keyRef": "k8s://secrets/eks/oci-signer" }
  },
  "retentionDays": 30,
  "encryption": { "enabled": true, "kmsKey": "kms://tenant-default/key1" },
  "priority": "normal"
}
```

## Response: 202 Accepted
- `runId`, `status: queued|running|succeeded|failed|expired`, `estimateSeconds`, `retryAfter`.

## Response: GET run
```jsonc
{
  "runId": "export-run::tenant-default::2025-12-06::0003",
  "status": "running",
  "profileId": "export-profile::tenant-default::daily-vex",
  "startedAt": "2025-12-06T10:00:00Z",
  "outputs": [
    { "type": "manifest", "format": "json", "url": "https://exports.local/.../manifest.json?sig=...", "sha256": "...", "expiresAt": "2025-12-06T16:00:00Z" }
  ],
  "progress": { "percent": 35, "itemsCompleted": 70, "itemsTotal": 200 },
  "errors": []
}
```

## SSE events
- `started`, `progress`, `artifact_ready` (url, sha256, type), `completed`, `failed` (code, message).

## Limits (proposal)
- Max request body 256 KiB; max targets 50; default timeout 60 minutes.
- Idle SSE timeout 60s; backoff with `Retry-After`.

## Error codes (proposal)
- `ERR_EXPORT_PROFILE_NOT_FOUND`
- `ERR_EXPORT_REQUEST_INVALID`
- `ERR_EXPORT_TOO_LARGE`
- `ERR_EXPORT_RATE_LIMIT`
- `ERR_EXPORT_DISTRIBUTION_FAILED`

## Samples
- Profile list sample: _todo_
- Run request/response: see above snippets.
- Events NDJSON: _todo_

## Outstanding (for finalization)
- Confirm scopes, limits, distribution signing rules, and manifest checksum requirements.
- Provide full OpenAPI/JSON schema and sample artifacts for OCI/object storage distributions.