Documentation
¶
Overview ¶
Package authkit serves gouncer sessions over HTTP.
Index ¶
- Constants
- Variables
- func CreateAdmin(ctx context.Context, store gouncer.Store, email string, name string, ...) error
- func Decode[T any](w http.ResponseWriter, r *http.Request) (T, error)
- func EnsureAdmin(ctx context.Context, store gouncer.Store, email, name, password string) (bool, error)
- func Respond(w http.ResponseWriter, status int, v any)
- func RespondError(w http.ResponseWriter, status int, message string)
- func StatusForAuthError(err error) (int, string, bool)
- func WithIdentity(ctx context.Context, id Identity) context.Context
- type Account
- type AdminHandlers
- func (a *AdminHandlers) Create(w http.ResponseWriter, r *http.Request)
- func (a *AdminHandlers) CreateAccount(ctx context.Context, email, name, password string) (Account, error)
- func (a *AdminHandlers) List(w http.ResponseWriter, r *http.Request)
- func (a *AdminHandlers) ListAccounts(ctx context.Context) ([]Account, error)
- func (a *AdminHandlers) SetAccountDisabled(ctx context.Context, actorID, id uuid.UUID, disabled bool) error
- func (a *AdminHandlers) SetDisabled(w http.ResponseWriter, r *http.Request)
- type AdminStore
- type Config
- type Handlers
- func (h *Handlers) Authenticate(ctx context.Context, email, password string) (Identity, error)
- func (h *Handlers) CookieName() string
- func (h *Handlers) EndSession(ctx context.Context, token string) (*http.Cookie, error)
- func (h *Handlers) Login(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) Logout(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) RequireSession(next http.Handler) http.Handler
- func (h *Handlers) Session(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) SessionIdentity(ctx context.Context, token string) (Identity, error)
- func (h *Handlers) StartSession(ctx context.Context, userID uuid.UUID) (*http.Cookie, error)
- type Identity
- type Reaper
- type ReaperConfig
- type SessionReaper
Constants ¶
const MaxRequestBodyBytes = 1 << 20
MaxRequestBodyBytes caps how much of a request body Decode will read, so an unauthenticated caller cannot exhaust memory.
Variables ¶
var ErrInvalidCredentials = errors.New("authkit: invalid credentials")
ErrInvalidCredentials reports a login that names no enabled account.
var ErrSelfDisable = errors.New("authkit: cannot disable your own account")
ErrSelfDisable reports an account disabling itself.
Functions ¶
func CreateAdmin ¶
func CreateAdmin( ctx context.Context, store gouncer.Store, email string, name string, stdin io.Reader, stdout io.Writer, ) error
CreateAdmin provisions a user account for command-line bootstrapping, reading the password as one line from stdin.
func Decode ¶
Decode reads and JSON-decodes a single request body into a value of type T, bounding the body size and rejecting trailing content.
func EnsureAdmin ¶ added in v0.2.0
func EnsureAdmin(ctx context.Context, store gouncer.Store, email, name, password string) (bool, error)
EnsureAdmin creates a user account unless the email is already taken, reporting whether it created the account.
func Respond ¶
func Respond(w http.ResponseWriter, status int, v any)
Respond writes v as a JSON response with the given status code, falling back to a 500 error payload if marshaling fails.
func RespondError ¶
func RespondError(w http.ResponseWriter, status int, message string)
RespondError writes a JSON error response with the given status code and message.
func StatusForAuthError ¶
StatusForAuthError returns the HTTP status code and client-facing message for a gouncer error, reporting false for errors it does not recognize.
Types ¶
type Account ¶ added in v0.4.0
type Account struct {
ID uuid.UUID `json:"id"`
Email string `json:"email"`
Name string `json:"name"`
Disabled bool `json:"disabled"`
CreatedAt time.Time `json:"created_at"`
}
Account is one user account as administration reports it.
type AdminHandlers ¶
type AdminHandlers struct {
// contains filtered or unexported fields
}
AdminHandlers serves user administration over HTTP. Mount its handlers behind RequireSession.
func NewAdmin ¶
func NewAdmin(store AdminStore) *AdminHandlers
NewAdmin returns AdminHandlers administering the accounts in store.
func (*AdminHandlers) Create ¶
func (a *AdminHandlers) Create(w http.ResponseWriter, r *http.Request)
Create decodes credentials, creates a user account, persists it, and responds with the created account.
func (*AdminHandlers) CreateAccount ¶ added in v0.4.0
func (a *AdminHandlers) CreateAccount(ctx context.Context, email, name, password string) (Account, error)
CreateAccount validates and persists a new user account.
func (*AdminHandlers) List ¶
func (a *AdminHandlers) List(w http.ResponseWriter, r *http.Request)
List responds with every user account.
func (*AdminHandlers) ListAccounts ¶ added in v0.4.0
func (a *AdminHandlers) ListAccounts(ctx context.Context) ([]Account, error)
ListAccounts returns every user account ordered for display.
func (*AdminHandlers) SetAccountDisabled ¶ added in v0.4.0
func (a *AdminHandlers) SetAccountDisabled(ctx context.Context, actorID, id uuid.UUID, disabled bool) error
SetAccountDisabled updates whether the account may log in, refusing an actor disabling itself.
func (*AdminHandlers) SetDisabled ¶
func (a *AdminHandlers) SetDisabled(w http.ResponseWriter, r *http.Request)
SetDisabled parses the user id from the request's "id" path value and updates whether that account may log in, refusing to disable the requester.
type AdminStore ¶
type AdminStore interface {
gouncer.Store
// ListUsers returns every user account ordered for display.
ListUsers(ctx context.Context) ([]gouncer.User, error)
// SetUserDisabled updates whether the account may log in.
SetUserDisabled(ctx context.Context, id uuid.UUID, disabled bool) error
}
AdminStore persists users for both login and administration.
type Config ¶
type Config struct {
// Store persists users and their login sessions.
Store gouncer.Store
// CookieName names the session cookie. Empty applies "__Host-session".
// Names should keep the __Host- prefix to retain its browser guarantees.
CookieName string
// SessionTTL bounds issued sessions and their cookie alike. Zero
// applies gouncer.DefaultSessionDuration.
SessionTTL time.Duration
}
Config parameterizes the session transport.
type Handlers ¶
type Handlers struct {
// contains filtered or unexported fields
}
Handlers serves login sessions over HTTP.
func (*Handlers) Authenticate ¶ added in v0.4.0
Authenticate verifies credentials, answering the account identity or ErrInvalidCredentials.
func (*Handlers) CookieName ¶ added in v0.4.0
CookieName reports the configured session cookie name.
func (*Handlers) EndSession ¶ added in v0.4.0
EndSession deletes the session behind token, returning the clearing cookie.
func (*Handlers) Login ¶
func (h *Handlers) Login(w http.ResponseWriter, r *http.Request)
Login verifies credentials and issues a session cookie.
func (*Handlers) Logout ¶
func (h *Handlers) Logout(w http.ResponseWriter, r *http.Request)
Logout deletes the current session and clears its cookie.
func (*Handlers) RequireSession ¶
RequireSession admits only requests carrying a usable session cookie, passing the authenticated identity down through the request context.
func (*Handlers) Session ¶
func (h *Handlers) Session(w http.ResponseWriter, r *http.Request)
Session reports the logged-in user, whose identity the RequireSession middleware already resolved.
func (*Handlers) SessionIdentity ¶ added in v0.4.0
SessionIdentity resolves the identity behind a session token.
type Identity ¶
type Identity struct {
ID uuid.UUID `json:"id"`
Email string `json:"email"`
Name string `json:"name"`
}
Identity is the authenticated user exposed to handlers, deliberately excluding credentials such as the password hash.
func IdentityFromContext ¶
IdentityFromContext returns the identity stored by the RequireSession middleware, or the zero identity outside of it.
type Reaper ¶
type Reaper struct {
// contains filtered or unexported fields
}
Reaper periodically deletes expired sessions until stopped.
func NewReaper ¶
func NewReaper(store SessionReaper, cfg ReaperConfig) *Reaper
NewReaper returns a Reaper sweeping store per cfg.
type ReaperConfig ¶
type ReaperConfig struct {
// Interval is how often expired sessions are swept. Zero applies one hour.
Interval time.Duration
// Timeout bounds each sweep. Zero applies thirty seconds.
Timeout time.Duration
// Logger receives sweep outcomes. Nil applies slog.Default.
Logger *slog.Logger
}
ReaperConfig parameterizes a Reaper.
Source Files
Directories