Documentation
¶
Overview ¶
Package middleware provides framework-neutral HTTP middleware for authkit. Every middleware function returns the standard func(http.Handler) http.Handler shape so it composes with lightmux.Mux.Use/Group/Handle, with chi/gorilla, or with any net/http stack accepting that signature.
Three primitives:
- RequireLogin — accept session OR JWT, optionally constrain by Authz
- RequireGuest — reject authenticated requests
- RequireServiceKey — accept a service token, optionally constrain by Authz
All three attach the relevant subject to the request context via authkit.WithUserContext or authkit.WithServiceKey, so handlers can read it via authkit.UserIDFromCtx / authkit.UserFromCtx / authkit.ServiceKeyFromCtx.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RequireGuest ¶ added in v0.3.0
func RequireGuest(opts GuestOptions) func(http.Handler) http.Handler
RequireGuest returns middleware that rejects requests carrying a valid session or JWT. Useful for /login or /register pages where authenticated users should be redirected away.
Default rejection is HTTP 403 JSON. Pass Options.OnAuthenticated to implement a redirect or custom response.
func RequireLogin ¶ added in v0.3.0
func RequireLogin(opts LoginOptions) func(http.Handler) http.Handler
RequireLogin returns middleware that authenticates the request via either a session cookie or a JWT (in that order) and, if Authz is set, gates the resolved Principal against the predicate.
Panics at construction time if Auth is nil or Authz references unknown slugs.
func RequireServiceKey ¶ added in v0.2.0
func RequireServiceKey(opts ServiceKeyOptions) func(http.Handler) http.Handler
RequireServiceKey returns middleware that authenticates the request via a service token and, if Authz is set, gates on the predicate.
Panics at construction time if Auth is nil or Authz references unknown ability slugs.
Types ¶
type GuestOptions ¶ added in v0.3.0
type GuestOptions struct {
// Auth is required.
Auth *authkit.Auth
SessionExtractor authkit.Extractor
JWTExtractor authkit.Extractor
// OnAuthenticated handles requests that present a valid credential
// (where a guest was expected). Default: JSON 403.
OnAuthenticated func(w http.ResponseWriter, r *http.Request)
}
GuestOptions configures RequireGuest.
type LoginOptions ¶ added in v0.3.0
type LoginOptions struct {
// Auth is required.
Auth *authkit.Auth
// SessionExtractor reads the session plaintext from the request.
// Defaults to a cookie extractor using Auth.SessionCookieName().
SessionExtractor authkit.Extractor
// JWTExtractor reads the JWT access token from the request. Defaults
// to BearerExtractor.
JWTExtractor authkit.Extractor
// Authz, if non-nil, gates the request on a predicate over the
// resolved *Principal. Validate is called once at construction; an
// invalid predicate (unknown slug) panics.
Authz authkit.LoginAuthz
// OnUnauth handles "no credential / bad credential" failures (HTTP
// 401). Default: JSON {"error":"Unauthorized"}.
OnUnauth func(w http.ResponseWriter, r *http.Request, err error)
// OnForbidden handles "credential ok but Authz failed" (HTTP 403).
// Default: JSON {"error":"Forbidden"}.
OnForbidden func(w http.ResponseWriter, r *http.Request, err error)
}
LoginOptions configures RequireLogin.
type ServiceKeyOptions ¶ added in v0.3.0
type ServiceKeyOptions struct {
Auth *authkit.Auth
// Extractor reads the service token plaintext. Defaults to
// BearerExtractor.
Extractor authkit.Extractor
// Authz, if non-nil, gates the request on a predicate over the
// resolved *ServiceKey.
Authz authkit.ServiceKeyAuthz
OnUnauth func(w http.ResponseWriter, r *http.Request, err error)
OnForbidden func(w http.ResponseWriter, r *http.Request, err error)
}
ServiceKeyOptions configures RequireServiceKey.
Source Files