up

docs/specs/symbols/api.md

@@ -0,0 +1,35 @@
+# Symbol Server API
+
+> **Imposed rule:** All API responses must include tenant scoping and content digests; cross-tenant symbol access is forbidden.
+
+Base path: `/api/v1/symbols` (service: Symbol Server / Export Center plugin).
+
+## Endpoints
+
+- `GET /manifest` – returns `SYMBOL_MANIFEST/v1` for the tenant.
+  - Headers: `X-Stella-Tenant` (required)
+  - Query: `image_digest` (optional filter), `build_id` (exact match)
+- `GET /files/{path}` – stream a symbol file by relative path in manifest.
+  - Headers: `X-Stella-Tenant`
+  - Responds with `Content-SHA256` header and ETag; 404 if tenant mismatch.
+- `POST /ingest` – upload a symbol bundle (tar or OCI artifact) and manifest.
+  - Headers: `X-Stella-Tenant`, `X-Stella-Attestation` (optional DSSE digest)
+  - Validates manifest checksum, entry digests, and tenant.
+- `GET /health` – readiness/liveness.
+
+## Error model
+- Problem+JSON; include `tenant`, `correlation_id`, and `policy` fields when access is denied.
+- Rate limits: `429` with `Retry-After`; deterministic budget per tenant.
+
+## Security
+- Auth via Authority-issued JWT; enforce `symbols:read`/`symbols:write` scopes.
+- Tenant check on every request; manifest tenant must equal header.
+- Optional DSSE attestation digest header is recorded and surfaced in `/manifest` under `source.attestation`.
+
+## Caching & offline
+- Console/CLI cache manifest + files in CAS; revalidate via `If-None-Match` on `GET /manifest`.
+- Offline kits mount symbol bundle read-only; API client can be pointed at `file://` CAS handler for air-gapped use.
+
+## Observability
+- Emit counters per tenant: `symbol_manifest_requests`, `symbol_file_bytes_served`, `symbol_ingest_failures`.
+- Logs include `build_id`, `image_digest`, `tenant`, `attested` flag.