From 6589ae11d60d58dd983fd0258f00acdd80e7cd3e Mon Sep 17 00:00:00 2001 From: master <> Date: Thu, 23 Apr 2026 07:44:52 +0300 Subject: [PATCH] chore(implplan): archive sprint 007 (CFG-04 split out) + open SPRINT_20260423_001 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit EXCITITOR-CFG-04 (artifact-backed OCI OpenVEX configuration) needed a distinct secret-reference storage model the scalar settings contract can't absorb. Splitting it to its own sprint (same pattern used when CAPSULE-001 was moved off SPRINT_20260408_005 earlier this session). SPRINT_20260422_007 — all in-scope tasks in terminal states (DONE x3 + MOVED), archive. SPRINT_20260423_001 — 3 new tasks (OCI-CFG-001/002/003) tracking artifact-reference storage + validator-backed OCI readiness + CLI/Web surfaces for the nested configuration shape. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...xcititor_persisted_provider_credentials.md | 0 ...itor_OCI_OpenVEX_artifact_backed_config.md | 84 +++++++++++++++++++ 2 files changed, 84 insertions(+) rename {docs => docs-archived}/implplan/SPRINT_20260422_007_Concelier_excititor_persisted_provider_credentials.md (100%) create mode 100644 docs/implplan/SPRINT_20260423_001_Excititor_OCI_OpenVEX_artifact_backed_config.md diff --git a/docs/implplan/SPRINT_20260422_007_Concelier_excititor_persisted_provider_credentials.md b/docs-archived/implplan/SPRINT_20260422_007_Concelier_excititor_persisted_provider_credentials.md similarity index 100% rename from docs/implplan/SPRINT_20260422_007_Concelier_excititor_persisted_provider_credentials.md rename to docs-archived/implplan/SPRINT_20260422_007_Concelier_excititor_persisted_provider_credentials.md diff --git a/docs/implplan/SPRINT_20260423_001_Excititor_OCI_OpenVEX_artifact_backed_config.md b/docs/implplan/SPRINT_20260423_001_Excititor_OCI_OpenVEX_artifact_backed_config.md new file mode 100644 index 000000000..db30421eb --- /dev/null +++ b/docs/implplan/SPRINT_20260423_001_Excititor_OCI_OpenVEX_artifact_backed_config.md @@ -0,0 +1,84 @@ +# Sprint 20260423-001 — Excititor OCI OpenVEX artifact-backed configuration + +## Topic & Scope +- Implement the complex `excititor:oci-openvex` configuration path separated out of SPRINT_20260422_007 (EXCITITOR-CFG-04 was BLOCKED there because it needs a distinct secret-reference / artifact-reference storage model that the scalar-settings path can't cleanly absorb). +- OCI OpenVEX connector configuration carries nested data that does not fit the flat string-map pattern the persisted-settings contract was designed for: image subscription lists (often dozens per tenant), registry credentials, cosign signature verification material (public keys, TUF trust roots, Fulcio identity constraints), and optional offline bundle inputs. +- Working directory: `src/Concelier/__Libraries/StellaOps.Excititor.Core/`, `StellaOps.Excititor.Connectors.OCI.OpenVEX.Attest/`, `StellaOps.Excititor.Persistence/`, `StellaOps.Excititor.WebService/`, plus CLI + Web surfaces. +- Expected evidence: new artifact-reference storage model, `VexProviderConfigurationService` extended for non-scalar field types, CLI + Web entries for the nested shape, focused tests, operator docs. + +## Dependencies & Concurrency +- Upstream: SPRINT_20260422_007 EXCITITOR-CFG-01/02/03 (archived via commit `7efa424fe`) shipped the scalar persisted-settings machinery. This sprint extends it for complex types. +- Adjacent: SPRINT_20260422_008 FE-STAB4 (open, FE suite work) — no overlap. +- Safe parallelism: stays within `src/Concelier/__Libraries/StellaOps.Excititor.*` + Excititor WebService + CLI + Web OCI configuration panel. + +## Documentation Prerequisites +- `docs-archived/implplan/SPRINT_20260422_007_Concelier_excititor_persisted_provider_credentials.md` — baseline CFG-01/02/03 contract. +- `src/Concelier/__Libraries/StellaOps.Excititor.Connectors.OCI.OpenVEX.Attest/OciOpenVexAttestationConnectorOptions.cs` — the real options validator to reuse. +- `docs/modules/excititor/operations/provider-control-plane.md` — current credential-entry dossier to extend. + +## Delivery Tracker + +### OCI-CFG-001 — Design + implement a staged artifact-reference storage model +Status: TODO +Dependency: none +Owners: Developer / Implementer +Task description: +- Extend `vex.provider_settings` (or add a sibling table `vex.provider_artifact_refs`) so settings can carry references to server-side staged artifacts rather than inlined binary material. A reference is an opaque, operator-uploaded blob identified by an ID, mime type, and optional checksum / signature. +- Define a minimal artifact-staging API: `POST /excititor/providers/{id}/artifacts` (multipart upload or base64) returning `{ artifactId, sha256 }`; `GET /excititor/providers/{id}/artifacts/{artifactId}/meta` for inspection (never returns the binary itself after staging); `DELETE` for removal. +- Artifacts live server-side with tenant isolation (RLS) and a size cap (e.g. 10 MiB per artifact, 50 MiB per provider total). +- Settings JSONB references artifacts by ID; the effective-settings resolver swaps refs for file-system-scoped material at runtime (e.g. writes a temp file to pass to cosign's verification library, then cleans up). + +Completion criteria: +- [ ] Artifact-reference storage schema + migration (embedded, auto-applied per §2.7). +- [ ] Upload / meta / delete API with size-cap enforcement + tenant RLS. +- [ ] Effective-settings resolver materializes artifact refs to disk for runtime consumption, cleaning up after. +- [ ] Secrets never echoed on read — meta endpoint returns only `{ artifactId, sha256, mime, sizeBytes, stagedAt }`. + +### OCI-CFG-002 — Wire OCI OpenVEX provider configuration to the new model +Status: TODO +Dependency: OCI-CFG-001 +Owners: Developer / Implementer +Task description: +- `VexProviderConfigurationService` must support nested field types: `artifactRef`, `list` (image subscriptions), `list` (multi-key / multi-TUF-root). +- Reuse `OciOpenVexAttestationConnectorOptions` validator to compute readiness. Blocked reasons must be operator-facing: `PROVIDER_CONFIG_MISSING_COSIGN_KEY`, `PROVIDER_CONFIG_INVALID_IMAGE_REFERENCE`, etc. — sub-codes within the existing `PROVIDER_CONFIG_INVALID` envelope. +- Worker + orchestrator paths: no change — they already read through the effective-settings resolver which now transparently materializes artifact refs. + +Completion criteria: +- [ ] OCI provider field schema exposes all 3 complex field types. +- [ ] Validator-backed readiness surfaces OCI-specific missing-material reasons. +- [ ] Targeted tests cover ready vs blocked vs invalid cases. + +### OCI-CFG-003 — CLI + Web surfaces for complex fields +Status: TODO +Dependency: OCI-CFG-002 +Owners: Developer / Implementer, Documentation author +Task description: +- CLI: `stella vex providers configure excititor:oci-openvex --image ghcr.io/foo/bar:v1 --image ...` (repeatable), `--upload-artifact cosign-key=@/path/to/cosign.pub`, `--clear-artifact cosign-key`, `--list-artifacts`. Host-path inputs explicitly supported behind a `--host-path-compat` flag and marked in CLI help as compatibility mode (CLI-only, never surfaced in UI). +- Web: new `OciOpenVexConfigurationComponent` (Angular standalone) with: + - image subscription list editor (add/remove rows, chip view). + - artifact-reference slots with upload + staged-secret rendering (similar masked-secret pattern). + - readiness panel showing the OCI-specific blocked reasons inline with the offending field. +- Routing: attach to the existing advisory-vex-sources detail flow via a conditional render when `provider.kind == 'oci-openvex'`. +- Docs: extend `docs/modules/excititor/operations/provider-credentials.md` with an OCI OpenVEX operator dossier (image subscription list management, cosign material acquisition, TUF root setup if applicable, offline bundle flow if retained). + +Completion criteria: +- [ ] CLI commands cover list + upload + clear per artifact + image subscription editing. +- [ ] Web OCI configuration component renders + submits correctly against the new API. +- [ ] Operator doc updated with walk-through for the 3–4 canonical OCI OpenVEX setup shapes. + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-04-23 | Sprint created by splitting EXCITITOR-CFG-04 out of SPRINT_20260422_007 (now archivable). OCI artifact-backed configuration needs its own storage-model design — scalar settings store can't absorb image subscription lists + binary credential material cleanly. | Claude | + +## Decisions & Risks +- **Decision**: artifact-reference table is a sibling of `vex.provider_settings`, not an extension of the JSONB column. Keeps scalar-settings semantics simple and lets binary material use its own RLS-enforced storage with size caps. +- **Decision**: host-path compat stays in CLI only, flagged. The UI must not surface file paths on an operator's host because the server won't be able to read them in production deployments. +- **Risk**: cosign/TUF verification libraries generally want on-disk paths. Mitigation: effective-settings resolver writes tempfiles per-request, ensures cleanup, keeps the temp directory chmod'd appropriately. +- **Risk**: artifact size caps (10 MiB per artifact, 50 MiB per provider) may be too tight for some TUF-root scenarios. Mitigation: caps are soft + configurable via platform environment settings; document the tunable. +- **Risk**: nested field types (`list`) change the `values/clearKeys` API shape. Mitigation: keep the scalar shape unchanged, introduce a separate `/artifacts` endpoint path so the existing client code on scalar providers doesn't regress. + +## Next Checkpoints +- OCI-CFG-001 DONE: artifact-reference schema + upload/meta/delete API + effective-settings materializer. +- OCI-CFG-002 DONE: OCI provider wired to the new model; validator-backed OCI-specific blocked reasons. +- OCI-CFG-003 DONE: CLI + Web + docs; sprint archivable when worker can run a sealed OCI OpenVEX provider end-to-end.