Security

TrebuchetSecurity

Production-grade security for distributed actors.

Overview

TrebuchetSecurity provides comprehensive security features for Trebuchet distributed actors:

• Authentication: API keys and JWT tokens
• Authorization: Role-based access control (RBAC)
• Rate Limiting: Token bucket and sliding window algorithms
• Request Validation: Payload size limits and input validation

Quick Start

import TrebuchetCloud
import TrebuchetSecurity

// Create security components
let apiAuth = APIKeyAuthenticator(keys: [
    .init(key: "sk_live_abc123", principalId: "service-1", roles: ["service"])
])

let policy = RoleBasedPolicy(rules: [
    .adminFullAccess,
    .userReadOnly
])

let limiter = TokenBucketLimiter(
    requestsPerSecond: 100,
    burstSize: 200
)

let validator = RequestValidator(configuration: .strict)

// Create middleware stack
let authMiddleware = AuthenticationMiddleware(provider: apiAuth)
let authzMiddleware = AuthorizationMiddleware(policy: policy)
let rateLimitMiddleware = RateLimitingMiddleware(limiter: limiter)
let validationMiddleware = ValidationMiddleware(validator: validator)

// Configure gateway with full security
let gateway = CloudGateway(configuration: .init(
    middlewares: [
        validationMiddleware,   // Validate first
        authMiddleware,         // Authenticate
        authzMiddleware,        // Authorize
        rateLimitMiddleware     // Rate limit
    ],
    stateStore: stateStore,
    registry: registry
))

Authentication

Verify user and service identities.

API Key Authentication

Simple, secure authentication for services:

import TrebuchetSecurity

// Configure API keys
let apiAuth = APIKeyAuthenticator(keys: [
    .init(
        key: "sk_live_abc123",
        principalId: "service-worker-1",
        roles: ["service", "worker"]
    ),
    .init(
        key: "sk_admin_xyz789",
        principalId: "admin-bot",
        roles: ["admin"],
        expiresAt: Date().addingTimeInterval(86400) // 24 hours
    )
])

// Authenticate a request
let credentials = Credentials.apiKey(key: "sk_live_abc123")
let principal = try await apiAuth.authenticate(credentials)

print(principal.id) // "service-worker-1"
print(principal.roles) // ["service", "worker"]

Dynamic Key Management

// Create authenticator
let apiAuth = APIKeyAuthenticator()

// Register new keys at runtime
await apiAuth.register(.init(
    key: "sk_new_key",
    principalId: "new-service",
    roles: ["service"]
))

// Revoke compromised keys
await apiAuth.revoke("sk_old_key")

JWT Authentication

Security Warning: The included JWT implementation does NOT validate signatures and is for testing only.

For production, use a proper JWT library:

• swift-jwt
• JWTKit

// Configure JWT validator (testing only)
let jwtAuth = JWTAuthenticator(configuration: .init(
    issuer: "https://auth.example.com",
    audience: "https://api.example.com",
    clockSkew: 60 // Allow 60 seconds clock drift
))

// Authenticate bearer token
let credentials = Credentials.bearer(token: jwtToken)
let principal = try await jwtAuth.authenticate(credentials)

Migration Note (v0.3.0): If using the built-in JWT implementation (not recommended for production):

• SigningKey.symmetric(secret:) → Use SigningKey.hs256(secret:) instead
• SigningKey.asymmetric(publicKey:) → Use SigningKey.es256(publicKey:) instead

For production JWT authentication, integrate a proper JWT library with TrebuchetSecurity's AuthenticationProvider protocol.

Principal

The Principal struct represents an authenticated identity:

public struct Principal: Sendable, Codable {
    public let id: String                    // Unique identifier
    public let type: PrincipalType           // user, service, system
    public let roles: Set<String>            // Assigned roles
    public let attributes: [String: String]  // Custom attributes
    public let authenticatedAt: Date         // Authentication time
    public let expiresAt: Date?              // Optional expiration
}

// Check roles
if principal.hasRole("admin") {
    // Allow admin action
}

if principal.hasAnyRole(["admin", "moderator"]) {
    // Allow privileged action
}

Authorization

Control access to actors and methods with RBAC.

Basic RBAC

import TrebuchetSecurity

// Define access rules
let policy = RoleBasedPolicy(rules: [
    // Admins can do anything
    .init(role: "admin", actorType: "*", method: "*"),

    // Users can only read
    .init(role: "user", actorType: "*", method: "get*"),

    // Workers can invoke GameRoom
    .init(role: "worker", actorType: "GameRoom", method: "*")
])

// Check authorization
let action = Action(actorType: "GameRoom", method: "join")
let resource = Resource(type: "game", id: "room-123")

let allowed = try await policy.authorize(
    principal,
    action: action,
    resource: resource
)

if !allowed {
    throw AuthorizationError.accessDenied
}

Pattern Matching

Rules support wildcard patterns:

// Prefix matching: methods starting with "get"
.init(role: "user", actorType: "*", method: "get*")

// Suffix matching: methods ending with "Status"
.init(role: "monitor", actorType: "*", method: "*Status")

// Exact match: specific actor and method
.init(role: "admin", actorType: "AdminPanel", method: "reset")

// Wildcard: all actors and methods
.init(role: "admin", actorType: "*", method: "*")

Predefined Rules

let policy = RoleBasedPolicy(rules: [
    .adminFullAccess,  // Admin has full access
    .userReadOnly,     // User can only read
    .serviceInvoke     // Service can invoke any method
])

Multi-Role Example

let gamePolicy = RoleBasedPolicy(rules: [
    // Admins can do everything
    .init(role: "admin", actorType: "*", method: "*"),

    // Players can join and leave games
    .init(role: "player", actorType: "GameRoom", method: "join"),
    .init(role: "player", actorType: "GameRoom", method: "leave"),

    // Premium players can create private rooms
    .init(role: "premium", actorType: "GameRoom", method: "create"),

    // Moderators can kick players
    .init(role: "moderator", actorType: "GameRoom", method: "kick"),

    // All users can view lobbies
    .init(role: "user", actorType: "Lobby", method: "get*")
])

Rate Limiting

Protect actors from abuse.

Token Bucket Limiter

Allow controlled bursts while maintaining average rate:

import TrebuchetSecurity

let limiter = TokenBucketLimiter(
    requestsPerSecond: 100,  // Average rate
    burstSize: 200           // Allow bursts up to 200
)

// Check rate limit
let result = try await limiter.checkLimit(key: principal.id)

if !result.allowed {
    throw RateLimitError.limitExceeded(retryAfter: result.retryAfter!)
}

Sliding Window Limiter

Precise per-window limits with smooth transitions:

let limiter = SlidingWindowLimiter(
    maxRequests: 1000,
    windowSize: .seconds(60)
)

let result = try await limiter.checkLimit(key: principal.id)

Rate Limit Result

public struct RateLimitResult {
    let allowed: Bool           // Whether request is allowed
    let remaining: Int          // Remaining requests
    let retryAfter: Duration?   // When to retry if denied
}

Request Validation

Validate incoming requests.

Configuration

let validator = RequestValidator(configuration: .init(
    maxPayloadSize: 1024 * 1024,        // 1MB
    maxActorIDLength: 256,
    maxMethodNameLength: 128,
    allowedMethodNamePattern: "[a-zA-Z][a-zA-Z0-9_]*"
))

// Validate request
try await validator.validate(invocation)

Preset Configurations

// Strict validation (recommended for production)
let validator = RequestValidator(configuration: .strict)

// Lenient validation (for development)
let validator = RequestValidator(configuration: .lenient)

Middleware Integration

Security components integrate via middleware:

import TrebuchetCloud
import TrebuchetSecurity

// Middleware executes in order
let middlewares: [CloudMiddleware] = [
    ValidationMiddleware(validator: validator),     // 1. Validate request
    AuthenticationMiddleware(provider: apiAuth),    // 2. Authenticate
    AuthorizationMiddleware(policy: policy),        // 3. Authorize
    RateLimitingMiddleware(limiter: limiter)        // 4. Rate limit
]

let gateway = CloudGateway(configuration: .init(
    middlewares: middlewares,
    stateStore: stateStore,
    registry: registry
))

Security Flow

1. Request arrives
   ↓
2. ValidationMiddleware validates payload
   ↓
3. AuthenticationMiddleware verifies credentials → Principal
   ↓
4. AuthorizationMiddleware checks permissions
   ↓
5. RateLimitingMiddleware checks rate limits
   ↓
6. Request processed by actor

Security Presets

Development

Permissive settings for local development:

let devAuth = APIKeyAuthenticator(keys: [
    .init(key: "dev_test", principalId: "dev", roles: ["admin"])
])

let devPolicy = RoleBasedPolicy(rules: [
    .init(role: "admin", actorType: "*", method: "*")
], denyByDefault: false)

let devLimiter = TokenBucketLimiter(
    requestsPerSecond: 1000,
    burstSize: 2000
)

let devValidator = RequestValidator(configuration: .init(
    maxPayloadSize: 10 * 1024 * 1024,  // 10MB
    maxActorIDLength: 1000,
    maxMethodNameLength: 500
))

Production

Strict settings for production:

let prodAuth = JWTAuthenticator(configuration: .init(
    issuer: "https://auth.example.com",
    audience: "https://api.example.com"
))

let prodPolicy = RoleBasedPolicy(rules: [
    .adminFullAccess,
    .userReadOnly
])

let prodLimiter = TokenBucketLimiter(
    requestsPerSecond: 10,
    burstSize: 20
)

let prodValidator = RequestValidator(configuration: .strict)

Error Handling

do {
    try await processSecureRequest()
} catch AuthenticationError.invalidCredentials {
    return .unauthorized("Invalid credentials")
} catch AuthenticationError.expired {
    return .unauthorized("Credentials expired")
} catch AuthorizationError.accessDenied {
    return .forbidden("Access denied")
} catch RateLimitError.limitExceeded(let retryAfter) {
    return .tooManyRequests(retryAfter: retryAfter)
} catch ValidationError.payloadTooLarge(let size, let limit) {
    return .requestTooLarge("Payload \(size) exceeds limit \(limit)")
}

Best Practices

Defense in Depth

Use multiple security layers:

// ✅ Multiple security checks
let middleware = [
    ValidationMiddleware(...),      // Validate inputs
    AuthenticationMiddleware(...),  // Verify identity
    AuthorizationMiddleware(...),   // Check permissions
    RateLimitingMiddleware(...)     // Prevent abuse
]

Least Privilege

Grant minimum necessary permissions:

// ✅ Specific permissions
.init(role: "user", actorType: "GameRoom", method: "join")

// ❌ Overly broad permissions
.init(role: "user", actorType: "*", method: "*")

Audit Logging

Log all security decisions:

logger.info("Authorization decision", metadata: [
    "principal": principal.id,
    "action": "\(action.actorType).\(action.method)",
    "resource": resource.id,
    "allowed": "\(allowed)"
])

Secure Defaults

Start strict, relax as needed:

// ✅ Start strict
let validator = RequestValidator(configuration: .strict)

// ❌ Start permissive
let validator = RequestValidator(configuration: .lenient)

Custom Providers

Implement custom authentication:

actor CustomAuthenticator: AuthenticationProvider {
    func authenticate(_ credentials: Credentials) async throws -> Principal {
        guard case .custom(let type, let value) = credentials,
              type == "device-token" else {
            throw AuthenticationError.malformed(reason: "Expected device token")
        }

        let deviceInfo = try await validateDeviceToken(value)

        return Principal(
            id: deviceInfo.deviceId,
            type: .system,
            roles: ["device", "iot"]
        )
    }
}

Implement custom authorization:

actor TimeBasedPolicy: AuthorizationPolicy {
    let allowedHours: ClosedRange<Int>

    func authorize(
        _ principal: Principal,
        action: Action,
        resource: Resource
    ) async throws -> Bool {
        let hour = Calendar.current.component(.hour, from: Date())
        guard allowedHours.contains(hour) else {
            return false
        }
        return principal.hasRole("admin") || principal.hasRole("user")
    }
}

See Also

• Cloud deployment guide for CloudGateway integration
• Observability guide for security event logging
• AWS Lambda guide for production deployment

Converted and distributed by TomeVault — claim your Tome and manage your conversions.