up

docs/specs/symbols/SYMBOL_MANIFEST_v1.md

@@ -0,0 +1,80 @@
+# SYMBOL_MANIFEST v1
+
+> **Imposed rule:** Symbol bundles must be content-addressed and tenant-scoped; every manifest entry must include the originating image digest and build-id to prevent cross-tenant leakage.
+
+This document specifies the manifest format for distributing native debug symbols (ELF, PDB, dSYM) within StellaOps Offline Kits and symbol servers.
+
+## 1. Use cases
+- Offline debugging: GDB/LLDB/WinDBG pointing at local symbol server or file tree.
+- Reachability analysis: map call stacks and function addresses to packages for scanner reachability overlays.
+- Forensics: correlate runtime crash dumps to signed builds.
+
+## 2. File layout
+
+```
+symbols/
+  manifest.json          # SYMBOL_MANIFEST v1 (this spec)
+  manifest.json.sha256   # sha256 of manifest.json
+  /.build-id/aa/bbbbb.debug   # ELF split DWARF
+  /.build-id/cc/ddddd.sym     # PE/PDB (optional)
+  /mach-o/<uuid>.dSYM        # Apple dSYM bundle (optional)
+```
+
+## 3. Manifest schema (JSON)
+
+Top-level fields:
+
+```jsonc
+{
+  "schema": "SYMBOL_MANIFEST/v1",
+  "generated_at": "2025-11-26T12:00:00Z",
+  "generator": "stella symbol pack 1.0.0",
+  "tenant": "acme",
+  "entries": [
+    {
+      "image_digest": "sha256:...",          // source image
+      "component": "openssl",                // optional package/name
+      "build_id": "abcdef1234567890",        // GNU build-id or PE GUID
+      "file": ".build-id/ab/cdef.debug",     // relative path inside bundle
+      "format": "elf-debug" ,                // elf-debug | pdb | dsym
+      "arch": "linux/amd64",                 // GOARCH-style
+      "size": 123456,                          // bytes
+      "sha256": "sha256:...",                // file digest
+      "source": {
+        "kind": "ci" | "vendor" | "runtime-capture",
+        "pipeline": "https://ci.example/pipeline/123", // optional
+        "attestation": "sha256:..."           // DSSE bundle digest (optional)
+      }
+    }
+  ]
+}
+```
+
+Constraints:
+- `schema` must be exactly `SYMBOL_MANIFEST/v1`.
+- Entries sorted by `build_id` then `file` to keep deterministic ordering.
+- `tenant` required; manifests are not shareable across tenants.
+
+## 4. Validation
+- Verify `manifest.json.sha256` matches `manifest.json`.
+- For each entry, hash the referenced file and compare to `sha256`.
+- Ensure `build_id` path matches file location (for ELF: `/.build-id/<aa>/<rest>.debug`).
+- When attestation is present, validate the DSSE bundle before serving symbols.
+
+## 5. Transport
+- OCI artifact (recommended): media type `application/vnd.stella.symbols.manifest.v1+json`; symbols packed as a tar layer with manifest at root.
+- File archive: deterministic `tar.gz` with POSIX `ustar`, sorted entries, UTC mtimes set to `0`.
+- Export Center mirrors symbol bundles alongside SBOM/attestation bundles for air-gapped installs.
+
+## 6. Tenant controls
+- Symbol server enforces tenant header `X-Stella-Tenant`; manifests without matching tenant are rejected.
+- Offline bundles carry tenant in manifest; Console warns if loading mismatched tenant.
+
+## 7. Versioning
+- Future versions add optional fields; parsers must ignore unknown fields.
+- Breaking changes will bump to `SYMBOL_MANIFEST/v2`.
+
+## 8. References
+- `docs/24_OFFLINE_KIT.md` (debug store expectations)
+- `docs/benchmarks/signals/bench-determinism.md`
+- `docs/modules/scanner/architecture.md` (reachability + symbol linkage)

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.

docs/specs/symbols/bundle-guide.md

@@ -0,0 +1,39 @@
+# Symbol Bundle Guide
+
+This guide explains how to package, validate, and distribute symbol bundles that comply with `SYMBOL_MANIFEST/v1`.
+
+## 1. Packaging steps
+1. Gather debug artifacts (ELF `.debug`, PDB, dSYM) for the target release.
+2. Compute `sha256` for each file and record size/arch/format.
+3. Build `manifest.json` as per `SYMBOL_MANIFEST_v1.md`; sort entries by `build_id`, then `file`.
+4. Write `manifest.json.sha256` with the hex digest of `manifest.json`.
+5. Create a deterministic tarball:
+   - POSIX ustar
+   - Sorted file order
+   - `mtime=0`, `uid=gid=0`, `uname=guname=root`
+   - Compression: gzip `-n` to avoid timestamps
+6. Optional: wrap as OCI artifact with media type `application/vnd.stella.symbols.manifest.v1+json`.
+
+## 2. Validation checklist
+- [ ] `manifest.json` hashes to `manifest.json.sha256`.
+- [ ] Each file hash matches manifest entry.
+- [ ] Build-id path structure is correct (ELF `.build-id/aa/<rest>.debug`).
+- [ ] Tenant in manifest matches upload tenant.
+- [ ] Tarball ordering is lexicographic and mtimes are zeroed.
+
+## 3. Ingestion (API)
+- POST the tar/OCI blob to `/api/v1/symbols/ingest` with header `X-Stella-Tenant`.
+- Server recomputes digests; rejects mismatches or tenant mismatch.
+- Optional DSSE attestation digest recorded in manifest for downstream verification.
+
+## 4. Reachability integration
+- Scanner attaches `build_id` and source image digest to reachability edges; Graph API can fetch symbol manifests to render function names in overlays.
+- When symbols are missing, UI shows “symbol lookup unavailable” badge; import the matching manifest to enable function-level overlays.
+
+## 5. Offline kits
+- Place `symbols/` directory (manifest + files) at the kit root; include tarball and manifest digest.
+- `debug-manifest.json` in Offline Kit should link to symbol manifest for cross-reference.
+
+## 6. Tenant controls & audit
+- Symbol server enforces tenant; exports are tagged with tenant in manifest and tar annotations.
+- Emit Timeline events on ingest with bundle digest and tenant; attach DSSE attestation if present.