stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

feat: Implement DevPortal Offline Export Job

Browse Source 
- Added DevPortalOfflineJob to coordinate bundle construction, manifest signing, and artifact persistence.
- Introduced DevPortalOfflineWorkerOptions for configuration of the offline export job.
- Enhanced the Worker class to utilize DevPortalOfflineJob and handle execution based on configuration.
- Implemented HmacDevPortalOfflineManifestSigner for signing manifests with HMAC SHA256.
- Created FileSystemDevPortalOfflineObjectStore for storing artifacts in the file system.
- Updated appsettings.json to include configuration options for the DevPortal offline export.
- Added unit tests for DevPortalOfflineJob and HmacDevPortalOfflineManifestSigner to ensure functionality.
- Refactored existing tests to accommodate changes in method signatures and new dependencies.
This commit is contained in:
master
2025-11-05 21:57:46 +02:00
parent c467b4d4b7
commit 21a2759412
20 changed files with 1141 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/modules/export-center/architecture.md
View File

@@ -84,7 +84,8 @@ All endpoints require Authority-issued JWT + DPoP tokens with scopes `export:run
- Supports optional encryption of `/data` subtree (age/AES-GCM) with key wrapping stored in `provenance.json`.
- **DevPortal (`devportal:offline`).**
- Packages developer portal static assets, OpenAPI specs, SDK releases, and changelog content into a reproducible archive with manifest/checksum pairs.
- Emits `manifest.json`, `checksums.txt`, and helper scripts described in [DevPortal Offline Bundle Specification](devportal-offline.md); signing/DSSE wiring follows the shared Export Center signing service.
- Emits `manifest.json`, `checksums.txt`, helper scripts, and a DSSE signature document (`manifest.dsse.json`) as described in [DevPortal Offline Bundle Specification](devportal-offline.md).
- Stores artefacts under `<storagePrefix>/<bundleId>/` and signs manifests via the Export Center signing adapter (HMAC-SHA256 v1, tenant scoped).
Adapters expose structured telemetry events (`adapter.start`, `adapter.chunk`, `adapter.complete`) with record counts and byte totals per chunk. Failures emit `adapter.error` with reason codes.

20
docs/modules/export-center/devportal-offline.md
View File

@@ -81,7 +81,14 @@ root <sha256(manifest.json)>
The `root` value is the SHA-256 hash of the serialized manifest and is exposed separately in the result object for downstream signing.
## 4. Verification script
## 4. DSSE signature and storage
- The export job signs `manifest.json` with an HMAC-SHA256 based DSSE envelope, producing `manifest.dsse.json` alongside the bundle artefacts.
- The signature document captures the bundle identifier, manifest root hash, signing timestamp, algorithm metadata, and the DSSE payload/signature.
- Operators verify the manifest by validating `manifest.dsse.json`, then cross-checking the `payload` base64 with the downloaded manifest and the `rootHash` in `checksums.txt`.
- All artefacts are written under a deterministic storage prefix `<storagePrefix>/<bundleId>/` with the bundle archive stored as `bundle.tgz` (or the configured file name).
## 5. Verification script
`verify-offline.sh` is a POSIX-compatible helper that:
@@ -91,7 +98,7 @@ The `root` value is the SHA-256 hash of the serialized manifest and is exposed s
Operators can override the archive name via the first argument (`./verify-offline.sh mybundle.tgz`).
## 5. Content categories
## 6. Content categories
| Category | Target prefix | Notes |
|-----------|---------------|-------|
@@ -102,14 +109,13 @@ Operators can override the archive name via the first argument (`./verify-offlin
Paths are normalised to forward slashes and guarded against directory traversal.
## 6. Determinism and hashing rules
## 7. Determinism and hashing rules
- Files are enumerated and emitted in ordinal path order.
- SHA-256 digests use lowercase hex encoding.
- Optional directories (specs, SDKs, changelog) are skipped when absent; at least one category must contain files or the builder fails fast.
## 7. Next steps
## 8. Next steps
- Attach DSSE signing + timestamping (`signature.json`) once Export Center signing infrastructure is ready.
- Integrate the builder into the Export Center worker profile (`devportal --offline`) and plumb orchestration/persistence.
- Produce CLI validation tooling (`stella devportal verify`) per DVOFF-64-002 and document operator workflows under `docs/airgap/devportal-offline.md`.
- Expand `stella devportal verify` (DVOFF-64-002) to validate DSSE signatures and bundle integrity offline.
- Document operator workflow under `docs/airgap/devportal-offline.md`.