stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
79b8e53441e92dbc63684f42072434d40b80275f
git.stella-ops.org/docs/modules/findings-ledger/oas-baseline.md
master 79b8e53441
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Add new features and tests for AirGap and Time modules 
- Introduced `SbomService` tasks documentation.
- Updated `StellaOps.sln` to include new projects: `StellaOps.AirGap.Time` and `StellaOps.AirGap.Importer`.
- Added unit tests for `BundleImportPlanner`, `DsseVerifier`, `ImportValidator`, and other components in the `StellaOps.AirGap.Importer.Tests` namespace.
- Implemented `InMemoryBundleRepositories` for testing bundle catalog and item repositories.
- Created `MerkleRootCalculator`, `RootRotationPolicy`, and `TufMetadataValidator` tests.
- Developed `StalenessCalculator` and `TimeAnchorLoader` tests in the `StellaOps.AirGap.Time.Tests` namespace.
- Added `fetch-sbomservice-deps.sh` script for offline dependency fetching.
2025-11-20 23:29:54 +02:00

2.0 KiB
Raw Blame History

Findings Ledger OAS baseline (v1)

Scope. Establish the canonical OpenAPI baseline and API host definitions for Findings Ledger. This satisfies PREP-LEDGER-OAS-61-001 and unblocks downstream OAS/SDK/OBS tasks (61-002..63-001).

What shipped (2025-11-20).

  • Published baseline OAS document: docs/modules/findings-ledger/openapi/findings-ledger.v1.yaml (OpenAPI 3.0.3).
  • Servers: https://{env}.ledger.api.stellaops.local (env ∈ dev/staging/prod/airgap) and offline https://ledger.{region}.offline.bundle.
  • Security: bearerAuth (JWT) and mTLS declared; tenant header X-Stella-Tenant required.
  • Paths included:
    • GET /v1/ledger/events (deterministic paging by chain/sequence; cursor header).
    • POST /v1/ledger/events (append; validates hashes; 409 on non-deterministic input).
    • GET /v1/ledger/projections/findings (projection read with cycleHash).
  • Schemas align with docs/modules/findings-ledger/schema.md (ledger events, projections, hashes, provenance fields).

Usage / next steps.

  • Export to renderer or client generation from findings-ledger.v1.yaml; keep schema source of truth in YAML, not code-first.
  • Downstream tasks (61-002, 62-001, 63-001) should extend this spec with SDK/validation/deprecation headers but must not change base paths, security schemes, or canonical field names.
  • When new fields are added, update both schema.md and the YAML and bump info.version with changelog entry.

Determinism & offline posture.

  • Stable ordering: events sorted by (chainId, sequence); projections do not perform consensus/merges.
  • No external calls required at runtime; offline host is declared for bundle deployments.
  • Hash fields (eventHash, previousHash, merkleLeafHash, cycleHash) remain lowercase hex SHA-256 per schema.

Artifact locations.

  • OAS YAML: docs/modules/findings-ledger/openapi/findings-ledger.v1.yaml
  • Schema reference: docs/modules/findings-ledger/schema.md
  • Export surface reference (for later OAS extensions): docs/modules/findings-ledger/export-http-surface.md