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

ADR-SEC-001: OIDC/JWT Authentication Strategy

Date: 2026-08-04
Status: ✅ APPROVED (AEG-X-005)
Context: Platform authentication & authorization
Decision: OIDC for production, JWT for API service-to-service, Development headers for testing

---

Problem Statement

How should we structure authentication to:

1. Production: Enforce strict OAuth2/OIDC (no direct credentials)
2. Service-to-Service: Use JWT for microservice communication
3. Development/Testing: Allow header-based auth without OAuth setup
4. Security: Ensure no unauthenticated access reaches protected endpoints

---

Decision

Tier 1: Production (OIDC - OAuth2 Authorization Code Flow)

Protocol: OpenID Connect 1.0 (built on OAuth 2.0)

// Production handler: Validates OIDC tokens from identity provider
// - Verifies JWT signature using provider's public key
// - Checks token expiry
// - Enforces required scopes
// - Maps claims to application roles

public class OidcAuthenticationHandler : AuthenticationHandler<OidcOptions>
{
    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        // 1. Extract token from Authorization: Bearer <token>
        var token = GetBearerToken();
        if (token == null) return AuthenticateResult.NoResult();

        try
        {
            // 2. Validate JWT signature using OIDC provider's public key
            var principal = ValidateJwtSignature(token, _oidcOptions.Authority);
            
            // 3. Verify issuer, audience, expiry
            if (!ValidateTokenClaims(principal)) 
                return AuthenticateResult.Fail("Token validation failed");

            // 4. Map OIDC claims to application roles
            AddApplicationRoles(principal, _roleMapping);

            return AuthenticateResult.Success(
                new AuthenticationTicket(principal, Scheme.Name));
        }
        catch (SecurityTokenException ex)
        {
            return AuthenticateResult.Fail($"Token invalid: {ex.Message}");
        }
    }
}

Configuration (appsettings.Production.json):

{
  "Authentication": {
    "Scheme": "OIDC",
    "Authority": "https://auth.example.com",
    "ClientId": "kartsell-api",
    "ClientSecret": "{{from-secure-vault}}",
    "Audience": "https://api.kartsell.example.com"
  }
}

Benefits:

• ✅ No credentials stored in app
• ✅ Centralized identity management
• ✅ MFA-ready (OIDC providers handle MFA)
• ✅ Standards-compliant

---

Tier 2: Service-to-Service (JWT with Shared Secret)

Protocol: JWT (JSON Web Token) with HS256 (HMAC-SHA256) signing

// API-to-API: Service A calls Service B with JWT
// - Service A signs JWT with shared secret
// - Service B verifies JWT with same shared secret
// - JWT includes scopes (e.g., "read:prices", "write:portfolio")

public class JwtBearerAuthenticationHandler : AuthenticationHandler<JwtBearerOptions>
{
    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        var token = GetBearerToken();
        if (token == null) return AuthenticateResult.NoResult();

        try
        {
            // 1. Validate JWT using HS256 (shared secret)
            var principal = _tokenHandler.ValidateToken(token, _tokenValidationParameters);

            // 2. Check token expiry
            var expiryUnix = principal.FindFirst(JwtRegisteredClaimNames.Exp)?.Value;
            if (long.TryParse(expiryUnix, out var expiry))
            {
                if (DateTimeOffset.UtcNow.ToUnixTimeSeconds() > expiry)
                    return AuthenticateResult.Fail("Token expired");
            }

            // 3. Extract scopes (e.g., "read:signals write:portfolio")
            var scopes = principal.FindAll("scope").Select(c => c.Value).ToList();

            return AuthenticateResult.Success(
                new AuthenticationTicket(principal, Scheme.Name));
        }
        catch (SecurityTokenException ex)
        {
            return AuthenticateResult.Fail($"JWT validation failed: {ex.Message}");
        }
    }
}

Example JWT Payload (Service A → Service B):

{
  "iss": "kartsell-model-operations",
  "sub": "00000000-0000-0000-0000-000000000001",
  "aud": "kartsell-signal-engine",
  "scope": "read:signals write:recommendations",
  "iat": 1691126400,
  "exp": 1691130000
}

Benefits:

• ✅ No OAuth provider needed for service-to-service
• ✅ Stateless (no session storage)
• ✅ Scope-based authorization (fine-grained)
• ✅ Can be validated offline (signature check only)

---

Tier 3: Development/Testing (DevelopmentHeader - Restricted)

Protocol: HTTP header-based authentication (Debug mode only)

// Development only: X-KArtSell-User + X-KArtSell-Role headers
// - Enabled ONLY in Debug configuration
// - Disabled (403 Forbidden) in Release

public class DevelopmentHeaderAuthenticationHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!_environment.IsDevelopment())
            return AuthenticateResult.Fail("DevelopmentHeader only allowed in Development mode");

        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 if role not specified

        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));
    }
}

Restrictions:

• ✅ Disabled in Release mode (FailClosedAuthenticationHandler instead)
• ✅ Requires appsettings.Development.json explicit opt-in
• ✅ No credentials validation (only for testing)
• ✅ Not suitable for any environment with real data

---

Security Guarantees

Acceptance Criteria: "비개발 무인증 접근 0, secret/log/prompt 노출 0"

1. No Unauthenticated Access in Non-Development

// FailClosedAuthenticationHandler (Release mode default)
public class FailClosedAuthenticationHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        // Release mode: Always fail, forcing caller to provide valid credentials
        return AuthenticateResult.Fail("Authentication required. Use OIDC bearer token.");
    }
}

Verification:

# Release mode: All unauthenticated requests → 401 Unauthorized
curl http://localhost:5002/api/protected  # → 401 (no header)
curl -H "X-KArtSell-User: test" http://localhost:5002/api/protected  # → 401 (header ignored in Release)

2. Secrets/Logs/Prompts Protected

Secret Protection:

// Configuration: Never log secrets
var jwtSecret = Configuration["Authentication:JwtSecret"]; // From secure vault only
// NOT: Configuration.GetSection("Authentication").GetChildren() // Would expose all secrets

// Logging: Redact sensitive data
Log.Information("User {UserId} authenticated with scope {Scope}", 
    userId, scope); // ✅ Safe: no secrets logged

// NEVER:
Log.Information("Token: {Token}", bearerToken); // ❌ Exposes JWT

// NEVER:
Log.Debug("Full config: {@Config}", Configuration); // ❌ Exposes secrets

Log Redaction (Serilog):

services.AddSerilog((services, config) => config
    .Enrich.FromLogContext()
    .WriteTo.Console(outputTemplate: "{Timestamp:HH:mm:ss} [{Level}] {Message:lj}{NewLine}")
    .Destructure.ToMaximumDepth(2) // Prevent deep object logging
    .Filter.ByExcluding(le => 
        le.MessageTemplate.Text.Contains("Bearer") || // Tokens
        le.MessageTemplate.Text.Contains("token") ||
        le.MessageTemplate.Text.Contains("secret") ||
        le.MessageTemplate.Text.Contains("password")
    ));

Prompt Protection (AI API calls):

// NEVER pass user data to AI without redaction
var userQuestion = "What is the price of AAPL?"; // Safe: business data only

// NEVER:
var systemPrompt = $"User email: {user.Email}, Token: {token}..."; // ❌ Exposes PII + credentials

---

Tier Selection Matrix

Environment	Tier	Handler	Mode	Validation	Status
Production	OIDC	OidcAuthenticationHandler	Release	OIDC provider keys	✅ 401 if invalid
Staging	JWT	JwtBearerAuthenticationHandler	Release	HS256 secret	✅ 401 if invalid
Development	DevelopmentHeader	DevelopmentHeaderAuthenticationHandler	Debug	None (test only)	✅ Allowed
Development	(any tier in Release mode)	FailClosedAuthenticationHandler	Release	—	❌ 403 always

---

Implementation Verification Checklist

Acceptance Evidence: "비개발 무인증 접근 0, secret/log/prompt 노출 0"

✅ 1. No Unauthenticated Access

• All endpoints require Roles() or Policies()
• Architecture test: "Every_module_endpoint_declares_roles_or_policies" PASS
• Release mode uses FailClosedAuthenticationHandler (denies all)
• Test: Unauthenticated request → 401, not 200

✅ 2. Secrets Protected

• JWT secrets: Loaded from Configuration (never in code)
• Test: Grep codebase for hardcoded secrets (none found)
• Logs: No Bearer tokens, secrets, passwords logged
• Test: Serilog redaction filter active in production

✅ 3. Logs Protected

• No full object logging (depth limit = 2)
• No {Token}, {Secret}, {Password} in templates
• Test: Log output audit (verify no PII/credentials)

✅ 4. Prompts Protected

• No user PII passed to AI prompts
• No credentials in system prompts
• Test: AI call audit (verify redaction)

---

Alternatives Considered & Rejected

Alt 1: Basic Auth (Username + Password)

❌ Rejected: Credentials sent on every request (no Bearer token)
❌ Rejected: Difficult MFA integration
❌ Rejected: Stateless storage of passwords

Alt 2: API Key (Static Key)

❌ Rejected: Key rotation difficult
❌ Rejected: No expiry mechanism
❌ Rejected: Key compromise = full access

Alt 3: Session-Based (PHP-style)

❌ Rejected: Stateful (scales poorly)
❌ Rejected: CSRF vulnerable
❌ Rejected: Cannot be used for service-to-service

✅ Chosen: OIDC (Production) + JWT (Service-to-Service) + DevelopmentHeader (Testing)

---

Sign-Off

Role	Approval	Date
Security	✅ APPROVED	2026-08-04
Architect	✅ APPROVED	2026-08-04
Ops/DevOps	✅ APPROVED	2026-08-04

---

Status: ✅ APPROVED & ACTIVE
Implementation: OIDC (production-ready), JWT (service-to-service), DevelopmentHeader (testing only)
Next: Security audit + penetration testing (post-Gate 5)