authhttp

auth/http

auth/http adapts auth.Service to chi routes, bearer middleware, cookies, and JSON responses. Import path: github.com/Ithildur/EiluneKit/auth/http; package name: authhttp.

This package is for the default session auth flow used by admin dashboards, internal control planes, and shared-secret applications. Login uses JSON credentials and refresh cookies.

Quick Start

manager, err := authjwt.New(signingKey, authstore.NewMemoryStore())
if err != nil {
	return err
}

authHandler, err := authhttp.NewHandler(manager, authhttp.Options{
	LoginAuthenticator: authhttp.LoginAuthenticatorFunc(func(ctx context.Context, username, password string) (string, bool, error) {
		user, err := repo.FindByUsername(ctx, username)
		if err != nil {
			return "", false, err
		}
		if user == nil {
			return "", false, nil
		}

		computedHash := hashPassword(password, user.Salt)
		if !authhttp.VerifyCredential(user.PasswordHash, computedHash) {
			return "", false, nil
		}
		return user.ID, true, nil
	}),
})
if err != nil {
	return err
}

if err := authHandler.Register(r); err != nil {
	return err
}

POST /auth/login accepts username, password, and a required persistence field with persistent or session. LoginAuthenticator verifies the credentials; the handler returns an access token and sets refresh/CSRF cookies with matching persistence.

Static Credential

For a fixed shared secret:

staticAuth, err := authhttp.NewStaticPassword("dashboard-admin", adminPassword)
if err != nil {
	return err
}

authHandler, err := authhttp.NewHandler(manager, authhttp.Options{
	LoginAuthenticator: staticAuth,
})
if err != nil {
	return err
}

if err := authhttp.ValidateStaticPassword(adminPassword); err != nil {
	return err
}

This is the intended path for a single-admin dashboard or internal control plane. The request username may be ignored; the configured user ID becomes the token subject when the password matches.

Bearer Middleware

bearer, err := authhttp.RequireBearer(manager)
if err != nil {
	return err
}
r.Use(bearer)

RequireBearer accepts any AccessTokenValidator. It parses the HTTP Authorization: Bearer header in the HTTP layer, while jwt.Manager only validates the raw access token.

Use OptionalBearer when a public route may attach user claims but must still reject malformed or invalid tokens.

optionalBearer, err := authhttp.OptionalBearer(manager)
if err != nil {
	return err
}
route.Get("/feed", "List feed", feed, routes.Auth(routes.AuthOptional), routes.Use(optionalBearer))

API Key Middleware

nodeKey, err := authhttp.RequireAPIKey(authhttp.APIKeyValidatorFunc(func(ctx context.Context, key string) (bool, error) {
	return subtle.ConstantTimeCompare([]byte(key), []byte(nodeSecret)) == 1, nil
}), "X-Node-Secret")
if err != nil {
	return err
}
route.Get("/node/metrics", "Node metrics", metrics, routes.Auth(routes.AuthRequired), routes.Use(nodeKey))

An empty header name defaults to X-API-Key.

Routes

Default HTTP paths:

Handler.Routes() returns route declarations with authentication middleware for mounting and OpenAPI generation. GET /auth/sessions requires a manager that implements auth.SessionLister; auth/jwt.Manager supports it when the store supports session listing. DELETE /auth/sessions revokes the current user's sessions and clears stored session records when the manager supports cleanup.

routeList := authHandler.Routes()
err := routes.Mount(r, "", routeList)

spec, err := openapi.Generate(routeList, openapi.Options{
	Title:   "Application Auth API",
	Version: "1.0.0",
})

Options

• LoginAuthenticator: required credential verification entrypoint
• BasePath: *string route prefix; nil defaults to "/auth", new("") selects the root, and new("/api/auth") selects /api/auth. Non-empty prefixes require a single leading slash; trailing slashes and surrounding whitespace are rejected.
• RefreshCookiePath: browser-visible absolute refresh-cookie path; defaults to / followed by the resolved BasePath
• CSRFCookiePath: CSRF cookie path; default /
• RefreshCookieName, CSRFCookieName, CSRFHeaderName: cookie and header names
• CookieSameSite: optional auth cookie SameSite override; zero keeps automatic TLS/proxy-derived behavior
• TrustedProxies: forwarded-header trust boundary for rate limiting and secure-cookie detection
• MaxBodyBytes: request body size limit for auth endpoints
• RateLimit: login rate-limit settings
• LoginLockout: optional failed-login lockout. On credential failure it records the lockout key, returns 429 login_locked when the key reaches its threshold, and clears the key after a successful login.
• LoginLockoutKeyFunc: optional key function for LoginLockout; the default key uses the exact client IP. When LoginLockout is set, the key must be non-empty. Include username only when LoginAuthenticator treats username as meaningful.
• Events: auth lifecycle hooks. Events.Login runs after credentials are accepted and tokens are issued, but before cookies and response body are written; returning an error attempts to revoke the new refresh session and fails the login request. Hooks may be called concurrently.
• Logger: optional *slog.Logger for auth lifecycle hook failures and revoke-compensation failures.

Forwarded headers are trusted only when TrustedProxies is set. The default rate-limit key uses RemoteAddr.

Use auth.NewMemoryLockout for single-process deployments:

authHandler, err := authhttp.NewHandler(manager, authhttp.Options{
	LoginAuthenticator: staticAuth,
	LoginLockout: auth.NewMemoryLockout(auth.MemoryLockoutOptions{
		MaxFailures: 5,
		Window:      15 * time.Minute,
		Lockout:     15 * time.Minute,
	}),
})

For multi-instance deployments, pass a Redis or SQL-backed auth.Lockout so failed-login state is shared across processes.

By default, cookie Secure and SameSite are derived from the request: TLS always enables secure cookies, and X-Forwarded-Proto: https only counts from trusted proxies. Set CookieSameSite when deployment policy needs an explicit mode, for example http.SameSiteLaxMode for same-site apps or http.SameSiteNoneMode for cross-site SPAs.

Contracts

• NewHandler requires both a TokenManager and Options.LoginAuthenticator.
• NewHandler takes one Options struct; fields other than LoginAuthenticator fall back to defaults when left zero-valued.
• NewStaticPassword requires a non-empty user ID and password.
• VerifyCredential performs exact byte comparison and is suitable for pre-hashed or application-derived credentials.
• Use auth/rbac and auth/rbac/http when the application needs multiple users, roles, or scopes.