Documentation
¶
Overview ¶
Package middleware holds the HTTP concerns that wrap every request: authentication, role checks and rate limiting.
Index ¶
- Constants
- func Admin(scope string) []okapi.Middleware
- func Auth(svc *service.Service, auth *service.Authenticator) okapi.Middleware
- func Guard(role okapi.Middleware, scope string) []okapi.Middleware
- func PrincipalOf(c *okapi.Context) *service.Principal
- func Read(scope string) []okapi.Middleware
- func RequireAdmin() okapi.Middleware
- func RequireRole(roles ...string) okapi.Middleware
- func RequireScope(scope string) okapi.Middleware
- func RequireWrite() okapi.Middleware
- func SecurityHeaders(policy func() string) okapi.Middleware
- func Write(scope string) []okapi.Middleware
- type RateLimiter
Constants ¶
const PrincipalKey = "certio.principal"
PrincipalKey is the context key under which the authenticated identity is stored for handlers to read.
Variables ¶
This section is empty.
Functions ¶
func Admin ¶
func Admin(scope string) []okapi.Middleware
Admin builds the guard for an administrator-only route.
func Auth ¶
func Auth(svc *service.Service, auth *service.Authenticator) okapi.Middleware
Auth authenticates a request from either a JWT or an API token. Both arrive as `Authorization: Bearer <value>`; a Certio API token is recognised by its `certio_` prefix, and anything else is treated as a JWT.
func Guard ¶
func Guard(role okapi.Middleware, scope string) []okapi.Middleware
Guard composes the role and scope checks a route needs into the one slice a RouteDefinition carries, so a route states its requirements once.
func PrincipalOf ¶
PrincipalOf returns the authenticated identity, or nil on an unauthenticated route.
func Read ¶
func Read(scope string) []okapi.Middleware
Read builds the guard for a read-only route: no role restriction (every signed-in account may look), but a token still needs the scope.
func RequireRole ¶
func RequireRole(roles ...string) okapi.Middleware
RequireRole rejects a request whose principal does not hold one of the listed roles.
func RequireScope ¶
func RequireScope(scope string) okapi.Middleware
RequireScope rejects a request whose API token was not granted the scope the route needs. It is a second gate below RequireRole, not a replacement for it: a viewer's token holding certificates:write still cannot issue anything, because the role check runs too.
A signed-in session is unaffected — scopes only ever narrow a token.
func RequireWrite ¶
func RequireWrite() okapi.Middleware
RequireWrite allows admins and operators — everyone who may change PKI state. It is the guard on every mutating certificate route.
func SecurityHeaders ¶
func SecurityHeaders(policy func() string) okapi.Middleware
SecurityHeaders sets the response headers that make sense for an app that serves both an API and an embedded SPA.
The policy arrives as a function rather than a string: it depends on hashes of the dashboard's and the docs page's inline scripts, and the latter cannot be computed until the routes exist. An empty policy omits the header, which is what a caller with nothing to protect should get.
func Write ¶
func Write(scope string) []okapi.Middleware
Write builds the guard for a mutating route.
Types ¶
type RateLimiter ¶
type RateLimiter struct {
// contains filtered or unexported fields
}
RateLimiter is a fixed-window limiter keyed by client IP. It is deliberately in-process: Certio is a single binary, and a shared limiter would mean a Redis dependency for a feature that only needs to slow down credential stuffing against one instance.
func NewRateLimiter ¶
func NewRateLimiter(limit int, per time.Duration) *RateLimiter
NewRateLimiter builds a limiter allowing limit requests per window.
func (*RateLimiter) Allow ¶
func (r *RateLimiter) Allow(key string) (bool, time.Duration)
Allow reports whether a key may proceed, and how long until it may retry.
func (*RateLimiter) Middleware ¶
func (r *RateLimiter) Middleware() okapi.Middleware
Middleware applies the limiter to a route, keyed by client IP.
func (*RateLimiter) PerPrincipal ¶
func (r *RateLimiter) PerPrincipal() okapi.Middleware
PerPrincipal applies the limiter keyed by the authenticated identity, with the client IP as the fallback. Two CI jobs behind one NAT gateway should not share a budget, and one token looping should not be masked by the address it happens to come from.