Security

Security

Sessions, CSRF, JWT, rate limiting, CORS, API keys, password hashing, and audit logging

Overview

github.com/xraph/forge/extensions/security is a comprehensive security toolkit that registers multiple independent security services in the DI container: session management, CSRF protection, JWT token handling, rate limiting, CORS, API key management, password hashing, security headers, and audit logging. Each component can be enabled/disabled independently and optionally auto-applied as middleware.

What It Registers

ServiceDI KeyType
Session storesecurity:sessionsSessionStore
Cookie managersecurity:cookies*CookieManager
CSRF protectionsecurity:csrf*CSRFProtection
Rate limitersecurity:ratelimit*MemoryRateLimiter
Security headerssecurity:headers*SecurityHeadersManager
Password hashersecurity:passwords*PasswordHasher
JWT managersecurity:jwt*JWTManager
CORS managersecurity:cors*CORSManager
API key managersecurity:apikeys*APIKeyManager
Audit loggersecurity:audit*AuditLogger

Quick Start

package main

import (
    "context"
    "net/http"
    "time"

    "github.com/xraph/forge"
    "github.com/xraph/forge/extensions/security"
)

func main() {
    app := forge.NewApp(forge.AppConfig{Name: "my-app", Version: "1.0.0"})

    // Register the security extension with desired features
    app.RegisterExtension(security.NewExtension(
        security.WithSession(true, "inmemory", 24*time.Hour),
        security.WithJWT(true, "HS256", "my-secret-key"),
        security.WithRateLimit(true, 200, time.Minute),
        security.WithCORS(true, "*"),
        security.WithCSRF(true),
        security.WithAPIKey(true, "header:X-API-Key"),
    ))

    ctx := context.Background()
    app.Start(ctx)
    defer app.Stop(ctx)

    // --- JWT Authentication ---
    // Resolve the JWT manager
    jwtManager := app.Container().MustResolve("security:jwt").(*security.JWTManager)

    // Generate a token
    token, _ := jwtManager.GenerateToken(&security.JWTClaims{
        UserID:   "user-123",
        Username: "alice",
        Email:    "alice@example.com",
        Roles:    []string{"admin"},
    })
    _ = token // Send to client

    // Protect routes with JWT middleware
    api := app.Group("/api")
    api.Use(security.JWTMiddleware(jwtManager))
    api.GET("/me", func(ctx forge.Context) error {
        claims, ok := security.GetJWTClaims(ctx)
        if !ok {
            return ctx.String(http.StatusUnauthorized, "no claims")
        }
        return ctx.JSON(http.StatusOK, map[string]any{
            "userId": claims.UserID,
            "email":  claims.Email,
            "roles":  claims.Roles,
        })
    })

    // Require specific roles
    admin := api.Group("/admin")
    admin.Use(security.RequireRoles("admin"))
    admin.GET("/dashboard", func(ctx forge.Context) error {
        return ctx.String(http.StatusOK, "admin dashboard")
    })
}

Session Management

// Resolve session components
store := app.Container().MustResolve("security:sessions").(security.SessionStore)
cookieManager := app.Container().MustResolve("security:cookies").(*security.CookieManager)

// Create a session (e.g., in login handler)
app.POST("/login", func(ctx forge.Context) error {
    // ... validate credentials ...
    session, err := security.CreateSession(
        ctx.Context(),
        ctx.Response(),
        "user-123",
        store,
        cookieManager,
        sessionConfig,
        map[string]any{"ip": ctx.Request().RemoteAddr},
    )
    if err != nil {
        return ctx.String(http.StatusInternalServerError, "session error")
    }
    return ctx.JSON(http.StatusOK, map[string]string{"sessionId": session.ID})
})

// Read session in protected routes
app.GET("/profile", func(ctx forge.Context) error {
    session, ok := security.GetSessionFromForgeContext(ctx)
    if !ok {
        return ctx.String(http.StatusUnauthorized, "no session")
    }
    return ctx.JSON(http.StatusOK, map[string]any{
        "userId": session.GetUserID(),
        "data":   session.Data,
    })
})

// Destroy session on logout
app.POST("/logout", func(ctx forge.Context) error {
    security.DestroySession(ctx.Context(), ctx.Response(), store, cookieManager, "forge_session")
    return ctx.String(http.StatusOK, "logged out")
})

API Key Management

apiKeyManager := app.Container().MustResolve("security:apikeys").(*security.APIKeyManager)

// Generate and register an API key
key, _ := apiKeyManager.GenerateAPIKey("myapp")
apiKeyManager.CreateAPIKey(&security.APIKeyInfo{
    Key:    key,
    Name:   "Production Key",
    UserID: "user-123",
    Scopes: []string{"read", "write"},
})

// Protect routes with API key middleware
external := app.Group("/external")
external.Use(security.APIKeyMiddleware(apiKeyManager))

// Require specific scopes
external.DELETE("/resources/:id", security.RequireScopes("write", "delete"), func(ctx forge.Context) error {
    info, _ := security.GetAPIKeyInfo(ctx)
    // info.Name, info.UserID, info.Scopes
    return ctx.String(http.StatusOK, "deleted")
})

Password Hashing

hasher := app.Container().MustResolve("security:passwords").(*security.PasswordHasher)

// Hash a password
hash, err := hasher.Hash("user-password-123")

// Verify a password
match, err := hasher.Verify("user-password-123", hash)

// Check if rehashing is needed (e.g., after config change)
needsRehash, _ := hasher.NeedsRehash(hash)

// Password strength checking
strength := security.CheckPasswordStrength("myP@ssw0rd!")
// Returns: PasswordVeryWeak, PasswordWeak, PasswordFair, PasswordStrong, PasswordVeryStrong

// Validate password against policy
err = security.ValidatePassword("pass", 8, 72, true, true, true, true)
// Returns error if password doesn't meet requirements

Audit Logging

auditLogger := app.Container().MustResolve("security:audit").(*security.AuditLogger)

// Apply audit middleware to log all requests
app.Use(security.AuditMiddleware(auditLogger))

// Log specific security events
security.LogAuthEvent(auditLogger, ctx, "login_success", "success", "user-123", map[string]any{
    "ip": "192.168.1.1",
    "method": "jwt",
})

security.LogSecurityEvent(auditLogger, ctx, "suspicious_activity", "warning", "multiple failed logins", map[string]any{
    "attempts": 5,
    "ip": "10.0.0.1",
})

security.LogAdminEvent(auditLogger, ctx, "user_deleted", "success", "admin-1", "delete_user", map[string]any{
    "targetUser": "user-456",
})

Auto-Apply Middleware

The security extension implements forge.MiddlewareExtension. When AutoApplyMiddleware is enabled for a component, its middleware is automatically applied to all routes without manual wiring:

app.RegisterExtension(security.NewExtension(
    security.WithAutoApplyMiddleware(true),      // Session
    security.WithAutoApplyCSRF(true),            // CSRF
    security.WithAutoApplyRateLimit(true),       // Rate limiting
    security.WithAutoApplySecurityHeaders(true), // Security headers
    security.WithAutoApplyJWT(true),             // JWT
    security.WithAutoApplyCORS(true),            // CORS
    security.WithAutoApplyAPIKey(true),          // API keys
    security.WithAutoApplyAudit(true),           // Audit logging
))
// All enabled middleware is automatically applied to every route

Key Concepts

  • Sessions -- in-memory session store with configurable cookie name, TTL, idle timeout, and auto-apply middleware. Sessions store arbitrary key-value data per user.
  • CSRF -- token-based CSRF protection using header or form field extraction. Configurable safe methods (GET, HEAD, OPTIONS, TRACE).
  • JWT -- generate and validate JSON Web Tokens with HS256/HS384/HS512/RS256/RS384/RS512 signing. Claims include user ID, email, roles. Supports refresh tokens.
  • Rate limiting -- per-IP token-bucket rate limiting with configurable requests per window and skip paths.
  • CORS -- origin, method, and header validation with preflight handling and configurable max age.
  • API keys -- generate, validate, and manage API keys with scope-based authorization. Custom validator support.
  • Password hashing -- Argon2id (default) or bcrypt hashing with configurable parameters.
  • Security headers -- X-Frame-Options, Content-Security-Policy, HSTS, X-Content-Type-Options, Referrer-Policy.
  • Audit logging -- log authentication events, request/response details, and security events with configurable levels and exclude paths.

Detailed Pages

How is this guide?

On this page