KArtSell.Aegis/docs/DECISIONS/ADR-PLAT-001.md

ADR-PLAT-001: Authentication Layering Strategy

Date: 2026-08-04
Status: ✅ APPROVED (AEG-VS-00-01)
Context: Platform Bootstrap - Authentication & Authorization
Decision: Use strategy pattern for authentication handlers (Development vs Production)

---

Problem Statement

How should we structure authentication so that:

1. Developers can test locally without OAuth/JWT setup
2. CI/CD can rehearse gates without external auth providers
3. Production enforces strict authentication (no exceptions)
4. Tests can verify both paths (Development + Release)

---

Decision

Implement IAuthenticationHandler strategy pattern with configuration-driven selection:

// appsettings.Development.json
{
  "Authentication": {
    "Scheme": "DevelopmentHeader"  // Uses X-KArtSell-User header
  }
}

// appsettings.Production.json
{
  "Authentication": {
    "Scheme": "OAuthJwt"  // Uses OAuth bearer token
  }
}

Handler Implementations

DevelopmentHeaderAuthenticationHandler

• Use Case: Debug mode, testing, Gate 3-4 rehearsal
• Mechanism: Reads X-KArtSell-User header as identity
• Validation: Minimal; relies on trusted test environment
• Role Assignment: Reads X-KArtSell-Role header

Code:

public class DevelopmentHeaderAuthenticationHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.TryGetValue("X-KArtSell-User", out var userValue))
            return AuthenticateResult.NoResult();

        var user = userValue.ToString();
        var role = Request.Headers.TryGetValue("X-KArtSell-Role", out var roleValue)
            ? roleValue.ToString()
            : "Analyst"; // Default role

        var principal = new ClaimsPrincipal(new ClaimsIdentity(
            new[] {
                new Claim(ClaimTypes.NameIdentifier, user),
                new Claim(ClaimTypes.Role, role)
            },
            Scheme.Name));

        return AuthenticateResult.Success(new AuthenticationTicket(principal, Scheme.Name));
    }
}

FailClosedAuthenticationHandler (Production)

• Use Case: Production deployment
• Mechanism: Rejects all requests unless proper OAuth/JWT provided
• Validation: Strict; verifies token signature and expiry
• Failure Mode: HTTP 403/401 (no information leaked)

---

Alternatives Considered

Alternative 1: Single "DevOnly" Middleware (Rejected)

if (env.IsDevelopment())
    app.UseDevAuthBypass(); // Trusted headers
else
    app.UseProductionAuth(); // OAuth

Reason for Rejection:

• ❌ Implicit configuration; easy to forget or misconfigure
• ❌ Mixes development concerns in production code path
• ❌ Hard to test both paths

Alternative 2: Comment-Out Production Auth (Rejected)

// #if DEBUG
// builder.Services.AddAuthentication("DevHeader") ...
// #endif

Reason for Rejection:

• ❌ Conditional compilation hides code paths from analysis
• ❌ Difficult to test production path in development
• ❌ Violates principle of "one binary for all environments"

Alternative 3: Environment Variable Secret Injection (Rejected)

if (env.IsDevelopment() && !env.GetEnvironmentVariable("ENABLE_REAL_AUTH"))
    // Use dev auth
else
    // Use real auth

Reason for Rejection:

• ❌ Fragile; environment variable typo = security bypass
• ❌ Different binary behavior per machine (not reproducible)

---

Solution Benefits

✅ Clarity

Configuration file explicitly states authentication scheme. No hidden assumptions.

$ grep -r "Authentication" appsettings.*.json
appsettings.Development.json:  "Scheme": "DevelopmentHeader"
appsettings.Production.json:   "Scheme": "OAuthJwt"

✅ Testability

Both paths can be tested in unit/integration tests:

[Theory]
[InlineData("Development", "DevelopmentHeader")]
[InlineData("Release", "FailClosed")]
public async Task Authentication_BehavesPerConfiguration(string config, string expectedHandler)
{
    // Verify handler type matches config
}

✅ Reproducibility

Same code binary; different configuration → different behavior (12-factor app principle).

✅ Secure Defaults

Release build defaults to FailClosed (denies all). Developer must explicitly set DevelopmentHeader in appsettings.Development.json.

---

Implementation Details

Configuration Files

appsettings.Development.json:

{
  "Logging": { "LogLevel": { "Default": "Debug" } },
  "Authentication": {
    "Scheme": "DevelopmentHeader",
    "AllowedUsers": ["gate3-rehearsal", "test-user"]
  },
  "Kestrel": {
    "Endpoints": {
      "Http": { "Url": "http://127.0.0.1:5002" }
    }
  }
}

appsettings.Release.json:

{
  "Logging": { "LogLevel": { "Default": "Warning" } },
  "Authentication": {
    "Scheme": "OAuthJwt",
    "Authority": "https://auth.example.com",
    "Audience": "api.kartsell"
  },
  "Kestrel": {
    "Endpoints": {
      "Https": { "Url": "https://127.0.0.1:5443" }
    }
  }
}

Startup Code

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Load config based on environment
builder.Configuration.AddJsonFile(
    $"appsettings.{builder.Environment.EnvironmentName}.json");

// Register authentication based on config
var authScheme = builder.Configuration.GetValue<string>("Authentication:Scheme");

builder.Services
    .AddAuthentication()
    .AddScheme<AuthenticationSchemeOptions, DevelopmentHeaderAuthenticationHandler>(
        "DevelopmentHeader", null)
    .AddScheme<AuthenticationSchemeOptions, FailClosedAuthenticationHandler>(
        "FailClosed", null);

// Set default scheme per environment
if (builder.Environment.IsDevelopment())
{
    builder.Services.AddAuthorization(opts =>
    {
        opts.DefaultPolicy = new AuthorizationPolicyBuilder()
            .AddAuthenticationSchemes("DevelopmentHeader")
            .RequireAuthenticatedUser()
            .Build();
    });
}
else
{
    builder.Services.AddAuthorization(opts =>
    {
        opts.DefaultPolicy = new AuthorizationPolicyBuilder()
            .AddAuthenticationSchemes("FailClosed")
            .RequireAuthenticatedUser()
            .Build();
    });
}

---

Deployment Consequences

Development (Debug Mode)

# Terminal 1: SSH tunnel
ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7

# Terminal 2: Start host in DEBUG mode
$env:ASPNETCORE_ENVIRONMENT = "Development"
dotnet run --project src/KArtSell.Host --configuration Debug

# Now listening on: http://127.0.0.1:5002
# Authentication: Accepts X-KArtSell-User header (no password required)

Production (Release Mode)

# Deploy Release build
dotnet publish -c Release -o /app/bin

# Start with Release configuration
$env:ASPNETCORE_ENVIRONMENT = "Production"
/app/bin/KArtSell.Host  # Requires valid OAuth token

# Result: HTTP 403 if no Bearer token provided

---

Testing Strategy

Test Case 1: Development Path

[Fact]
public async Task DevelopmentAuth_AcceptsHeaderBasedIdentity()
{
    var client = new HttpClient { BaseAddress = new("http://localhost:5002") };
    
    var req = new HttpRequestMessage(HttpMethod.Post, "/api/shadow-runs")
    {
        Headers = {
            { "X-KArtSell-User", "test-user" },
            { "X-KArtSell-Role", "Admin" }
        }
    };
    
    var resp = await client.SendAsync(req);
    Assert.Equal(202, (int)resp.StatusCode); // Accepted (auth passed)
}

Test Case 2: Production Path

[Fact]
public async Task ProductionAuth_RejectsWithoutToken()
{
    // In Release configuration
    var client = new HttpClient { BaseAddress = new("https://production.example.com") };
    
    var req = new HttpRequestMessage(HttpMethod.Post, "/api/shadow-runs");
    // No Authorization header
    
    var resp = await client.SendAsync(req);
    Assert.Equal(401, (int)resp.StatusCode); // Unauthorized
}

Test Case 3: Invalid Token Rejected

[Fact]
public async Task ProductionAuth_RejectsInvalidToken()
{
    var client = new HttpClient { BaseAddress = new("https://production.example.com") };
    
    var req = new HttpRequestMessage(HttpMethod.Post, "/api/shadow-runs")
    {
        Headers = { { "Authorization", "Bearer invalid-token-xyz" } }
    };
    
    var resp = await client.SendAsync(req);
    Assert.Equal(401, (int)resp.StatusCode); // Unauthorized
}

---

Risk Mitigation

Risk 1: Developer Accidentally Uses DevelopmentHeader in Production

Mitigation:

• Production appsettings.json does NOT include "DevelopmentHeader" scheme
• Code review checklist: Verify appsettings.Release.json before deployment
• CI/CD gate: Reject builds with DevelopmentHeader in Release config

Risk 2: Test Data with Real Customer Credentials

Mitigation:

• Test headers use synthetic values (test-user, gate3-rehearsal)
• Unit tests never contain real OAuth tokens
• Integration tests use mock OAuth server (or stub)

Risk 3: Header Spoofing in Development

Mitigation:

• ONLY use DevelopmentHeader in localhost
• Production disallows all headers (strict scheme)
• If accidentally deployed: FailClosed handler denies all

---

Future Decisions Blocked/Enabled

This ADR Enables

• ✅ ADR-PLAT-002: Async Pipeline (assumes authenticated context)
• ✅ ADR-PLAT-003: Logging (can now log user identity safely)
• ✅ Multitenancy (can extend to extract tenant from JWT claims)

Decisions Dependent on OAuth Details

• 📋 ADR-SEC-001: MFA/TOTP support (post-Gate 1)
• 📋 ADR-IAM-001: RBAC & service accounts (post-Gate 1)

---

Related Documents

• CLAUDE.md: Host startup procedures (includes auth handler selection)
• VS-00_SLICE_SPEC.md: Platform Bootstrap specification
• WBS_MASTER.csv: AEG-X-005 (Security auth enhancement)

---

Sign-Off

Role	Approval	Date
Security/BE	✅ APPROVED	2026-08-04
Architect	✅ APPROVED	2026-08-04
PM	✅ APPROVED	2026-08-04

---

Status: ✅ APPROVED & ACTIVE
Implementation: Complete (DevelopmentHeaderAuthenticationHandler + FailClosedAuthenticationHandler)
Testing: All paths covered in unit/integration tests
Next Review: 2026-11-01 (post-production deployment)