Add Authority Advisory AI and API Lifecycle Configuration

- Introduced AuthorityAdvisoryAiOptions and related classes for managing advisory AI configurations, including remote inference options and tenant-specific settings.
- Added AuthorityApiLifecycleOptions to control API lifecycle settings, including legacy OAuth endpoint configurations.
- Implemented validation and normalization methods for both advisory AI and API lifecycle options to ensure proper configuration.
- Created AuthorityNotificationsOptions and its related classes for managing notification settings, including ack tokens, webhooks, and escalation options.
- Developed IssuerDirectoryClient and related models for interacting with the issuer directory service, including caching mechanisms and HTTP client configurations.
- Added support for dependency injection through ServiceCollectionExtensions for the Issuer Directory Client.
- Updated project file to include necessary package references for the new Issuer Directory Client library.

src/Scanner/__Tests/StellaOps.Scanner.Surface.Env.Tests/StellaOps.Scanner.Surface.Env.Tests.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>preview</LangVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <IsPackable>false</IsPackable>
+    <OutputType>Exe</OutputType>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="../../__Libraries/StellaOps.Scanner.Surface.Env/StellaOps.Scanner.Surface.Env.csproj" />
+  </ItemGroup>
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+</Project>

src/Scanner/__Tests/StellaOps.Scanner.Surface.Env.Tests/SurfaceEnvironmentBuilderTests.cs

@@ -0,0 +1,80 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using StellaOps.Scanner.Surface.Env;
+
+namespace StellaOps.Scanner.Surface.Env.Tests;
+
+public sealed class SurfaceEnvironmentBuilderTests
+{
+    [Fact]
+    public void Build_UsesDefaults_WhenVariablesMissing()
+    {
+        var services = CreateServices();
+        var environment = SurfaceEnvironmentFactory.Create(services, options =>
+        {
+            options.RequireSurfaceEndpoint = false;
+        });
+
+        Assert.Equal("surface-cache", environment.Settings.SurfaceFsBucket);
+        Assert.Equal(4096, environment.Settings.CacheQuotaMegabytes);
+        Assert.False(environment.Settings.PrefetchEnabled);
+        Assert.NotNull(environment.Settings.CacheRoot);
+        Assert.True(environment.Settings.CacheRoot.Exists);
+    }
+
+    [Fact]
+    public void Build_ReadsEnvironmentVariables_WithPrefixes()
+    {
+        Environment.SetEnvironmentVariable("SCANNER_SURFACE_FS_BUCKET", "custom-bucket");
+        Environment.SetEnvironmentVariable("SCANNER_SURFACE_CACHE_QUOTA_MB", "512");
+        Environment.SetEnvironmentVariable("SCANNER_SURFACE_FS_ENDPOINT", "https://surface.example.test");
+
+        try
+        {
+            var services = CreateServices();
+            var environment = SurfaceEnvironmentFactory.Create(services);
+
+            Assert.Equal("custom-bucket", environment.Settings.SurfaceFsBucket);
+            Assert.Equal(512, environment.Settings.CacheQuotaMegabytes);
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable("SCANNER_SURFACE_FS_BUCKET", null);
+            Environment.SetEnvironmentVariable("SCANNER_SURFACE_CACHE_QUOTA_MB", null);
+            Environment.SetEnvironmentVariable("SCANNER_SURFACE_FS_ENDPOINT", null);
+        }
+    }
+
+    [Fact]
+    public void Build_Throws_WhenIntegerOutOfRange()
+    {
+        Environment.SetEnvironmentVariable("SCANNER_SURFACE_CACHE_QUOTA_MB", "1");
+        Environment.SetEnvironmentVariable("SCANNER_SURFACE_FS_ENDPOINT", "https://surface.example.test");
+
+        try
+        {
+            var services = CreateServices();
+            var exception = Assert.Throws<SurfaceEnvironmentException>(() => SurfaceEnvironmentFactory.Create(services));
+            Assert.Equal("SURFACE_CACHE_QUOTA_MB", exception.Variable);
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable("SCANNER_SURFACE_CACHE_QUOTA_MB", null);
+            Environment.SetEnvironmentVariable("SCANNER_SURFACE_FS_ENDPOINT", null);
+        }
+    }
+
+    private static IServiceProvider CreateServices(Action<IServiceCollection>? configure = null)
+    {
+        var services = new ServiceCollection();
+        var configuration = new ConfigurationBuilder().Build();
+
+        services.AddSingleton<IConfiguration>(configuration);
+        services.AddLogging(builder => builder.ClearProviders());
+
+        configure?.Invoke(services);
+
+        return services.BuildServiceProvider();
+    }
+}

src/Scanner/__Tests/StellaOps.Scanner.Surface.Env.Tests/SurfaceEnvironmentFeatureFlagTests.cs

@@ -0,0 +1,43 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using StellaOps.Scanner.Surface.Env;
+
+namespace StellaOps.Scanner.Surface.Env.Tests;
+
+public sealed class SurfaceEnvironmentFeatureFlagTests
+{
+    [Fact]
+    public void Build_ReturnsFlags_LowerCased()
+    {
+        Environment.SetEnvironmentVariable("SCANNER_SURFACE_FEATURES", "Validation,PreWarm , unknown");
+        Environment.SetEnvironmentVariable("SCANNER_SURFACE_FS_ENDPOINT", "https://surface.example.test");
+        try
+        {
+            var services = CreateServices();
+            var environment = SurfaceEnvironmentFactory.Create(services, options =>
+            {
+                options.KnownFeatureFlags.Add("validation");
+                options.KnownFeatureFlags.Add("prewarm");
+                options.RequireSurfaceEndpoint = true;
+            });
+
+            Assert.Contains("validation", environment.Settings.FeatureFlags);
+            Assert.Contains("prewarm", environment.Settings.FeatureFlags);
+            Assert.Contains("unknown", environment.Settings.FeatureFlags);
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable("SCANNER_SURFACE_FEATURES", null);
+            Environment.SetEnvironmentVariable("SCANNER_SURFACE_FS_ENDPOINT", null);
+        }
+    }
+
+    private static IServiceProvider CreateServices()
+    {
+        var services = new ServiceCollection();
+        services.AddSingleton<IConfiguration>(new ConfigurationBuilder().Build());
+        services.AddLogging(builder => builder.ClearProviders());
+        return services.BuildServiceProvider();
+    }
+}