feat: Implement Filesystem and MongoDB provenance writers for PackRun execution context
Some checks failed
Airgap Sealed CI Smoke / sealed-smoke (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled

- Added `FilesystemPackRunProvenanceWriter` to write provenance manifests to the filesystem.
- Introduced `MongoPackRunArtifactReader` to read artifacts from MongoDB.
- Created `MongoPackRunProvenanceWriter` to store provenance manifests in MongoDB.
- Developed unit tests for filesystem and MongoDB provenance writers.
- Established `ITimelineEventStore` and `ITimelineIngestionService` interfaces for timeline event handling.
- Implemented `TimelineIngestionService` to validate and persist timeline events with hashing.
- Created PostgreSQL schema and migration scripts for timeline indexing.
- Added dependency injection support for timeline indexer services.
- Developed tests for timeline ingestion and schema validation.
This commit is contained in:
StellaOps Bot
2025-11-30 15:38:14 +02:00
parent 8f54ffa203
commit 17d45a6d30
276 changed files with 8618 additions and 688 deletions

View File

@@ -0,0 +1,53 @@
# Export Center · AGENTS Charter (Sprint 0164-0001-0001)
## Module Scope & Working Directory
- Working directory: `src/ExportCenter/**` (API/WebService, Worker, Core/Infrastructure libs, Trivy/Mirror/DevPortal adapters, RiskBundles pipeline, tests, seed/config). Cross-module edits require an explicit note in the sprint Decisions & Risks.
- Mission: produce deterministic evidence exports (JSON, Trivy DB, mirror/delta, devportal offline) with provenance, signing, and distribution (HTTP, OCI, object) that remain offline-friendly and tenant-safe.
## Roles
- **Backend engineer (.NET 10 / ASP.NET Core):** API surface, planner/run lifecycle, RBAC/tenant guards, SSE events, download endpoints.
- **Adapter engineer:** Trivy DB/Java DB, mirror delta, OCI distribution, encryption/KMS wrapping, pack-run integration.
- **Worker/Concurrency engineer:** job leasing, retries/idempotency, retention pruning, scheduler hooks.
- **Crypto/Provenance steward:** signing, DSSE/in-toto, age/AES-GCM envelope handling, provenance schemas.
- **QA automation:** WebApplicationFactory + Mongo/Mongo2Go fixtures, adapter regression harnesses, determinism checks, offline-kit verification scripts.
- **Docs steward:** keep `docs/modules/export-center/*.md`, sprint Decisions & Risks, and CLI docs aligned with behavior.
## Required Reading (treat as read before setting DOING)
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/export-center/architecture.md`
- `docs/modules/export-center/profiles.md`
- `docs/modules/export-center/trivy-adapter.md` (for 36-001/36-002)
- `docs/modules/export-center/mirror-bundles.md` (for 37-001/37-002)
- `docs/modules/export-center/provenance-and-signing.md`
- `docs/modules/export-center/operations/kms-envelope-pattern.md` (for 37-002 encryption/KMS)
- Sprint file `docs/implplan/SPRINT_0164_0001_0001_exportcenter_iii.md`
## Working Agreements
- Enforce tenant scoping and RBAC on every API, worker fetch, and distribution path; no cross-tenant exports unless explicitly whitelisted and logged.
- Maintain determinism: sorted outputs, canonical JSON, UTC RFC3339 timestamps, stable hashing; identical selectors yield identical manifests.
- Offline-first: avoid new external calls; OCI distribution must be feature-flagged/disable-able for air-gap; tests must not reach the network.
- Aggregation-Only Contract for evidence: no derived modifications; policy outputs stay separate and clearly labeled.
- Concurrency: default per-tenant run caps (4 active) and idempotent retries; cooperative cancellation must clean partial artefacts and audit outcome.
- Cross-module changes (Authority/Orchestrator/CLI) only when sprint explicitly covers them; log in Decisions & Risks.
## Coding & Observability Standards
- Target **.NET 10** with curated `local-nugets/`; MongoDB driver ≥ 3.x; ORAS/OCI client where applicable.
- Metrics under `StellaOps.ExportCenter.*`; tag `tenant`, `profile`, `adapter`, `result`; document new counters/histograms.
- Logs structured, no PII; include `runId`, `tenant`, `profile`, `adapter`, `correlationId`; map phases (`plan`, `resolve`, `adapter`, `manifest`, `sign`, `distribute`).
- SSE/telemetry events must be deterministic and replay-safe; backpressure aware.
- Signing/encryption: default cosign-style KMS signing; age/AES-GCM envelopes with key wrapping; store references in provenance only (no raw keys).
## Testing Rules
- API/worker tests: `StellaOps.ExportCenter.Tests` with WebApplicationFactory + in-memory/Mongo2Go fixtures; assert tenant guards, RBAC, quotas, SSE timelines.
- Adapter regression: deterministic fixtures for Trivy DB/Java DB, mirror delta/base comparison, OCI manifest generation; no network.
- Risk bundle pipeline: tests in `StellaOps.ExportCenter.RiskBundles.Tests` (or add) covering bundle layout, DSSE signatures, checksum publication.
- Determinism checks: stable ordering/hashes in manifests, provenance, and distribution descriptors; retry paths must not duplicate outputs.
- Keep tests air-gap friendly; seeded data under `seed-data/` or inline fixtures.
## Delivery Discipline
- Update sprint tracker statuses (`TODO → DOING → DONE/BLOCKED`) in `docs/implplan/SPRINT_0164_0001_0001_exportcenter_iii.md` when starting/finishing/blocking work; mirror design decisions in Decisions & Risks and Execution Log.
- If a decision is needed (API contract, KMS envelope pattern), mark the task `BLOCKED`, describe the decision in sprint Decisions & Risks, and continue with other unblocked tasks.
- When contracts or schemas change (API, manifest, provenance, adapter outputs), update module docs and link them from the sprint.
- Retain deterministic retention/pruning behavior; document feature flags and defaults in `docs/modules/export-center/operations/*.md` when modified.