Restructure solution layout by module

src/Aoc/StellaOps.Aoc.sln

@@ -0,0 +1,56 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "__Libraries", "__Libraries", "{41F15E67-7190-CF23-3BC4-77E87134CADD}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StellaOps.Aoc", "__Libraries\StellaOps.Aoc\StellaOps.Aoc.csproj", "{54CD9E36-B119-4970-B652-826363055F7D}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "__Tests", "__Tests", "{56BCE1BF-7CBA-7CE8-203D-A88051F1D642}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StellaOps.Aoc.Tests", "__Tests\StellaOps.Aoc.Tests\StellaOps.Aoc.Tests.csproj", "{5CF1158D-64F6-4981-85CB-B43453A37329}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Debug|x64 = Debug|x64
+		Debug|x86 = Debug|x86
+		Release|Any CPU = Release|Any CPU
+		Release|x64 = Release|x64
+		Release|x86 = Release|x86
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{54CD9E36-B119-4970-B652-826363055F7D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Debug|x64.Build.0 = Debug|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Debug|x86.Build.0 = Debug|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Release|x64.ActiveCfg = Release|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Release|x64.Build.0 = Release|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Release|x86.ActiveCfg = Release|Any CPU
+		{54CD9E36-B119-4970-B652-826363055F7D}.Release|x86.Build.0 = Release|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Debug|x64.Build.0 = Debug|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Debug|x86.Build.0 = Debug|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Release|Any CPU.Build.0 = Release|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Release|x64.ActiveCfg = Release|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Release|x64.Build.0 = Release|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Release|x86.ActiveCfg = Release|Any CPU
+		{5CF1158D-64F6-4981-85CB-B43453A37329}.Release|x86.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(NestedProjects) = preSolution
+		{54CD9E36-B119-4970-B652-826363055F7D} = {41F15E67-7190-CF23-3BC4-77E87134CADD}
+		{5CF1158D-64F6-4981-85CB-B43453A37329} = {56BCE1BF-7CBA-7CE8-203D-A88051F1D642}
+	EndGlobalSection
+EndGlobal

src/Aoc/__Libraries/StellaOps.Aoc/AocForbiddenKeys.cs

@@ -0,0 +1,25 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Aoc;
+
+public static class AocForbiddenKeys
+{
+    private static readonly ImmutableHashSet<string> ForbiddenTopLevel = new[]
+    {
+        "severity",
+        "cvss",
+        "cvss_vector",
+        "effective_status",
+        "effective_range",
+        "merged_from",
+        "consensus_provider",
+        "reachability",
+        "asset_criticality",
+        "risk_score",
+    }.ToImmutableHashSet(StringComparer.OrdinalIgnoreCase);
+
+    public static bool IsForbiddenTopLevel(string propertyName) => ForbiddenTopLevel.Contains(propertyName);
+
+    public static bool IsDerivedField(string propertyName)
+        => propertyName.StartsWith("effective_", StringComparison.OrdinalIgnoreCase);
+}

src/Aoc/__Libraries/StellaOps.Aoc/AocGuardException.cs

@@ -0,0 +1,17 @@
+using System;
+using System.Collections.Immutable;
+
+namespace StellaOps.Aoc;
+
+public sealed class AocGuardException : Exception
+{
+    public AocGuardException(AocGuardResult result)
+        : base("AOC guard validation failed.")
+    {
+        Result = result ?? throw new ArgumentNullException(nameof(result));
+    }
+
+    public AocGuardResult Result { get; }
+
+    public ImmutableArray<AocViolation> Violations => Result.Violations;
+}

src/Aoc/__Libraries/StellaOps.Aoc/AocGuardExtensions.cs

@@ -0,0 +1,22 @@
+using System.Text.Json;
+
+namespace StellaOps.Aoc;
+
+public static class AocGuardExtensions
+{
+    public static AocGuardResult ValidateOrThrow(this IAocGuard guard, JsonElement document, AocGuardOptions? options = null)
+    {
+        if (guard is null)
+        {
+            throw new ArgumentNullException(nameof(guard));
+        }
+
+        var result = guard.Validate(document, options);
+        if (!result.IsValid)
+        {
+            throw new AocGuardException(result);
+        }
+
+        return result;
+    }
+}

src/Aoc/__Libraries/StellaOps.Aoc/AocGuardOptions.cs

@@ -0,0 +1,29 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Aoc;
+
+public sealed record AocGuardOptions
+{
+    private static readonly ImmutableHashSet<string> DefaultRequiredTopLevel = new[]
+    {
+        "tenant",
+        "source",
+        "upstream",
+        "content",
+        "linkset",
+    }.ToImmutableHashSet(StringComparer.OrdinalIgnoreCase);
+
+    public static AocGuardOptions Default { get; } = new();
+
+    public ImmutableHashSet<string> RequiredTopLevelFields { get; init; } = DefaultRequiredTopLevel;
+
+    /// <summary>
+    /// When true, signature metadata is required under upstream.signature.
+    /// </summary>
+    public bool RequireSignatureMetadata { get; init; } = true;
+
+    /// <summary>
+    /// When true, tenant must be a non-empty string.
+    /// </summary>
+    public bool RequireTenant { get; init; } = true;
+}

src/Aoc/__Libraries/StellaOps.Aoc/AocGuardResult.cs

@@ -0,0 +1,14 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Aoc;
+
+public sealed record AocGuardResult(bool IsValid, ImmutableArray<AocViolation> Violations)
+{
+    public static AocGuardResult Success { get; } = new(true, ImmutableArray<AocViolation>.Empty);
+
+    public static AocGuardResult FromViolations(IEnumerable<AocViolation> violations)
+    {
+        var array = violations.ToImmutableArray();
+        return array.IsDefaultOrEmpty ? Success : new(false, array);
+    }
+}

src/Aoc/__Libraries/StellaOps.Aoc/AocViolation.cs

@@ -0,0 +1,13 @@
+using System.Text.Json.Serialization;
+
+namespace StellaOps.Aoc;
+
+public sealed record AocViolation(
+    [property: JsonPropertyName("code")] AocViolationCode Code,
+    [property: JsonPropertyName("errorCode")] string ErrorCode,
+    [property: JsonPropertyName("path")] string Path,
+    [property: JsonPropertyName("message")] string Message)
+{
+    public static AocViolation Create(AocViolationCode code, string path, string message)
+        => new(code, code.ToErrorCode(), path, message);
+}

src/Aoc/__Libraries/StellaOps.Aoc/AocViolationCode.cs

@@ -0,0 +1,34 @@
+namespace StellaOps.Aoc;
+
+public enum AocViolationCode
+{
+    None = 0,
+    ForbiddenField,
+    MergeAttempt,
+    IdempotencyViolation,
+    MissingProvenance,
+    SignatureInvalid,
+    DerivedFindingDetected,
+    UnknownField,
+    MissingRequiredField,
+    InvalidTenant,
+    InvalidSignatureMetadata,
+}
+
+public static class AocViolationCodeExtensions
+{
+    public static string ToErrorCode(this AocViolationCode code) => code switch
+    {
+        AocViolationCode.ForbiddenField => "ERR_AOC_001",
+        AocViolationCode.MergeAttempt => "ERR_AOC_002",
+        AocViolationCode.IdempotencyViolation => "ERR_AOC_003",
+        AocViolationCode.MissingProvenance => "ERR_AOC_004",
+        AocViolationCode.SignatureInvalid => "ERR_AOC_005",
+        AocViolationCode.DerivedFindingDetected => "ERR_AOC_006",
+        AocViolationCode.UnknownField => "ERR_AOC_007",
+        AocViolationCode.MissingRequiredField => "ERR_AOC_004",
+        AocViolationCode.InvalidTenant => "ERR_AOC_004",
+        AocViolationCode.InvalidSignatureMetadata => "ERR_AOC_005",
+        _ => "ERR_AOC_000",
+    };
+}

src/Aoc/__Libraries/StellaOps.Aoc/AocWriteGuard.cs

@@ -0,0 +1,127 @@
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Text.Json;
+
+namespace StellaOps.Aoc;
+
+public interface IAocGuard
+{
+    AocGuardResult Validate(JsonElement document, AocGuardOptions? options = null);
+}
+
+public sealed class AocWriteGuard : IAocGuard
+{
+    public AocGuardResult Validate(JsonElement document, AocGuardOptions? options = null)
+    {
+        options ??= AocGuardOptions.Default;
+        var violations = ImmutableArray.CreateBuilder<AocViolation>();
+        var presentTopLevel = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var property in document.EnumerateObject())
+        {
+            presentTopLevel.Add(property.Name);
+
+            if (AocForbiddenKeys.IsForbiddenTopLevel(property.Name))
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.ForbiddenField, $"/{property.Name}", $"Field '{property.Name}' is forbidden in AOC documents."));
+                continue;
+            }
+
+            if (AocForbiddenKeys.IsDerivedField(property.Name))
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.DerivedFindingDetected, $"/{property.Name}", $"Derived field '{property.Name}' must not be written during ingestion."));
+            }
+        }
+
+        foreach (var required in options.RequiredTopLevelFields)
+        {
+            if (!document.TryGetProperty(required, out var element) || element.ValueKind is JsonValueKind.Null or JsonValueKind.Undefined)
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.MissingRequiredField, $"/{required}", $"Required field '{required}' is missing."));
+                continue;
+            }
+
+            if (options.RequireTenant && string.Equals(required, "tenant", StringComparison.OrdinalIgnoreCase))
+            {
+                if (element.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(element.GetString()))
+                {
+                    violations.Add(AocViolation.Create(AocViolationCode.InvalidTenant, "/tenant", "Tenant must be a non-empty string."));
+                }
+            }
+        }
+
+        if (document.TryGetProperty("upstream", out var upstream) && upstream.ValueKind == JsonValueKind.Object)
+        {
+            if (!upstream.TryGetProperty("content_hash", out var contentHash) || contentHash.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(contentHash.GetString()))
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.MissingProvenance, "/upstream/content_hash", "Upstream content hash is required."));
+            }
+
+            if (!upstream.TryGetProperty("signature", out var signature) || signature.ValueKind != JsonValueKind.Object)
+            {
+                if (options.RequireSignatureMetadata)
+                {
+                    violations.Add(AocViolation.Create(AocViolationCode.MissingProvenance, "/upstream/signature", "Signature metadata is required."));
+                }
+            }
+            else if (options.RequireSignatureMetadata)
+            {
+                ValidateSignature(signature, violations);
+            }
+        }
+        else
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.MissingRequiredField, "/upstream", "Upstream metadata is required."));
+        }
+
+        if (document.TryGetProperty("content", out var content) && content.ValueKind == JsonValueKind.Object)
+        {
+            if (!content.TryGetProperty("raw", out var raw) || raw.ValueKind is JsonValueKind.Null or JsonValueKind.Undefined)
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.MissingProvenance, "/content/raw", "Raw upstream payload must be preserved."));
+            }
+        }
+        else
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.MissingRequiredField, "/content", "Content metadata is required."));
+        }
+
+        if (!document.TryGetProperty("linkset", out var linkset) || linkset.ValueKind != JsonValueKind.Object)
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.MissingRequiredField, "/linkset", "Linkset metadata is required."));
+        }
+
+        return AocGuardResult.FromViolations(violations);
+    }
+
+    private static void ValidateSignature(JsonElement signature, ImmutableArray<AocViolation>.Builder violations)
+    {
+        if (!signature.TryGetProperty("present", out var presentElement) || presentElement.ValueKind is not (JsonValueKind.True or JsonValueKind.False))
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.InvalidSignatureMetadata, "/upstream/signature/present", "Signature metadata must include 'present' boolean."));
+            return;
+        }
+
+        var signaturePresent = presentElement.GetBoolean();
+
+        if (!signaturePresent)
+        {
+                return;
+            }
+
+            if (!signature.TryGetProperty("format", out var formatElement) || formatElement.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(formatElement.GetString()))
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.InvalidSignatureMetadata, "/upstream/signature/format", "Signature format is required when signature is present."));
+        }
+
+        if (!signature.TryGetProperty("sig", out var sigElement) || sigElement.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(sigElement.GetString()))
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.SignatureInvalid, "/upstream/signature/sig", "Signature payload is required when signature is present."));
+        }
+
+        if (!signature.TryGetProperty("key_id", out var keyIdElement) || keyIdElement.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(keyIdElement.GetString()))
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.InvalidSignatureMetadata, "/upstream/signature/key_id", "Signature key identifier is required when signature is present."));
+        }
+    }
+}

src/Aoc/__Libraries/StellaOps.Aoc/ServiceCollectionExtensions.cs

@@ -0,0 +1,17 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace StellaOps.Aoc;
+
+public static class ServiceCollectionExtensions
+{
+    public static IServiceCollection AddAocGuard(this IServiceCollection services)
+    {
+        if (services is null)
+        {
+            throw new ArgumentNullException(nameof(services));
+        }
+
+        services.AddSingleton<IAocGuard, AocWriteGuard>();
+        return services;
+    }
+}

src/Aoc/__Libraries/StellaOps.Aoc/StellaOps.Aoc.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>preview</LangVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0-rc.2.25502.107" />
+  </ItemGroup>
+</Project>

src/Aoc/__Tests/StellaOps.Aoc.Tests/AocWriteGuardTests.cs

@@ -0,0 +1,113 @@
+using System.Text.Json;
+using StellaOps.Aoc;
+
+namespace StellaOps.Aoc.Tests;
+
+public sealed class AocWriteGuardTests
+{
+    private static readonly AocWriteGuard Guard = new();
+
+    [Fact]
+    public void Validate_ReturnsSuccess_ForMinimalValidDocument()
+    {
+        using var document = JsonDocument.Parse("""
+        {
+          "tenant": "default",
+          "source": {"vendor": "osv"},
+          "upstream": {
+            "upstream_id": "GHSA-xxxx",
+            "content_hash": "sha256:abc",
+            "signature": { "present": false }
+          },
+          "content": {
+            "format": "OSV",
+            "raw": {"id": "GHSA-xxxx"}
+          },
+          "linkset": {}
+        }
+        """);
+
+        var result = Guard.Validate(document.RootElement);
+
+        Assert.True(result.IsValid);
+        Assert.Empty(result.Violations);
+    }
+
+    [Fact]
+    public void Validate_FlagsMissingTenant()
+    {
+        using var document = JsonDocument.Parse("""
+        {
+          "source": {"vendor": "osv"},
+          "upstream": {
+            "upstream_id": "GHSA-xxxx",
+            "content_hash": "sha256:abc",
+            "signature": { "present": false }
+          },
+          "content": {
+            "format": "OSV",
+            "raw": {"id": "GHSA-xxxx"}
+          },
+          "linkset": {}
+        }
+        """);
+
+        var result = Guard.Validate(document.RootElement);
+
+        Assert.False(result.IsValid);
+        Assert.Contains(result.Violations, v => v.ErrorCode == "ERR_AOC_004" && v.Path == "/tenant");
+    }
+
+    [Fact]
+    public void Validate_FlagsForbiddenField()
+    {
+        using var document = JsonDocument.Parse("""
+        {
+          "tenant": "default",
+          "severity": "high",
+          "source": {"vendor": "osv"},
+          "upstream": {
+            "upstream_id": "GHSA-xxxx",
+            "content_hash": "sha256:abc",
+            "signature": { "present": false }
+          },
+          "content": {
+            "format": "OSV",
+            "raw": {"id": "GHSA-xxxx"}
+          },
+          "linkset": {}
+        }
+        """);
+
+        var result = Guard.Validate(document.RootElement);
+
+        Assert.False(result.IsValid);
+        Assert.Contains(result.Violations, v => v.ErrorCode == "ERR_AOC_001" && v.Path == "/severity");
+    }
+
+    [Fact]
+    public void Validate_FlagsInvalidSignatureMetadata()
+    {
+        using var document = JsonDocument.Parse("""
+        {
+          "tenant": "default",
+          "source": {"vendor": "osv"},
+          "upstream": {
+            "upstream_id": "GHSA-xxxx",
+            "content_hash": "sha256:abc",
+            "signature": { "present": true, "format": "dsse" }
+          },
+          "content": {
+            "format": "OSV",
+            "raw": {"id": "GHSA-xxxx"}
+          },
+          "linkset": {}
+        }
+        """);
+
+        var result = Guard.Validate(document.RootElement);
+
+        Assert.False(result.IsValid);
+        Assert.Contains(result.Violations, v => v.ErrorCode == "ERR_AOC_005" && v.Path.Contains("/sig"));
+    }
+}

src/Aoc/__Tests/StellaOps.Aoc.Tests/StellaOps.Aoc.Tests.csproj

@@ -0,0 +1,42 @@
+<?xml version='1.0' encoding='utf-8'?>
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>preview</LangVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <OutputType>Exe</OutputType>
+    <IsPackable>false</IsPackable>
+    <UseConcelierTestInfra>false</UseConcelierTestInfra>
+
+    
+    
+    
+    
+    
+    
+    
+    
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="xunit.v3" Version="3.0.0" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.3" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content Include="xunit.runner.json" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../../__Libraries/StellaOps.Aoc/StellaOps.Aoc.csproj" />
+  </ItemGroup>
+
+</Project>

src/Aoc/__Tests/StellaOps.Aoc.Tests/UnitTest1.cs

@@ -0,0 +1,10 @@
+namespace StellaOps.Aoc.Tests;
+
+public class UnitTest1
+{
+    [Fact]
+    public void Test1()
+    {
+
+    }
+}

src/Aoc/__Tests/StellaOps.Aoc.Tests/xunit.runner.json

@@ -0,0 +1,3 @@
+{
+    "$schema": "https://xunit.net/schema/current/xunit.runner.schema.json"
+}