Files
CHORUS/pkg/seqthink/policy/middleware.go
anthonyrawlins 9190c75440 Implement Beat 3: Policy Gate (JWT Authentication)
This commit completes Beat 3 of the SequentialThinkingForCHORUS implementation,
adding KACHING JWT policy enforcement with scope checking.

## Deliverables

### 1. JWT Validation Package (pkg/seqthink/policy/)

**jwt.go** (313 lines): Complete JWT validation system
- `Validator`: JWT token validation with JWKS fetching
- `Claims`: JWT claims structure with scope support
- JWKS fetching and caching (1-hour TTL)
- RSA public key parsing from JWK format
- Space-separated and array scope formats
- Automatic JWKS refresh on cache expiration

**Features**:
- RS256 signature verification
- Expiration and NotBefore validation
- Required scope checking
- JWKS caching to reduce API calls
- Thread-safe key cache with mutex
- Base64 URL encoding/decoding utilities

**jwt_test.go** (296 lines): Comprehensive test suite
- Valid token validation
- Expired token rejection
- Missing scope detection
- Space-separated scopes parsing
- Not-yet-valid token rejection
- JWKS caching behavior verification
- Invalid JWKS server handling
- 5 test scenarios, all passing

### 2. Authorization Middleware

**middleware.go** (75 lines): HTTP authorization middleware
- Bearer token extraction from Authorization header
- Token validation via Validator
- Policy denial metrics tracking
- Optional enforcement (disabled if no JWKS URL)
- Request logging with subject and scopes
- Clean error responses (401 Unauthorized)

**Integration**:
- Wraps `/mcp/tool` endpoint (both encrypted and plaintext)
- Wraps `/mcp/sse` endpoint (both encrypted and plaintext)
- Health and metrics endpoints remain open (no auth)
- Automatic mode detection based on configuration

### 3. Proxy Server Integration

**Updated server.go**:
- Policy middleware initialization in `NewServer()`
- Pre-fetches JWKS on startup
- Auth wrapper for protected endpoints
- Configuration-based enforcement
- Graceful fallback if JWKS unavailable

**Configuration**:
```go
ServerConfig{
    KachingJWKSURL: "https://auth.kaching.services/jwks",
    RequiredScope:  "sequentialthinking.run",
}
```

If both fields are set → policy enforcement enabled
If either is empty → policy enforcement disabled (dev mode)

## Testing Results

### Unit Tests
```
PASS: TestValidateToken (5 scenarios)
  - valid_token with required scope
  - expired_token rejection
  - missing_scope rejection
  - space_separated_scopes parsing
  - not_yet_valid rejection

PASS: TestJWKSCaching
  - Verifies JWKS fetched only once within cache window
  - Verifies JWKS re-fetched after cache expiration

PASS: TestParseScopes (5 scenarios)
  - Single scope parsing
  - Multiple scopes parsing
  - Extra spaces handling
  - Empty string handling
  - Spaces-only handling

PASS: TestInvalidJWKS
  - Handles JWKS server errors gracefully

PASS: TestGetCachedKeyCount
  - Tracks cached key count correctly
```

**All 5 test groups passed (16 total test cases)**

### Integration Verification

**Without Policy** (development):
```bash
export KACHING_JWKS_URL=""
./build/seqthink-wrapper
# → "Policy enforcement disabled"
# → All requests allowed
```

**With Policy** (production):
```bash
export KACHING_JWKS_URL="https://auth.kaching.services/jwks"
export REQUIRED_SCOPE="sequentialthinking.run"
./build/seqthink-wrapper
# → "Policy enforcement enabled"
# → JWKS pre-fetched
# → Authorization: Bearer <token> required
```

## Security Properties

 **Authentication**: RS256 JWT signature verification
 **Authorization**: Scope-based access control
 **Token Validation**: Expiration and not-before checking
 **JWKS Security**: Automatic key rotation support
 **Metrics**: Policy denial tracking for monitoring
 **Graceful Degradation**: Works without JWKS in dev mode
 **Thread Safety**: Concurrent JWKS cache access safe

## API Flow with Policy

### Successful Request:
```
1. Client → POST /mcp/tool
   Authorization: Bearer eyJhbGci...
   Content-Type: application/age
   Body: <encrypted request>

2. Middleware extracts Bearer token
3. Middleware validates JWT signature (JWKS)
4. Middleware checks required scope
5. Request forwarded to handler
6. Handler decrypts request
7. Handler calls MCP server
8. Handler encrypts response
9. Response sent to client
```

### Unauthorized Request:
```
1. Client → POST /mcp/tool
   (missing Authorization header)

2. Middleware checks for header → NOT FOUND
3. Policy denial metric incremented
4. 401 Unauthorized response
5. Request rejected
```

## Configuration Modes

**Full Security** (Beat 2 + Beat 3):
```bash
export AGE_IDENT_PATH=/etc/seqthink/age.key
export AGE_RECIPS_PATH=/etc/seqthink/age.pub
export KACHING_JWKS_URL=https://auth.kaching.services/jwks
export REQUIRED_SCOPE=sequentialthinking.run
```
→ Encryption + Authentication + Authorization

**Development Mode**:
```bash
# No AGE_* or KACHING_* variables set
```
→ Plaintext, no authentication

## Next Steps (Beat 4)

Beat 4 will add deployment infrastructure:
- Docker Swarm service definition
- Network overlay configuration
- Secret management for age keys
- KACHING integration documentation
- End-to-end testing in swarm

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-13 08:48:42 +11:00

81 lines
2.2 KiB
Go

package policy
import (
"net/http"
"strings"
"github.com/rs/zerolog/log"
)
// AuthMiddleware creates HTTP middleware for JWT authentication
type AuthMiddleware struct {
validator *Validator
policyDenials func() // Metrics callback for policy denials
enforcementEnabled bool
}
// NewAuthMiddleware creates a new authentication middleware
func NewAuthMiddleware(validator *Validator, policyDenials func()) *AuthMiddleware {
return &AuthMiddleware{
validator: validator,
policyDenials: policyDenials,
enforcementEnabled: validator != nil,
}
}
// Wrap wraps an HTTP handler with JWT authentication
func (m *AuthMiddleware) Wrap(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// If enforcement is disabled, pass through
if !m.enforcementEnabled {
log.Warn().Msg("Policy enforcement disabled - allowing request")
next.ServeHTTP(w, r)
return
}
// Extract token from Authorization header
authHeader := r.Header.Get("Authorization")
if authHeader == "" {
log.Error().Msg("Missing Authorization header")
m.policyDenials()
http.Error(w, "Unauthorized: missing authorization header", http.StatusUnauthorized)
return
}
// Check Bearer scheme
parts := strings.SplitN(authHeader, " ", 2)
if len(parts) != 2 || parts[0] != "Bearer" {
log.Error().Str("auth_header", authHeader).Msg("Invalid Authorization header format")
m.policyDenials()
http.Error(w, "Unauthorized: invalid authorization format", http.StatusUnauthorized)
return
}
tokenString := parts[1]
// Validate token
claims, err := m.validator.ValidateToken(tokenString)
if err != nil {
log.Error().Err(err).Msg("Token validation failed")
m.policyDenials()
http.Error(w, "Unauthorized: "+err.Error(), http.StatusUnauthorized)
return
}
log.Info().
Str("subject", claims.Subject).
Strs("scopes", claims.Scopes).
Msg("Request authorized")
// Token is valid, pass to next handler
next.ServeHTTP(w, r)
})
}
// WrapFunc wraps an HTTP handler function with JWT authentication
func (m *AuthMiddleware) WrapFunc(next http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
m.Wrap(next).ServeHTTP(w, r)
}
}