up

docs/modules/export-center/devportal-offline-manifest.md

@@ -0,0 +1,74 @@
+# DevPortal Offline Bundle Manifest (draft v0.1)
+
+Applies to sprint: SPRINT_0206_0001_0001_devportal · Action #2 (DEVPORT-64-001/64-002 interlock with Export Center)
+
+## Purpose
+- Define a deterministic, air-gap-friendly manifest for Developer Portal offline bundles.
+- Ensure SDK archives, OpenAPI specs, and static site assets can be verified and consumed by Export Center and SDK Release pipelines.
+
+## Bundle layout
+```
+devportal-offline/
+  manifest.json              # see schema below
+  site/                      # static HTML/CSS/JS (Astro/Starlight build)
+  specs/
+    stella-aggregate.yaml    # merged OpenAPI used by portal
+    *.yaml                   # per-service OpenAPI (authority, scanner, policy, graph, etc.)
+  sdks/
+    node-sdk.tar.gz
+    python-sdk.tar.gz
+    java-sdk.zip             # optional, language-dependent
+  assets/
+    fonts/*                  # self-hosted; no external CDNs
+    icons/*                  # SVG/PNG used by site
+```
+
+## Manifest schema (manifest.json)
+```json
+{
+  "version": "0.1",
+  "generatedAt": "2025-11-26T00:00:00Z",
+  "site": {
+    "path": "site",
+    "sha256": "<hex>",
+    "bytes": 0
+  },
+  "specs": [
+    { "name": "stella-aggregate.yaml", "path": "specs/stella-aggregate.yaml", "sha256": "<hex>", "bytes": 0 },
+    { "name": "authority.yaml", "path": "specs/authority.yaml", "sha256": "<hex>", "bytes": 0 }
+  ],
+  "sdks": [
+    { "name": "node-sdk", "path": "sdks/node-sdk.tar.gz", "sha256": "<hex>", "bytes": 0 },
+    { "name": "python-sdk", "path": "sdks/python-sdk.tar.gz", "sha256": "<hex>", "bytes": 0 }
+  ],
+  "checks": {
+    "integrity": "sha256",
+    "policy": "no-external-assets"
+  }
+}
+```
+
+### Rules
+- `version` is additive; bump on breaking shape change.
+- `sha256` is hex lowercase of the file contents.
+- `bytes` is the exact byte length for deterministic validation.
+- `checks.policy` documents applied constraints; default `no-external-assets` (verify no `http(s)://` fonts/scripts).
+
+## Production contract
+- Export Center expects `manifest.json` at bundle root; validates sha256/bytes before publishing.
+- Offline bundle must build via `npm run build:offline` without network calls after initial `npm ci` + `npm run sync:spec`.
+- Specs and SDK archives are treated as opaque; manifest carries their hashes for downstream verification.
+
+## Open items
+- Add per-language SDK metadata (version, commit SHA) once SDKREL-64-002 finalises.
+- Add optional `signatures` array (DSSE over manifest) when Authority signing profile is ready.
+
+## How to produce locally (deterministic)
+```
+npm ci --ignore-scripts --no-fund --no-audit
+npm run sync:spec
+npm run build:offline
+# compute manifest hashes using sha256sum and fill manifest.json
+```
+
+Record generated manifest in sprint evidence when produced; keep caches local to avoid external fetches.

docs/modules/export-center/mirror-bundles.md

@@ -180,22 +180,38 @@ sequenceDiagram
   3. Re-run integrity checks (`mirror verify <path>`).
 - **Audit logging:** Export Center logs `mirror.bundle.created`, `mirror.delta.applied`, and `mirror.encryption.enabled` events. Consume them in the central observability pipeline.
 
-## 7. Troubleshooting
-
-| Symptom | Meaning | Action |
-|---------|---------|--------|
-| `ERR_EXPORT_BASE_MISSING` | Base export not available | Republish base bundle or rebuild as full export. |
-| Delta applies but mirror misses entries | Deltas applied out of order | Rebuild from last full bundle and reapply in sequence. |
+## 7. Validation checklist (Trivy / mirror bundles)
+
+- Download and verify:
+  - `stella export download <exportId> --format mirror`
+  - `stella export verify <exportId>`
+- Delta ordering:
+  - Ensure `manifest.diff.json.baseExportId` exists locally before applying delta.
+  - Track applied order in `appliedExportIds.log`.
+- Trivy adapter (if enabled):
+  - `stella export trivy-validate --bundle mirror-YYYYMMDD.tar.zst --policy ./policies/export-center.rego`
+- Dry-run import:
+  - `stella export mirror-validate --bundle mirror-YYYYMMDD.tar.zst --dry-run`
+- Post-import checks:
+  - Recompute SHA256 for `manifest.yaml` and a sample data file; compare to manifest.
+  - Run `mirror verify` (Offline Kit) and confirm zero mismatches.
+
+## 8. Troubleshooting
+
+| Symptom | Meaning | Action |
+|---------|---------|--------|
+| `ERR_EXPORT_BASE_MISSING` | Base export not available | Republish base bundle or rebuild as full export. |
+| Delta applies but mirror misses entries | Deltas applied out of order | Rebuild from last full bundle and reapply in sequence. |
 | Decryption fails | Recipient key mismatch or corrupted bundle | Confirm key distribution and re-download bundle. |
-| Verification errors | Signature mismatch | Do not import; regenerate bundle and investigate signing pipeline. |
-| Manifest hash mismatch | Files changed after extraction | Re-extract bundle and re-run verification; check storage tampering. |
-
-## 8. References
-
-- [Export Center Overview](overview.md)
-- [Export Center Architecture](architecture.md)
-- [Export Center API reference](api.md)
-- [Export Center CLI Guide](cli.md)
+| Verification errors | Signature mismatch | Do not import; regenerate bundle and investigate signing pipeline. |
+| Manifest hash mismatch | Files changed after extraction | Re-extract bundle and re-run verification; check storage tampering. |
+
+## 9. References
+
+- [Export Center Overview](overview.md)
+- [Export Center Architecture](architecture.md)
+- [Export Center API reference](api.md)
+- [Export Center CLI Guide](cli.md)
 - [Concelier mirror runbook](../concelier/operations/mirror.md)
 - [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md)