Restructure solution layout by module

src/Cartographer/StellaOps.Cartographer/AGENTS.md

@@ -0,0 +1,18 @@
+# StellaOps.Cartographer — Agent Charter
+
+## Mission
+Build and operate the Cartographer service that materializes immutable SBOM property graphs, precomputes layout tiles, and hydrates policy/VEX overlays so other services (API, UI, CLI) can navigate and reason about dependency relationships with context.
+
+## Responsibilities
+- Ingest normalized SBOM projections (CycloneDX/SPDX) and generate versioned graph snapshots with tenant-aware storage.
+- Maintain overlay workers that merge Policy Engine effective findings and VEX metadata onto graph nodes/edges, including path relevance computation.
+- Serve graph APIs for viewport tiles, paths, filters, exports, simulation overlays, and diffing.
+- Coordinate with Policy Engine, Scheduler, Conseiller, Excitator, and Authority to keep overlays current, respect RBAC, and uphold determinism guarantees.
+- Deliver observability (metrics/traces/logs) and performance benchmarks for large graphs (≥50k nodes).
+
+## Expectations
+- Keep builds deterministic; snapshots are write-once and content-addressed.
+- Tenancy and scope enforcement must match Authority policies (`graph:*`, `sbom:read`, `findings:read`).
+- Update `TASKS.md`, `../../docs/implplan/SPRINTS.md` when status changes.
+- Provide fixtures and documentation so UI/CLI teams can simulate graphs offline.
+- Authority integration derives scope names from `StellaOps.Auth.Abstractions.StellaOpsScopes`; avoid hard-coded `graph:*` literals.

src/Cartographer/StellaOps.Cartographer/Options/CartographerAuthorityOptions.cs

@@ -0,0 +1,101 @@
+using System;
+using System.Collections.Generic;
+
+namespace StellaOps.Cartographer.Options;
+
+/// <summary>
+/// Configuration controlling Authority-backed authentication for the Cartographer service.
+/// </summary>
+public sealed class CartographerAuthorityOptions
+{
+    /// <summary>
+    /// Enables Authority-backed authentication for Cartographer endpoints.
+    /// </summary>
+    public bool Enabled { get; set; }
+
+    /// <summary>
+    /// Allows anonymous access when Authority integration is enabled (development only).
+    /// </summary>
+    public bool AllowAnonymousFallback { get; set; }
+
+    /// <summary>
+    /// Authority issuer URL exposed via OpenID discovery.
+    /// </summary>
+    public string Issuer { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Whether HTTPS metadata is required when fetching Authority discovery documents.
+    /// </summary>
+    public bool RequireHttpsMetadata { get; set; } = true;
+
+    /// <summary>
+    /// Optional explicit metadata endpoint for Authority discovery.
+    /// </summary>
+    public string? MetadataAddress { get; set; }
+
+    /// <summary>
+    /// Timeout (seconds) applied to Authority back-channel HTTP calls.
+    /// </summary>
+    public int BackchannelTimeoutSeconds { get; set; } = 30;
+
+    /// <summary>
+    /// Allowed token clock skew (seconds) when validating Authority-issued tokens.
+    /// </summary>
+    public int TokenClockSkewSeconds { get; set; } = 60;
+
+    /// <summary>
+    /// Accepted audiences for Cartographer access tokens.
+    /// </summary>
+    public IList<string> Audiences { get; } = new List<string>();
+
+    /// <summary>
+    /// Scopes required for Cartographer operations.
+    /// </summary>
+    public IList<string> RequiredScopes { get; } = new List<string>();
+
+    /// <summary>
+    /// Tenants permitted to access Cartographer resources.
+    /// </summary>
+    public IList<string> RequiredTenants { get; } = new List<string>();
+
+    /// <summary>
+    /// Networks allowed to bypass authentication enforcement.
+    /// </summary>
+    public IList<string> BypassNetworks { get; } = new List<string>();
+
+    /// <summary>
+    /// Validates configured values and throws <see cref="InvalidOperationException"/> on failure.
+    /// </summary>
+    public void Validate()
+    {
+        if (!Enabled)
+        {
+            return;
+        }
+
+        if (string.IsNullOrWhiteSpace(Issuer))
+        {
+            throw new InvalidOperationException("Cartographer Authority issuer must be configured when Authority integration is enabled.");
+        }
+
+        if (!Uri.TryCreate(Issuer.Trim(), UriKind.Absolute, out var issuerUri))
+        {
+            throw new InvalidOperationException("Cartographer Authority issuer must be an absolute URI.");
+        }
+
+        if (RequireHttpsMetadata && !issuerUri.IsLoopback && !string.Equals(issuerUri.Scheme, Uri.UriSchemeHttps, StringComparison.OrdinalIgnoreCase))
+        {
+            throw new InvalidOperationException("Cartographer Authority issuer must use HTTPS unless running on loopback.");
+        }
+
+        if (BackchannelTimeoutSeconds <= 0)
+        {
+            throw new InvalidOperationException("Cartographer Authority back-channel timeout must be greater than zero seconds.");
+        }
+
+        if (TokenClockSkewSeconds < 0 || TokenClockSkewSeconds > 300)
+        {
+            throw new InvalidOperationException("Cartographer Authority token clock skew must be between 0 and 300 seconds.");
+        }
+    }
+}

src/Cartographer/StellaOps.Cartographer/Options/CartographerAuthorityOptionsConfigurator.cs

@@ -0,0 +1,37 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using StellaOps.Auth.Abstractions;
+
+namespace StellaOps.Cartographer.Options;
+
+/// <summary>
+/// Applies Cartographer-specific defaults to <see cref="CartographerAuthorityOptions"/>.
+/// </summary>
+internal static class CartographerAuthorityOptionsConfigurator
+{
+    /// <summary>
+    /// Ensures required scopes are present and duplicates are removed case-insensitively.
+    /// </summary>
+    /// <param name="options">Target options.</param>
+    public static void ApplyDefaults(CartographerAuthorityOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        EnsureScope(options.RequiredScopes, StellaOpsScopes.GraphRead);
+        EnsureScope(options.RequiredScopes, StellaOpsScopes.GraphWrite);
+    }
+
+    private static void EnsureScope(ICollection<string> scopes, string scope)
+    {
+        ArgumentNullException.ThrowIfNull(scopes);
+        ArgumentException.ThrowIfNullOrEmpty(scope);
+
+        if (scopes.Any(existing => string.Equals(existing, scope, StringComparison.OrdinalIgnoreCase)))
+        {
+            return;
+        }
+
+        scopes.Add(scope);
+    }
+}

src/Cartographer/StellaOps.Cartographer/Program.cs

@@ -0,0 +1,39 @@
+using StellaOps.Cartographer.Options;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Configuration
+    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
+    .AddEnvironmentVariables("CARTOGRAPHER_");
+
+builder.Services.AddOptions();
+builder.Services.AddLogging();
+
+var authoritySection = builder.Configuration.GetSection("Cartographer:Authority");
+var authorityOptions = new CartographerAuthorityOptions();
+authoritySection.Bind(authorityOptions);
+CartographerAuthorityOptionsConfigurator.ApplyDefaults(authorityOptions);
+authorityOptions.Validate();
+
+builder.Services.AddSingleton(authorityOptions);
+builder.Services.AddOptions<CartographerAuthorityOptions>()
+    .Bind(authoritySection)
+    .PostConfigure(CartographerAuthorityOptionsConfigurator.ApplyDefaults);
+
+// TODO: register Cartographer graph builders, overlay workers, and Authority client once implementations land.
+
+var app = builder.Build();
+
+if (!authorityOptions.Enabled)
+{
+    app.Logger.LogWarning("Cartographer Authority authentication is disabled; enable it before production deployments.");
+}
+else if (authorityOptions.AllowAnonymousFallback)
+{
+    app.Logger.LogWarning("Cartographer Authority allows anonymous fallback; disable fallback before production rollout.");
+}
+
+app.MapGet("/healthz", () => Results.Ok(new { status = "ok" }));
+app.MapGet("/readyz", () => Results.Ok(new { status = "warming" }));
+
+app.Run();

src/Cartographer/StellaOps.Cartographer/Properties/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("StellaOps.Cartographer.Tests")]

src/Cartographer/StellaOps.Cartographer/StellaOps.Cartographer.csproj

@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='utf-8'?>
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <LangVersion>preview</LangVersion>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../../__Libraries/StellaOps.Configuration/StellaOps.Configuration.csproj" />
+    <ProjectReference Include="../../__Libraries/StellaOps.DependencyInjection/StellaOps.DependencyInjection.csproj" />
+    <ProjectReference Include="../../Policy/StellaOps.Policy.Engine/StellaOps.Policy.Engine.csproj" />
+    <ProjectReference Include="../../Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOps.Auth.Abstractions.csproj" />
+  </ItemGroup>
+</Project>

src/Cartographer/StellaOps.Cartographer/TASKS.md

@@ -0,0 +1,6 @@
+# Cartographer Task Board — Epic 3: Graph Explorer v1
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| CARTO-GRAPH-21-010 | DONE (2025-10-27) | Cartographer Guild | AUTH-GRAPH-21-001 | Replace hard-coded `graph:*` scope strings in Cartographer services/clients with `StellaOpsScopes` constants; document new dependency. | All scope checks reference `StellaOpsScopes`; documentation updated; unit tests adjusted if needed. |
+
+> 2025-10-26 — Note: awaiting Cartographer service bootstrap. Keep this task open until Cartographer routes exist so we can swap to `StellaOpsScopes` immediately.