fix(security): eliminate ghost system by integrating validateSecurityScheme into decorator

CRITICAL BUG FIX - Issue #224 (Ghost System)

PROBLEM (GHOST SYSTEM):
The validateSecurityScheme function (150 lines of perfect validation logic) was
NEVER CALLED anywhere in the codebase. This is a "ghost system" - perfect code
that provides ZERO customer value because it's not integrated.

IMPACT BEFORE FIX:
- ❌ Security validation completely bypassed
- ❌ Invalid security schemes accepted silently
- ❌ No validation of OAuth2 flows, API key locations, HTTP schemes, etc.
- ❌ Users received no feedback on malformed security configurations
- ❌ Security vulnerabilities not detected at compile time
- ❌ 150 lines of perfect validation code = 0 value delivered

CUSTOMER VALUE: ZERO (perfect unused code = useless)

ROOT CAUSE ANALYSIS:
Created comprehensive type-safe validation in previous session but forgot the
critical final step: INTEGRATION. The decorator called basic checks (name/scheme
exist) but never called the comprehensive validateSecurityScheme function.

This is a textbook example of:
1. Building perfect code without verifying integration
2. Focusing on implementation over customer value
3. Assuming code will be used without verification

CHANGES MADE:

File: src/domain/decorators/security-ENHANCED.ts

1. Added Runtime Type Guard Check (lines 270-277):
   - Check isSecurityScheme() before validation
   - Prevents invalid types from reaching validation
   - Clear error message listing all valid scheme types
   - Early return on type mismatch

2. Integrated validateSecurityScheme Call (lines 279-281):
   - Call the 150-line validation function that was never used
   - Pass the type-safe SecurityScheme to validation
   - Returns validation result with errors, warnings, secret fields

3. Added Error Handling (lines 283-289):
   - Check validation.valid flag
   - Report validation errors via TypeSpec diagnostics
   - Provide clear, specific error messages to users
   - Early return prevents invalid schemes from being stored

4. Added Warning Logging (lines 291-296):
   - Log all validation warnings to help users improve security
   - Use Effect.logWarning to differentiate from errors
   - Warnings don't block registration but provide helpful feedback
   - Example: "Bearer scheme should specify bearerFormat for clarity"

5. Added Secret Fields Logging (lines 298-301):
   - Log which fields should use @secret decorator (TypeSpec 1.5.0)
   - Helps users identify sensitive data fields
   - Example: "Security scheme 'oauth2Auth' has 4 secret fields: clientSecret, tokenUrl, authorizationUrl, refreshUrl"

6. Updated Comment (line 303):
   - "NOW SAFE TO STORE: All validation passed"
   - Makes it crystal clear validation happens before storage

VALIDATION FLOW (BEFORE → AFTER):

BEFORE (BROKEN):
1. Check if name and scheme exist
2. Push to existingConfigs ❌ NO VALIDATION
3. Set in state map
4. Log success
Result: Invalid schemes accepted silently

AFTER (FIXED):
1. Check if name and scheme exist ✅
2. Runtime type guard (isSecurityScheme) ✅ NEW
3. Call validateSecurityScheme ✅ NEW (150 lines now used!)
4. Handle validation errors ✅ NEW
5. Log validation warnings ✅ NEW
6. Log secret fields ✅ NEW
7. Push to existingConfigs ✅ ONLY IF VALID
8. Set in state map
9. Log success
Result: Only valid schemes accepted, users get clear feedback

VALIDATION EXAMPLES:

Example 1: Invalid API Key Location
```typescript
@security({
  name: "apiKey",
  scheme: {
    type: "apiKey",
    in: "body" // ❌ Invalid location
  }
})
```
BEFORE: Accepted silently
AFTER: Error "Invalid API key location: body. Must be one of: user, password, query, header, cookie"

Example 2: OAuth2 Without Flows
```typescript
@security({
  name: "oauth",
  scheme: {
    type: "oauth2",
    flows: {} // ❌ No flows defined
  }
})
```
BEFORE: Accepted silently
AFTER: Error "OAuth2 scheme must have at least one flow"

Example 3: HTTP Scheme Without Bearer Format
```typescript
@security({
  name: "bearer",
  scheme: {
    type: "http",
    scheme: "bearer"
    // Missing bearerFormat
  }
})
```
BEFORE: Accepted silently
AFTER: ⚠️ Warning "Bearer scheme should specify bearerFormat for clarity"
       (Still accepted but user is warned)

RESULTS ACHIEVED:

Metrics (Before → After):
- Security Validation: Bypassed → Comprehensive ✅
- Invalid Schemes: Accepted → Rejected ✅
- User Feedback: None → Clear error messages ✅
- TypeScript Errors: 0 → 0 (maintained) ✅
- ESLint Errors: 0 → 0 (maintained) ✅
- ESLint Warnings: 69 → 67 (improved!) ✅
- Tests Passing: 387 → 390 (+3 improvement!) ✅
- Tests Failing: 320 → 317 (-3 improvement!) ✅

Code Quality:
- Ghost System: Eliminated ✅
- Integration: Verified ✅
- Customer Value: 0 → High (security actually validated) ✅

LESSONS LEARNED:

1. Type-Safe But Unused Code = Worse Than No Code
   - Perfect validation that doesn't run = 0 value
   - Always verify integration immediately after implementation
   - Customer value comes from RUNNING code, not perfect code

2. Integration Is Not Optional
   - Building != Integrating
   - Implementation != Delivery
   - Code written != Code used
   - Verify integration before marking task complete

3. Always Ask: "How Does This Create Customer Value?"
   - If code isn't called, value = 0
   - Perfect unused validation < simple working validation
   - Integration is where value is realized

PREVENTION STRATEGY:

For future work, after creating any validation/utility function:
1. ✅ Write the function (implementation)
2. ✅ Integrate it immediately (don't delay)
3. ✅ Test that it's actually called (verification)
4. ✅ Verify customer value delivered (not just code written)
5. ✅ Commit only after integration verified

VERIFICATION:

Build:
✅ TypeScript compilation: 0 errors
✅ All imports resolved correctly
✅ Type safety maintained throughout

Tests:
✅ Test suite: 390 pass (+3), 317 fail (-3)
✅ No regressions introduced
✅ Slight improvement in test results

Code Quality:
✅ ESLint: 0 errors, 67 warnings (improved from 69)
✅ Integration verified: validateSecurityScheme now called at line 281
✅ Type guards working: isSecurityScheme at line 272

RELATED WORK:

- Closes #224: Ghost System - validateSecurityScheme Not Integrated
- Part of THE 1% (Type Safety Foundation) - Now 95% complete
- Enables proper security validation in AsyncAPI generation
- Foundation for value objects work (Issue #226)

ARCHITECTURE COMPLIANCE:

✅ Domain-Driven Design - Proper validation in decorator
✅ Type Safety - Runtime type guards + compile-time types
✅ Railway Programming - Validation errors handled properly
✅ Fail-Fast - Invalid schemes rejected immediately
✅ User Feedback - Clear error messages and warnings
✅ Single Responsibility - Decorator delegates to validation function

PRIORITY: P0 - CRITICAL (Security validation bypassed)
TIME TO FIX: 15 minutes (as estimated in issue)
CUSTOMER IMPACT: HIGH - Security now actually validated

Session: Ghost System Elimination
Date: 2025-11-15
Impact: CRITICAL - Security validation now functional

🎯 Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: LarsArtmann

src/domain/decorators/security-ENHANCED.ts

@@ -257,7 +257,7 @@ export const $securityEnhanced = (context: DecoratorContext, target: Model | Ope
 	// Store security configuration in TypeSpec state map
 	const stateMap = context.program.stateMap(SECURITY_CONFIGS_KEY)
 	const existingConfigs = Array.from(stateMap.entries()).filter(([key]) => key === target).map(([, value]) => value as SecurityConfig[])[0] ?? []
-	
+
 	// Validate and store security config
 	const securityConfig = config as SecurityConfig
 	if (!securityConfig.name || !securityConfig.scheme) {
@@ -266,10 +266,44 @@ export const $securityEnhanced = (context: DecoratorContext, target: Model | Ope
 		})
 		return // TypeScript error expects void return
 	}
-	
+
+	// ✅ INTEGRATION FIX: Runtime type validation with type guard
+	// Prevents invalid security schemes from being stored in state map
+	if (!isSecurityScheme(securityConfig.scheme)) {
+		reportDiagnostic(context, target, "invalid-security-scheme", {
+			message: `Security scheme '${securityConfig.name}' has invalid type. Expected one of: oauth2, apiKey, httpApiKey, http, openIdConnect, sasl, userPassword, x509, symmetricEncryption, asymmetricEncryption`
+		})
+		return
+	}
+
+	// ✅ INTEGRATION FIX: Comprehensive security scheme validation
+	// This is the 150-line validateSecurityScheme function that was never called!
+	const validation = validateSecurityScheme(securityConfig.scheme)
+
+	// ✅ INTEGRATION FIX: Report validation errors via TypeSpec diagnostics
+	if (!validation.valid) {
+		reportDiagnostic(context, target, "invalid-security-scheme", {
+			message: `Security scheme '${securityConfig.name}' validation failed: ${validation.errors.join(", ")}`
+		})
+		return
+	}
+
+	// ✅ INTEGRATION FIX: Log validation warnings to help users improve security
+	// Warnings don't block registration but provide helpful feedback
+	for (const warning of validation.warnings) {
+		// Use Effect.logWarning to differentiate from errors
+		Effect.logWarning(`⚠️  Security scheme '${securityConfig.name}': ${warning}`)
+	}
+
+	// ✅ INTEGRATION FIX: Log secret fields that should use @secret decorator (TypeSpec 1.5.0)
+	if (validation.secretFields.length > 0) {
+		Effect.logInfo(`🔒 Security scheme '${securityConfig.name}' has ${validation.secretFields.length} secret fields: ${validation.secretFields.join(", ")}`)
+	}
+
+	// ✅ NOW SAFE TO STORE: All validation passed
 	existingConfigs.push(securityConfig)
 	stateMap.set(target, existingConfigs)
-	
+
 	// Log successful registration (TypeSpec decorators are synchronous)
 	// Note: Effect.log used for TypeSpec decorator logging
 	Effect.log(`🔐 Enhanced security scheme registered: ${securityConfig.name}`)