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.