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

chore(implplan): archive sprint 007 (CFG-04 split out) + open SPRINT_20260423_001

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
master
2026-04-23 07:44:52 +03:00
parent 86f29d580c
commit 6589ae11d6
2 changed files with 84 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
docs/implplan/SPRINT_20260422_007_Concelier_excititor_persisted_provider_credentials.md
View File

@@ -1,106 +0,0 @@
# Sprint 20260422_007 - Excititor Persisted Provider Credentials
## Topic & Scope
- Add a persisted provider-configuration control plane for Excititor so secret-bearing VEX connectors can be configured from Stella UI or CLI rather than environment-only host config.
- Keep provider readiness truthful: enabled providers with missing or invalid required settings must report `blocked` with explicit configuration diagnostics instead of appearing runnable.
- Reuse Excititor's real connector option binders and validators so save-time validation and runtime readiness both reflect actual connector behavior.
- Working directory: `src/Concelier/`.
- Cross-module edits permitted for `src/Cli/`, `src/Web/`, and `docs/modules/excititor/` where required by the provider configuration control plane.
- Expected evidence: targeted backend tests, worker/runtime tests, CLI command coverage, Web component tests, and updated operator docs.
## Dependencies & Concurrency
- Depends on completed sprint `SPRINT_20260422_004_Concelier_full_connector_control_plane.md`.
- Safe parallelism:
- backend persistence/runtime wiring can proceed in parallel with UI shell work once the API contract is fixed
- CLI wiring can proceed in parallel with Web UI once the API contract is fixed
- OCI binary-material handling should not start until the secret-reference storage model is fixed
## Documentation Prerequisites
- `docs/modules/excititor/operations/provider-control-plane.md`
- `docs/modules/concelier/connectors.md`
- `docs/code-of-conduct/CODE_OF_CONDUCT.md`
- `docs/code-of-conduct/TESTING_PRACTICES.md`
## Delivery Tracker
### EXCITITOR-CFG-01 - Add persisted provider settings store and configuration contracts
Status: DONE
Dependency: none
Owners: Project Manager, Developer / Implementer
Task description:
- Introduce a provider settings persistence model separate from the existing provider metadata store. The current `vex.providers` row stores display/discovery/trust/enablement metadata only and has no field for connector runtime settings.
- Add a new provider configuration contract surface under `StellaOps.Excititor.WebService` that mirrors the advisory source configuration UX: field schema, masked snapshot response, `values + clearKeys` update request, and per-provider field definitions.
- Sensitive values must not be re-exposed on reads. Persist either secret references or masked secret-presence state with clear retention semantics.
Completion criteria:
- [x] New Excititor provider configuration API exists for get/update operations.
- [x] Persistence schema exists for provider runtime settings with startup migrations wired.
- [x] Provider configuration snapshots expose masked secret state (`hasValue` / retained-secret semantics) without returning plaintext.
### EXCITITOR-CFG-02 - Drive readiness and execution from persisted provider settings
Status: DONE
Dependency: EXCITITOR-CFG-01
Owners: Developer / Implementer, Test Automation
Task description:
- Add an effective-settings resolver that loads persisted provider settings, binds them into the connector's real option type, and reuses the connector's existing validation path.
- Update provider readiness/status to surface configuration failures as first-class blocked states such as `PROVIDER_CONFIG_REQUIRED` / `PROVIDER_CONFIG_INVALID`.
- Wire the same effective settings into both scheduled worker runs and manual run/orchestrator flows. Current Excititor execution paths still validate with empty or schedule-only settings and must be corrected.
Completion criteria:
- [x] `VexProviderManagementService` computes blocked readiness from real connector validation results.
- [x] Scheduled worker execution resolves persisted provider settings before validation/fetch.
- [x] Manual provider run paths use the same effective settings resolution as the worker.
### EXCITITOR-CFG-03 - Deliver operator configuration surfaces for scalar providers
Status: DONE
Dependency: EXCITITOR-CFG-02
Owners: Developer / Implementer, Documentation author
Task description:
- Add CLI and Web UI configuration flows for the scalar/string-based provider families first: `excititor:cisco`, `excititor:suse-rancher`, and `excititor:msrc`.
- Reuse the existing advisory-source UX pattern: show stored field state, allow secret replacement, allow explicit clear, and render configuration diagnostics inline with readiness.
- Host-config and environment binding remain compatibility fallback only; persisted UI/CLI configuration becomes the primary operator path.
Completion criteria:
- [x] CLI can inspect and update persisted provider configuration for Cisco, Rancher, and MSRC.
- [x] Web UI exposes provider configuration panels with masked secret handling and save/clear flows.
- [x] Provider-control-plane docs are updated to describe the new primary operator path and remaining fallbacks.
### EXCITITOR-CFG-04 - Add artifact-backed configuration support for OCI OpenVEX
Status: BLOCKED
Dependency: EXCITITOR-CFG-02
Owners: Developer / Implementer, Test Automation
Task description:
- Implement the complex `excititor:oci-openvex` configuration path separately from the scalar providers. This connector includes nested image subscription data plus credential and verification material that should not be modeled as host file paths in the browser.
- Prefer staged secret or artifact references for private keys, certificates, identity tokens, refresh tokens, and offline bundle inputs. If compatibility file-path inputs are retained, keep them CLI-only and clearly marked as host-path compatibility mode.
- Ensure OCI configuration validation uses the real `OciOpenVexAttestationConnectorOptions` validator and produces operator-facing blocked reasons rather than runtime surprises.
Completion criteria:
- [ ] OCI provider settings support image subscription lists and registry/cosign credential material without requiring environment variables.
- [ ] UI and/or CLI clearly differentiate server-side staged secret/artifact references from host-path compatibility fields.
- [ ] Targeted tests cover valid and invalid OCI provider configuration scenarios.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-04-22 | Sprint created from implementation-planning review of Excititor provider credential gaps. Current findings: provider store lacks runtime settings, readiness does not validate connector config, and worker/manual run paths do not yet consume persisted provider settings. | Planning |
| 2026-04-22 | EXCITITOR-CFG-01/02/03 landed: new `vex.provider_settings` table + migration `007_vex_provider_settings.sql` wired via embedded-resource startup migrations; `IVexProviderSettingsStore` (Postgres + in-memory) added; `VexProviderConfigurationService`, `VexProviderRuntimeSettingsCache`, and field schemas for `excititor:cisco`, `excititor:suse-rancher`, `excititor:msrc`; `GET/PUT /excititor/providers/{id}/configuration` endpoints mirror SRC-CREDS-001 `values + clearKeys` shape with masked secret state; `VexProviderManagementService` blocked-readiness now surfaces `PROVIDER_CONFIG_REQUIRED` / `PROVIDER_CONFIG_INVALID` using the real `CiscoConnectorOptions` / `RancherHubConnectorOptions` / `MsrcConnectorOptions` validators; `VexIngestOrchestrator` and `DefaultVexProviderRunner` both resolve persisted settings and overlay them on host-config baseline. CLI: `stella vex providers configure <provider> --set --clear --format` in `VexProvidersCommandGroup`. Web: `VexProviderConfigurationComponent` standalone panel + API client methods on `VexProviderManagementApi`. Targeted xUnit run against `StellaOps.Excititor.WebService.Tests.VexProviderConfigurationServiceTests` passed `Total: 8, Failed: 0`; regression run of `ProviderManagementEndpointsTests` still passes `Total: 5, Failed: 0`. | Codex |
| 2026-04-22 | Follow-up hardening: Excititor scheduled worker now short-circuits providers blocked by missing or invalid persisted configuration instead of treating them as retry failures, clearing stale backoff while preserving a truthful operator-facing reason; `VexIngestOrchestrator` returns `blocked` per-provider results for batch run/init/reconcile flows when `PROVIDER_CONFIG_*` applies; operator docs corrected and expanded with `docs/modules/excititor/operations/provider-credentials.md` plus provider-control-plane/ops guide truthfulness fixes. | Codex |
| 2026-04-22 | Targeted behavioral verification for the hardening slice used the repo xUnit helper because this codebase runs Microsoft Testing Platform and ignores VSTest `dotnet test --filter ...` (`MTP0001`). Evidence: `powershell -ExecutionPolicy Bypass -File .\\scripts\\test-targeted-xunit.ps1 -Project src/Concelier/__Tests/StellaOps.Excititor.Worker.Tests/StellaOps.Excititor.Worker.Tests.csproj -Method StellaOps.Excititor.Worker.Tests.DefaultVexProviderRunnerTests.RunAsync_ConfigBlocked_DoesNotFetch_AndClearsBackoff` passed `Total: 1`; `powershell -ExecutionPolicy Bypass -File .\\scripts\\test-targeted-xunit.ps1 -Project src/Concelier/__Tests/StellaOps.Excititor.WebService.Tests/StellaOps.Excititor.WebService.Tests.csproj -Method StellaOps.Excititor.WebService.Tests.VexIngestOrchestratorTests.RunAsync_ReturnsBlocked_WhenProviderConfigurationMissing -BuildProjectReferences` passed `Total: 1`. The WebService test project also required an explicit `<Compile Include="VexIngestOrchestratorTests.cs" />` entry because it uses a closed compile list. | Codex |
| 2026-04-22 | EXCITITOR-CFG-04 deferred (marked BLOCKED). OCI OpenVEX needs image-subscription lists plus binary credential material (registry tokens, cosign keys, offline bundles) that should not ride the flat string map used by scalar providers. Staging that shape requires a secret-reference or artifact store decision out of scope for this sprint slice; see Decisions & Risks. | Codex |
## Decisions & Risks
- Decision (Sprint slice): scalar providers (Cisco, Rancher, MSRC) persist the full editable field set (including sensitive credentials) in `vex.provider_settings.settings::jsonb`. Secrets are masked on read and retained on blank submit; explicit `clearKeys` removes them. This follows the Concelier SRC-CREDS precedent. The vex.providers metadata row (trust, discovery, base_uris, enabled) remains the authority for provider metadata and is not rewritten by settings updates.
- Decision: blocked-readiness contract reuses the SRC-CREDS-005 shape. Provider list/status responses emit `blockingReasonCode` (`PROVIDER_CONFIG_REQUIRED` / `PROVIDER_CONFIG_INVALID`) and `blockingReason` so CLI and Web surfaces can render the same way they render Concelier source blocked states.
- Decision: persisted UI/CLI settings win over host-config when both define the same key. Host-config and environment binding remain compatibility fallbacks only.
- OCI is materially larger than Cisco/Rancher/MSRC because it includes nested image subscriptions and binary credential material (private keys, certificates, offline bundles). Shipping OCI requires a secret-reference/artifact-store decision that the flat string map used for scalar providers cannot represent cleanly. EXCITITOR-CFG-04 is marked BLOCKED pending that design decision; the blocked readiness surface remains truthful (OCI with missing binary material still shows blocked via the connector's own validator at run time).
- Compatibility risk: existing host-config paths continue to work as fallback. The worker runner merges persisted settings on top of the schedule-supplied baseline (`DefaultVexProviderRunner.ResolveEffectiveSettingsAsync`).
- Docs updated alongside implementation:
- `docs/modules/excititor/operations/provider-control-plane.md`
- `docs/modules/excititor/operations/provider-credentials.md`
- `docs/ops/connector-setup-guide.md`
## Next Checkpoints
- Contract review after `EXCITITOR-CFG-01` with decided persistence model and route shape.
- Runtime review after `EXCITITOR-CFG-02` with blocked-readiness evidence for missing credentials.
- Operator demo after `EXCITITOR-CFG-03` for Cisco/Rancher/MSRC CLI + Web flows.
- OCI design checkpoint before starting `EXCITITOR-CFG-04`.

84
docs/implplan/SPRINT_20260423_001_Excititor_OCI_OpenVEX_artifact_backed_config.md Normal file
View File

@@ -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<string>` (image subscriptions), `list<artifactRef>` (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<artifactRef>`) 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.