router

func DefaultSecurityMiddleware ¶

func DefaultSecurityMiddleware(next http.Handler) http.Handler

DefaultSecurityMiddleware applies a standard set of security protections.

This is a convenience middleware that combines:

• SecurityHeadersMiddleware (OWASP security headers)
• MaxRequestBodyMiddleware with 1MB limit (DoS protection)

This provides a good security baseline for most applications. Apply this middleware early in your middleware chain (before authentication) to protect all routes.

Usage:

r := chi.NewRouter()
r.Use(router.DefaultSecurityMiddleware)
r.Use(core.AegisContextMiddleware())
// ... rest of your routes

func MaxRequestBodyMiddleware ¶

func MaxRequestBodyMiddleware(maxBytes int64) func(http.Handler) http.Handler

MaxRequestBodyMiddleware limits the size of HTTP request bodies.

This middleware wraps the request body with http.MaxBytesReader, which enforces a size limit. If a request exceeds the limit, reading the body will fail and the connection will be closed.

Benefits:

• Prevents memory exhaustion from large requests
• Prevents network bandwidth abuse
• Protects against ZIP bomb attacks
• Limits upload file sizes

Parameters:

• maxBytes: Maximum allowed request body size in bytes

Usage:

// Apply 1MB limit to all routes
r.Use(router.MaxRequestBodyMiddleware(1 << 20))

// Apply 10MB limit for file upload routes
uploadRouter.Use(router.MaxRequestBodyMiddleware(10 << 20))

func MountRoutes ¶

func MountRoutes(router Router, authService *core.AuthService, config *core.AuthConfig, prefix string, rateLimiter *core.RateLimiter)

MountRoutes mounts all core Aegis authentication routes to the provided router.

This function registers handlers for:

Email+Password Routes (if config.EnableEmailPassword is true):

POST {prefix}/login - Authenticate with email+password
POST {prefix}/signup - Register new account

Protected Routes (require authentication):

POST {prefix}/logout - Invalidate session
GET  {prefix}/session - Get current session with user data
GET  {prefix}/sessions - List all user sessions
DELETE {prefix}/sessions/:id - Revoke specific session
DELETE {prefix}/sessions - Revoke all sessions

Public Routes:

POST {prefix}/session/refresh - Refresh session with refresh token

Route Grouping:

All core authentication routes are grouped under "Default" for OpenAPI documentation. Session management routes are additionally tagged with "Session".

Note: Route metadata for login/signup is always registered for OpenAPI documentation, but the actual handlers are only mounted when EnableEmailPassword is true. User data is returned with session endpoints, not as a separate /user endpoint.

Rate Limiting:

If a rateLimiter is provided, it's applied to the refresh endpoint to prevent token brute force attacks. Other routes can be rate-limited by plugins or custom middleware.

Parameters:

• router: HTTP router implementing the Router interface
• authService: Core authentication service with all sub-services
• config: Authentication configuration (controls which routes are enabled)
• prefix: URL prefix for all routes (e.g., "/auth", "/api/v1/auth")
• rateLimiter: Optional rate limiter for public endpoints (can be nil)

Example:

router := chi.NewRouter()
authService := core.NewAuthService(...)
config := &core.AuthConfig{EnableEmailPassword: true}

router.MountRoutes(router, authService, config, "/auth", nil)
// Routes mounted:
//   POST /auth/login
//   POST /auth/signup
//   POST /auth/logout
//   GET  /auth/user
//   ... etc

func NormalizePathToOpenAPI ¶

func NormalizePathToOpenAPI(path string) string

NormalizePathToOpenAPI converts router parameter syntax to OpenAPI path syntax.

Different HTTP routers use different syntax for path parameters:

• Chi, Gin, Echo: /users/:id/posts/:postId
• Gorilla Mux: /users/{id}/posts/{postId}
• OpenAPI spec: /users/{id}/posts/{postId}

This function normalizes paths from :param syntax (chi/gin/echo) to {param} syntax (OpenAPI spec) for automatic API documentation generation.

Conversion rules:

• :id → {id}
• :userId → {userId}
• :post_id → {post_id}
• Parameter names can contain: a-z, A-Z, 0-9, _

Examples:

NormalizePathToOpenAPI("/users/:id")
// Returns: "/users/{id}"

NormalizePathToOpenAPI("/organizations/:orgId/members/:userId")
// Returns: "/organizations/{orgId}/members/{userId}"

NormalizePathToOpenAPI("/static/file.css")
// Returns: "/static/file.css" (unchanged, no parameters)

func SecurityHeadersMiddleware ¶

func SecurityHeadersMiddleware(next http.Handler) http.Handler

SecurityHeadersMiddleware adds security headers to all HTTP responses.

This middleware implements OWASP security best practices by adding headers that protect against common web vulnerabilities:

Headers added:

• X-Content-Type-Options: nosniff Prevents MIME type sniffing (prevents browsers from interpreting files as different MIME type) Protects against: Drive-by download attacks

• X-Frame-Options: DENY Prevents the page from being embedded in <iframe>, <frame>, or <object> Protects against: Clickjacking attacks

• X-XSS-Protection: 1; mode=block Enables browser XSS filter (legacy, mostly replaced by CSP) Protects against: Reflected XSS attacks in older browsers

• Referrer-Policy: strict-origin-when-cross-origin Controls how much referrer information is sent with requests Protects against: Information leakage via Referer header

• Content-Security-Policy: default-src 'self' Basic CSP that only allows resources from the same origin Protects against: XSS, data injection, malicious scripts Note: This is a basic policy - override with custom CSP for your needs

Usage:

r.Use(router.SecurityHeadersMiddleware)

Note: The CSP header can be customized by setting it before this middleware runs, or by using a custom middleware that overrides it.