Documentation
¶
Overview ¶
Package authsession implements stateless HS256-signed session tokens that kombify backend services issue to their own browser frontends after a successful login (OIDC code-flow via [authflow], or break-glass via [authlocal]). The upstream provider's ID token is verified by [oidcclient.Verifier]; this package mints a short-lived backend session token whose only purpose is to carry user + tenant + provider claims through subsequent API calls.
Why a separate token instead of forwarding the provider ID token?
- Backends add tenant_id from their own provisioning step.
- The signing secret can be rotated independently of any IdP.
- The frontend-API contract stays stable across providers.
Donor: kombify-Techstack/pkg/v2/auth/session (lifted 2026-05-03 as part of the auth standardization; kept verbatim apart from the package rename).
Index ¶
- Constants
- Variables
- func ClearSessionCookie(w http.ResponseWriter, name string, secure bool)
- func SetSessionCookie(w http.ResponseWriter, name, token string, secure bool)
- func TenantFrom(ctx context.Context) (string, error)
- func WithClaims(ctx context.Context, c *Claims) context.Context
- type Claims
- type Config
- type Manager
- type Middleware
- type Option
Constants ¶
const ( DefaultIssuer = "kombify" DefaultLifetime = 30 * time.Minute )
Defaults.
const DefaultSessionCookieName = "kombify_session"
DefaultSessionCookieName is the recommended cookie name for backends that don't have a tool-specific override. Consumers SHOULD pick their own name (e.g. "techstack_v2_session", "kombisim_session") to avoid cross-tool collisions on shared parent domains.
Variables ¶
var ( ErrConfigInvalid = errors.New("authsession: invalid configuration") ErrInvalidToken = errors.New("authsession: invalid token") )
Errors returned by Manager.
var (
ErrMissingClaims = errors.New("authsession: no claims in context")
)
Errors returned by Middleware / context helpers.
Functions ¶
func ClearSessionCookie ¶
func ClearSessionCookie(w http.ResponseWriter, name string, secure bool)
ClearSessionCookie writes an expired session cookie to log the user out.
func SetSessionCookie ¶
func SetSessionCookie(w http.ResponseWriter, name, token string, secure bool)
SetSessionCookie writes a session cookie with the conventional kombify attributes (HttpOnly, SameSite=Lax, Path=/). The secure argument must be false only for explicit loopback/local-HTTP development.
func TenantFrom ¶
TenantFrom is a convenience wrapper returning just the tenant id.
Types ¶
type Claims ¶
type Claims struct {
Subject string `json:"sub"`
TenantID string `json:"tid"`
OrgID string `json:"org,omitempty"`
Email string `json:"email,omitempty"`
Provider string `json:"prv,omitempty"`
Role string `json:"role,omitempty"`
ReauthPurpose string `json:"reauth_purpose,omitempty"`
ReauthResource string `json:"reauth_resource,omitempty"`
AuthenticatedAt int64 `json:"auth_time,omitempty"`
IssuedAt int64 `json:"iat,omitempty"`
Expires int64 `json:"exp,omitempty"`
}
Claims is the payload of a session token.
type Config ¶
type Config struct {
// Issuer is the `iss` claim. Defaults to [DefaultIssuer].
Issuer string
// Audience is the `aud` claim. Required: identifies the consuming
// frontend audience (e.g. "techstack:frontend", "kombisim:frontend").
Audience string
// Secret is the HS256 signing secret. Must be at least 32 bytes.
Secret []byte
// Lifetime is how long issued tokens stay valid. Defaults to
// [DefaultLifetime] (30 minutes).
Lifetime time.Duration
// ClockSkew is reserved for future use; currently the underlying JWT
// library handles default skew.
ClockSkew time.Duration
}
Config configures the Manager.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager mints and verifies session tokens.
func NewManager ¶
NewManager validates Config and returns a Manager.
type Middleware ¶
type Middleware struct {
// contains filtered or unexported fields
}
Middleware is the bearer-token authentication middleware.
func NewMiddleware ¶
func NewMiddleware(mgr *Manager, opts ...Option) *Middleware
NewMiddleware returns a Middleware backed by the given session manager.
func (*Middleware) CookieName ¶
func (m *Middleware) CookieName() string
CookieName returns the cookie name this middleware reads.
func (*Middleware) Wrap ¶
func (m *Middleware) Wrap(next http.Handler) http.Handler
Wrap returns an http.Handler that authenticates requests before delegating to next. Unauthenticated requests are rejected with 401.
type Option ¶
type Option func(*Middleware)
Option configures a Middleware.
func WithCookieName ¶
WithCookieName overrides the default browser session cookie name.
Source Files