Documentation
¶
Overview ¶
Package http provides HTTP handlers for authentication and client management operations.
Package http provides HTTP handlers for authentication and client management operations.
Package http provides HTTP middleware and utilities for authentication.
Package http provides HTTP middleware and utilities for authentication.
Package http provides HTTP middleware and utilities for authentication.
Package http provides HTTP handlers for authentication and client management operations.
Package http provides HTTP handlers for authentication and client management operations.
Package http provides HTTP middleware and utilities for authentication.
Index ¶
- func AuthenticationMiddleware(tokenUseCase authUseCase.TokenUseCase, tokenService authService.TokenService, ...) gin.HandlerFunc
- func AuthorizationMiddleware(capability authDomain.Capability, auditLogUseCase authUseCase.AuditLogUseCase, ...) gin.HandlerFunc
- func GetCapability(ctx context.Context) (authDomain.Capability, bool)
- func GetClient(ctx context.Context) (*authDomain.Client, bool)
- func GetPath(ctx context.Context) (string, bool)
- func RateLimitMiddleware(rps float64, burst int, logger *slog.Logger) gin.HandlerFunc
- func TokenRateLimitMiddleware(rps float64, burst int, logger *slog.Logger) gin.HandlerFunc
- func WithCapability(ctx context.Context, capability authDomain.Capability) context.Context
- func WithClient(ctx context.Context, client *authDomain.Client) context.Context
- func WithPath(ctx context.Context, path string) context.Context
- type AuditLogHandler
- type ClientHandler
- type TokenHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AuthenticationMiddleware ¶
func AuthenticationMiddleware( tokenUseCase authUseCase.TokenUseCase, tokenService authService.TokenService, logger *slog.Logger, ) gin.HandlerFunc
AuthenticationMiddleware validates Bearer tokens and stores authenticated clients in request context.
Extracts Bearer token from Authorization header, hashes it via tokenService.HashToken(), validates via tokenUseCase.Authenticate(), and stores the client for downstream handlers.
Authorization header format: "Bearer <token>" (case-insensitive)
Returns:
- 401 Unauthorized: Missing/malformed/invalid token
- 403 Forbidden: Inactive client
- 500 Internal Server Error: Other errors
func AuthorizationMiddleware ¶
func AuthorizationMiddleware( capability authDomain.Capability, auditLogUseCase authUseCase.AuditLogUseCase, logger *slog.Logger, ) gin.HandlerFunc
AuthorizationMiddleware enforces capability-based authorization for authenticated clients.
MUST be used after AuthenticationMiddleware. Retrieves authenticated client from context, extracts request path, and checks if Client.IsAllowed(path, capability) permits access. Creates audit logs for all authorization attempts (both successful and failed).
Path Matching:
- Exact: "/secrets/mykey" matches policy "/secrets/mykey"
- Wildcard: "*" matches all paths
- Prefix: "secret/*" matches paths starting with "secret/"
Returns:
- 401 Unauthorized: No authenticated client in context
- 403 Forbidden: Insufficient permissions
func GetCapability ¶
func GetCapability(ctx context.Context) (authDomain.Capability, bool)
GetCapability retrieves the authorized capability from the context. Returns (capability, true) if present, or ("", false) if not set. This is typically called by handlers that need the authorized capability for audit logging.
func GetClient ¶
func GetClient(ctx context.Context) (*authDomain.Client, bool)
GetClient retrieves an authenticated client from the context. Returns (client, true) if a client is present, or (nil, false) if no client was set. This is typically called by handlers or subsequent middleware that need the authenticated client.
func GetPath ¶
GetPath retrieves the authorized path from the context. Returns (path, true) if a path is present, or ("", false) if no path was set. This is typically called by handlers that need the authorized path for audit logging.
func RateLimitMiddleware ¶ added in v0.5.0
RateLimitMiddleware enforces per-client rate limiting on authenticated requests.
MUST be used after AuthenticationMiddleware (requires authenticated client in context). Uses token bucket algorithm via golang.org/x/time/rate. Each client gets independent rate limiter based on their client ID.
Configuration:
- rps: Requests per second allowed per client
- burst: Maximum burst capacity for temporary spikes
Returns:
- 429 Too Many Requests: Rate limit exceeded (includes Retry-After header)
- Continues: Request allowed within rate limit
func TokenRateLimitMiddleware ¶ added in v0.7.0
TokenRateLimitMiddleware enforces per-IP rate limiting on token issuance endpoint.
Designed for unauthenticated endpoints to prevent credential stuffing and brute force attacks. Uses token bucket algorithm via golang.org/x/time/rate. Each IP address gets an independent rate limiter.
Uses c.ClientIP() which automatically handles:
- X-Forwarded-For header (takes first IP)
- X-Real-IP header
- Direct connection remote address
Configuration:
- rps: Requests per second allowed per IP address
- burst: Maximum burst capacity for temporary spikes
Returns:
- 429 Too Many Requests: Rate limit exceeded (includes Retry-After header)
- Continues: Request allowed within rate limit
func WithCapability ¶
func WithCapability(ctx context.Context, capability authDomain.Capability) context.Context
WithCapability stores the authorized capability in the context. This is typically called by the authorization middleware after successful authorization check.
func WithClient ¶
WithClient stores an authenticated client in the context. This is typically called by the authentication middleware after successful token validation.
Types ¶
type AuditLogHandler ¶
type AuditLogHandler struct {
// contains filtered or unexported fields
}
AuditLogHandler handles HTTP requests for audit log operations.
func NewAuditLogHandler ¶
func NewAuditLogHandler( auditLogUseCase authUseCase.AuditLogUseCase, logger *slog.Logger, ) *AuditLogHandler
NewAuditLogHandler creates a new audit log handler with required dependencies.
func (*AuditLogHandler) ListHandler ¶
func (h *AuditLogHandler) ListHandler(c *gin.Context)
ListHandler retrieves audit logs with pagination support and optional time-based filtering. GET /v1/audit-logs?offset=0&limit=50&created_at_from=2026-02-01T00:00:00Z&created_at_to=2026-02-14T23:59:59Z Requires ReadCapability on path /v1/audit-logs. Returns 200 OK with paginated audit log list ordered by created_at descending (newest first). Accepts optional created_at_from and created_at_to query parameters in RFC3339 format. Timestamps are converted to UTC. Both boundaries are inclusive (>= and <=).
type ClientHandler ¶
type ClientHandler struct {
// contains filtered or unexported fields
}
ClientHandler handles HTTP requests for client management operations. It coordinates authentication, authorization, and audit logging with the ClientUseCase.
func NewClientHandler ¶
func NewClientHandler( clientUseCase authUseCase.ClientUseCase, auditLogUseCase authUseCase.AuditLogUseCase, logger *slog.Logger, ) *ClientHandler
NewClientHandler creates a new client handler with required dependencies.
func (*ClientHandler) CreateHandler ¶
func (h *ClientHandler) CreateHandler(c *gin.Context)
CreateHandler creates a new authentication client with policies. POST /v1/clients - Requires WriteCapability on path /v1/clients. Returns 201 Created with ID and plain text secret.
func (*ClientHandler) DeleteHandler ¶
func (h *ClientHandler) DeleteHandler(c *gin.Context)
DeleteHandler soft deletes a client by setting IsActive to false. DELETE /v1/clients/:id - Requires DeleteCapability on path /v1/clients/:id. Returns 204 No Content.
func (*ClientHandler) GetHandler ¶
func (h *ClientHandler) GetHandler(c *gin.Context)
GetHandler retrieves a client by ID. GET /v1/clients/:id - Requires ReadCapability on path /v1/clients/:id. Returns 200 OK with client data (no secret).
func (*ClientHandler) ListHandler ¶
func (h *ClientHandler) ListHandler(c *gin.Context)
ListHandler retrieves clients with pagination support. GET /v1/clients?offset=0&limit=50 - Requires ReadCapability on path /v1/clients. Returns 200 OK with paginated client list.
func (*ClientHandler) UpdateHandler ¶
func (h *ClientHandler) UpdateHandler(c *gin.Context)
UpdateHandler updates an existing client's configuration. PUT /v1/clients/:id - Requires WriteCapability on path /v1/clients/:id. Returns 200 OK with updated client data (no secret).
type TokenHandler ¶
type TokenHandler struct {
// contains filtered or unexported fields
}
TokenHandler handles HTTP requests for token operations. It coordinates token issuance with the TokenUseCase.
func NewTokenHandler ¶
func NewTokenHandler( tokenUseCase authUseCase.TokenUseCase, logger *slog.Logger, ) *TokenHandler
NewTokenHandler creates a new token handler with required dependencies.
func (*TokenHandler) IssueTokenHandler ¶
func (h *TokenHandler) IssueTokenHandler(c *gin.Context)
IssueTokenHandler issues a new authentication token for a client. POST /v1/token - No authentication required (this is the authentication endpoint). Returns 201 Created with token and expiration time.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package dto provides data transfer objects for HTTP request and response handling.
|
Package dto provides data transfer objects for HTTP request and response handling. |
|
Package mocks provides mock implementations for testing HTTP handlers.
|
Package mocks provides mock implementations for testing HTTP handlers. |