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
| Service | DI Key | Type |
|---|---|---|
| Session store | security:sessions | SessionStore |
| Cookie manager | security:cookies | *CookieManager |
| CSRF protection | security:csrf | *CSRFProtection |
| Rate limiter | security:ratelimit | *MemoryRateLimiter |
| Security headers | security:headers | *SecurityHeadersManager |
| Password hasher | security:passwords | *PasswordHasher |
| JWT manager | security:jwt | *JWTManager |
| CORS manager | security:cors | *CORSManager |
| API key manager | security:apikeys | *APIKeyManager |
| Audit logger | security: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 requirementsAudit 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 routeKey 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?