feat: Implement approvals workflow and notifications integration

- Added approvals orchestration with persistence and workflow scaffolding. - Integrated notifications insights and staged resume hooks. - Introduced approval coordinator and policy notification bridge with unit tests. - Added approval decision API with resume requeue and persisted plan snapshots. - Documented the Excitor consensus API beta and provided JSON sample payload. - Created analyzers to flag usage of deprecated merge service APIs. - Implemented logging for artifact uploads and approval decision service. - Added tests for PackRunApprovalDecisionService and related components.
2025-11-06 08:48:13 +02:00
parent 21a2759412
commit dd217b4546
98 changed files with 3883 additions and 2381 deletions
--- a/src/Scanner/StellaOps.Scanner.WebService/AssemblyInfo.cs
+++ b/src/Scanner/StellaOps.Scanner.WebService/AssemblyInfo.cs
@@ -1,3 +1,3 @@
-using System.Runtime.CompilerServices;
-
-[assembly: InternalsVisibleTo("StellaOps.Scanner.WebService.Tests")]
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("StellaOps.Scanner.WebService.Tests")]
--- a/src/Scanner/StellaOps.Scanner.WebService/Program.cs
+++ b/src/Scanner/StellaOps.Scanner.WebService/Program.cs
@@ -97,6 +97,8 @@ builder.Services.AddSurfaceEnvironment(options =>
 builder.Services.AddSurfaceValidation();
 builder.Services.AddSurfaceFileCache();
 builder.Services.AddSurfaceSecrets();
+builder.Services.AddSingleton<IConfigureOptions<SurfaceCacheOptions>>(sp =>
+    new SurfaceCacheOptionsConfigurator(sp.GetRequiredService<ISurfaceEnvironment>()));
 builder.Services.AddSingleton<ISurfacePointerService, SurfacePointerService>();
 builder.Services.AddSingleton<IRedisConnectionFactory, RedisConnectionFactory>();
 if (bootstrapOptions.Events is { Enabled: true } eventsOptions
@@ -370,5 +372,24 @@ if (resolvedOptions.Features.EnablePolicyPreview)
 apiGroup.MapReportEndpoints(resolvedOptions.Api.ReportsSegment);
 apiGroup.MapRuntimeEndpoints(resolvedOptions.Api.RuntimeSegment);

-app.MapOpenApiIfAvailable();
-await app.RunAsync().ConfigureAwait(false);
+app.MapOpenApiIfAvailable();
+await app.RunAsync().ConfigureAwait(false);
+
+public partial class Program;
+
+internal sealed class SurfaceCacheOptionsConfigurator : IConfigureOptions<SurfaceCacheOptions>
+{
+    private readonly ISurfaceEnvironment _surfaceEnvironment;
+
+    public SurfaceCacheOptionsConfigurator(ISurfaceEnvironment surfaceEnvironment)
+    {
+        _surfaceEnvironment = surfaceEnvironment ?? throw new ArgumentNullException(nameof(surfaceEnvironment));
+    }
+
+    public void Configure(SurfaceCacheOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        var settings = _surfaceEnvironment.Settings;
+        options.RootDirectory = settings.CacheRoot.FullName;
+    }
+}
--- a/src/Scanner/StellaOps.Scanner.WebService/TASKS.md
+++ b/src/Scanner/StellaOps.Scanner.WebService/TASKS.md
@@ -4,7 +4,8 @@
 |----|--------|----------|------------|-------------|---------------|
 | SCAN-REPLAY-186-001 | TODO | Scanner WebService Guild | REPLAY-CORE-185-001 | Implement scan `record` mode producing replay manifests/bundles, capture policy/feed/tool hashes, and update `docs/modules/scanner/architecture.md` referencing `docs/replay/DETERMINISTIC_REPLAY.md` Section 6. | API/worker integration tests cover record mode; docs merged; replay artifacts stored per spec. |
 | SCANNER-SURFACE-02 | DONE (2025-11-05) | Scanner WebService Guild | SURFACE-FS-02 | Publish Surface.FS pointers (CAS URIs, manifests) via scan/report APIs and update attestation metadata.<br>2025-11-05: Surface pointers projected through scan/report endpoints, orchestrator samples + DSSE fixtures refreshed with manifest block, readiness tests updated to use validator stub. | OpenAPI updated; clients regenerated; integration tests validate pointer presence and tenancy. |
-| SCANNER-ENV-02 | DOING (2025-11-02) | Scanner WebService Guild, Ops Guild | SURFACE-ENV-02 | Wire Surface.Env helpers into WebService hosting (cache roots, feature flags) and document configuration.<br>2025-11-02: Cache root resolution switched to helper; feature flag bindings updated; Helm/Compose updates pending review. | Service uses helper; env table documented; helm/compose templates updated. |
+| SCANNER-ENV-02 | DOING (2025-11-02) | Scanner WebService Guild, Ops Guild | SURFACE-ENV-02 | Wire Surface.Env helpers into WebService hosting (cache roots, feature flags) and document configuration.<br>2025-11-02: Cache root resolution switched to helper; feature flag bindings updated; Helm/Compose updates pending review.<br>2025-11-05 14:55Z: Aligning readiness checks, docs, and Helm/Compose templates with Surface.Env outputs and planning test coverage for configuration fallbacks.<br>2025-11-06 17:05Z: Surface.Env documentation/README refreshed; warning catalogue captured for ops handoff. | Service uses helper; env table documented; helm/compose templates updated. |
+> 2025-11-05 19:18Z: Added configurator to project wiring and unit test ensuring Surface.Env cache root is honoured.
 | SCANNER-SECRETS-02 | DOING (2025-11-02) | Scanner WebService Guild, Security Guild | SURFACE-SECRETS-02 | Replace ad-hoc secret wiring with Surface.Secrets for report/export operations (registry and CAS tokens).<br>2025-11-02: Export/report flows now depend on Surface.Secrets stub; integration tests in progress. | Secrets fetched through shared provider; unit/integration tests cover rotation + failure cases. |
 | SCANNER-EVENTS-16-301 | BLOCKED (2025-10-26) | Scanner WebService Guild | ORCH-SVC-38-101, NOTIFY-SVC-38-001 | Emit orchestrator-compatible envelopes (`scanner.event.*`) and update integration tests to verify Notifier ingestion (no Redis queue coupling). | Tests assert envelope schema + orchestrator publish; Notifier consumer harness passes; docs updated with new event contract. Blocked by .NET 10 preview OpenAPI/Auth dependency drift preventing `dotnet test` completion. |
 | SCANNER-EVENTS-16-302 | DOING (2025-10-26) | Scanner WebService Guild | SCANNER-EVENTS-16-301 | Extend orchestrator event links (report/policy/attestation) once endpoints are finalised across gateway + console. | Links section covers UI/API targets; downstream consumers validated; docs/samples updated. |
--- a/src/Scanner/StellaOps.Scanner.Worker/AssemblyInfo.cs
+++ b/src/Scanner/StellaOps.Scanner.Worker/AssemblyInfo.cs
@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("StellaOps.Scanner.Worker.Tests")]
--- a/src/Scanner/StellaOps.Scanner.Worker/Program.cs
+++ b/src/Scanner/StellaOps.Scanner.Worker/Program.cs
@@ -36,6 +36,8 @@ builder.Services.AddSurfaceEnvironment(options =>
 builder.Services.AddSurfaceValidation();
 builder.Services.AddSurfaceFileCache();
 builder.Services.AddSurfaceSecrets();
+builder.Services.AddSingleton<IConfigureOptions<SurfaceCacheOptions>>(sp =>
+    new SurfaceCacheOptionsConfigurator(sp.GetRequiredService<ISurfaceEnvironment>()));
 builder.Services.AddSingleton<ScannerWorkerMetrics>();
 builder.Services.AddSingleton<ScanProgressReporter>();
 builder.Services.AddSingleton<ScanJobProcessor>();
@@ -127,3 +129,20 @@ var host = builder.Build();
 await host.RunAsync();

 public partial class Program;
+
+internal sealed class SurfaceCacheOptionsConfigurator : IConfigureOptions<SurfaceCacheOptions>
+{
+    private readonly ISurfaceEnvironment _surfaceEnvironment;
+
+    public SurfaceCacheOptionsConfigurator(ISurfaceEnvironment surfaceEnvironment)
+    {
+        _surfaceEnvironment = surfaceEnvironment ?? throw new ArgumentNullException(nameof(surfaceEnvironment));
+    }
+
+    public void Configure(SurfaceCacheOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        var settings = _surfaceEnvironment.Settings;
+        options.RootDirectory = settings.CacheRoot.FullName;
+    }
+}
--- a/src/Scanner/StellaOps.Scanner.Worker/TASKS.md
+++ b/src/Scanner/StellaOps.Scanner.Worker/TASKS.md
@@ -4,5 +4,6 @@
 |----|--------|----------|------------|-------------|---------------|
 | SCAN-REPLAY-186-002 | TODO | Scanner Worker Guild | REPLAY-CORE-185-001 | Enforce deterministic analyzer execution when consuming replay input bundles, emit layer Merkle metadata, and author `docs/modules/scanner/deterministic-execution.md` summarising invariants from `docs/replay/DETERMINISTIC_REPLAY.md` Section 4. | Replay mode analyzers pass determinism tests; new doc merged; integration fixtures updated. |
 | SCANNER-SURFACE-01 | DOING (2025-11-02) | Scanner Worker Guild | SURFACE-FS-02 | Persist Surface.FS manifests after analyzer stages, including layer CAS metadata and EntryTrace fragments.<br>2025-11-02: Draft Surface.FS manifests emitted for sample scans; telemetry counters under review. | Integration tests prove cache entries exist; telemetry counters exported. |
-| SCANNER-ENV-01 | DOING (2025-11-02) | Scanner Worker Guild | SURFACE-ENV-02 | Replace ad-hoc environment reads with `StellaOps.Scanner.Surface.Env` helpers for cache roots and CAS endpoints.<br>2025-11-02: Worker bootstrap now resolves cache roots via helper; warning path documented; smoke tests running. | Worker boots with helper; misconfiguration warnings documented; smoke tests updated. |
+| SCANNER-ENV-01 | DOING (2025-11-02) | Scanner Worker Guild | SURFACE-ENV-02 | Replace ad-hoc environment reads with `StellaOps.Scanner.Surface.Env` helpers for cache roots and CAS endpoints.<br>2025-11-02: Worker bootstrap now resolves cache roots via helper; warning path documented; smoke tests running.<br>2025-11-05 14:55Z: Extending helper usage into cache/secrets configuration, updating worker validator wiring, and drafting docs/tests for new Surface.Env outputs.<br>2025-11-06 17:05Z: README/design docs updated with warning catalogue; startup logging guidance captured for ops runbooks. | Worker boots with helper; misconfiguration warnings documented; smoke tests updated. |
+> 2025-11-05 19:18Z: Bound `SurfaceCacheOptions` root directory to resolved Surface.Env settings and added unit coverage around the configurator.
 | SCANNER-SECRETS-01 | DOING (2025-11-02) | Scanner Worker Guild, Security Guild | SURFACE-SECRETS-02 | Adopt `StellaOps.Scanner.Surface.Secrets` for registry/CAS credentials during scan execution.<br>2025-11-02: Surface.Secrets provider wired for CAS token retrieval; integration tests added. | Secrets fetched via shared provider; legacy secret code removed; integration tests cover rotation. |
--- a/src/Scanner/__Tests/StellaOps.Scanner.WebService.Tests/SurfaceCacheOptionsConfiguratorTests.cs
+++ b/src/Scanner/__Tests/StellaOps.Scanner.WebService.Tests/SurfaceCacheOptionsConfiguratorTests.cs
@@ -0,0 +1,49 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Security.Cryptography.X509Certificates;
+using StellaOps.Scanner.Surface.Env;
+using StellaOps.Scanner.Surface.FS;
+using Xunit;
+
+namespace StellaOps.Scanner.WebService.Tests;
+
+public sealed class SurfaceCacheOptionsConfiguratorTests
+{
+    [Fact]
+    public void Configure_UsesSurfaceEnvironmentCacheRoot()
+    {
+        var cacheRoot = new DirectoryInfo(Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N")));
+        var settings = new SurfaceEnvironmentSettings(
+            new Uri("https://surface.example"),
+            "surface-cache",
+            null,
+            cacheRoot,
+            cacheQuotaMegabytes: 512,
+            prefetchEnabled: true,
+            featureFlags: Array.Empty<string>(),
+            secrets: new SurfaceSecretsConfiguration("file", "tenant-b", "/etc/secrets", null, null, allowInline: false),
+            tenant: "tenant-b",
+            tls: new SurfaceTlsConfiguration(null, null, new X509Certificate2Collection()));
+
+        var environment = new StubSurfaceEnvironment(settings);
+        var configurator = new SurfaceCacheOptionsConfigurator(environment);
+        var options = new SurfaceCacheOptions();
+
+        configurator.Configure(options);
+
+        Assert.Equal(cacheRoot.FullName, options.RootDirectory);
+    }
+
+    private sealed class StubSurfaceEnvironment : ISurfaceEnvironment
+    {
+        public StubSurfaceEnvironment(SurfaceEnvironmentSettings settings)
+        {
+            Settings = settings;
+        }
+
+        public SurfaceEnvironmentSettings Settings { get; }
+
+        public IReadOnlyDictionary<string, string> RawVariables { get; } = new Dictionary<string, string>();
+    }
+}
--- a/src/Scanner/__Tests/StellaOps.Scanner.Worker.Tests/SurfaceCacheOptionsConfiguratorTests.cs
+++ b/src/Scanner/__Tests/StellaOps.Scanner.Worker.Tests/SurfaceCacheOptionsConfiguratorTests.cs
@@ -0,0 +1,49 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Security.Cryptography.X509Certificates;
+using StellaOps.Scanner.Surface.Env;
+using StellaOps.Scanner.Surface.FS;
+using Xunit;
+
+namespace StellaOps.Scanner.Worker.Tests;
+
+public sealed class SurfaceCacheOptionsConfiguratorTests
+{
+    [Fact]
+    public void Configure_UsesSurfaceEnvironmentCacheRoot()
+    {
+        var cacheRoot = new DirectoryInfo(Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N")));
+        var settings = new SurfaceEnvironmentSettings(
+            new Uri("https://surface.example"),
+            "surface-cache",
+            null,
+            cacheRoot,
+            cacheQuotaMegabytes: 1024,
+            prefetchEnabled: false,
+            featureFlags: Array.Empty<string>(),
+            secrets: new SurfaceSecretsConfiguration("file", "tenant-a", "/etc/secrets", null, null, false),
+            tenant: "tenant-a",
+            tls: new SurfaceTlsConfiguration(null, null, new X509Certificate2Collection()));
+
+        var environment = new StubSurfaceEnvironment(settings);
+        var configurator = new SurfaceCacheOptionsConfigurator(environment);
+        var options = new SurfaceCacheOptions();
+
+        configurator.Configure(options);
+
+        Assert.Equal(cacheRoot.FullName, options.RootDirectory);
+    }
+
+    private sealed class StubSurfaceEnvironment : ISurfaceEnvironment
+    {
+        public StubSurfaceEnvironment(SurfaceEnvironmentSettings settings)
+        {
+            Settings = settings;
+        }
+
+        public SurfaceEnvironmentSettings Settings { get; }
+
+        public IReadOnlyDictionary<string, string> RawVariables { get; } = new Dictionary<string, string>();
+    }
+}