79b8e53441
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- 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.
29 lines
2.0 KiB
Markdown
29 lines
2.0 KiB
Markdown
# 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`
|