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)

{
  "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.
• Record all hashes in src/DevPortal/StellaOps.DevPortal.Site/SHA256SUMS.devportal-stubs (or final SHA file) to keep determinism visible to docs/implplan sprints.

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.