session

Documentation

Overview

Package session implements opaque, purpose-bound, hashed browser sessions. It is storage-agnostic: applications implement Store using their own database.

Index

• Variables
• func TokenHash(purpose, token string) string
• type Authenticator
  • func (a Authenticator[User]) Authenticate(request *http.Request) (User, error)
• type CookieConfig
  • func (c CookieConfig) Cookie(token string, expire bool) *http.Cookie
• type Manager
  • func (m Manager[User]) End(ctx context.Context, token string) error
  • func (m Manager[User]) Resolve(ctx context.Context, token string) (User, error)
  • func (m Manager[User]) Start(ctx context.Context, user User) (string, error)
  • func (m Manager[User]) Validate() error
• type Store

Variables

var ErrNotFound = errors.New("session not found")

ErrNotFound indicates an absent or invalidated session.

Functions

func TokenHash

func TokenHash(purpose, token string) string

TokenHash derives the purpose-separated identifier stored in the database.

Types

type Authenticator

type Authenticator[User any] struct {
	// Manager provides secure session lookup.
	Manager Manager[User]
	// CookieName is the cookie carrying the opaque session token.
	CookieName string
}

Authenticator resolves users from a named session cookie.

func (Authenticator[User]) Authenticate

func (a Authenticator[User]) Authenticate(request *http.Request) (User, error)

Authenticate implements the shared auth.Authenticator contract.

type CookieConfig

type CookieConfig struct {
	// Name is the session cookie name, unique within the deployment.
	Name string
	// Path is the cookie path, typically the mounted application prefix or root.
	Path string
	// Lifetime is the browser cookie lifetime.
	Lifetime time.Duration
	// Secure must be true for HTTPS deployments.
	Secure bool
	// SameSite is the cookie cross-site policy.
	SameSite http.SameSite
}

CookieConfig defines an HTTP-only cookie scoped to the application's deployment path.

func (CookieConfig) Cookie

func (c CookieConfig) Cookie(token string, expire bool) *http.Cookie

Cookie returns an HTTP-only cookie using configured security settings.

type Manager

type Manager[User any] struct {
	// Store is the application-supplied durable session store.
	Store Store[User]
	// Lifetime is the maximum age of newly issued sessions.
	Lifetime time.Duration
	// Purpose isolates hashes from other types of token.
	Purpose string
}

Manager issues, resolves, and revokes sessions for one application.

func (Manager[User]) End

func (m Manager[User]) End(ctx context.Context, token string) error

End revokes one session without storing or logging the raw token.

func (Manager[User]) Resolve

func (m Manager[User]) Resolve(ctx context.Context, token string) (User, error)

Resolve authenticates the session token using application-owned persistence.

func (Manager[User]) Start

func (m Manager[User]) Start(ctx context.Context, user User) (string, error)

Start creates a cryptographically random token and persists only its hash.

func (Manager[User]) Validate

func (m Manager[User]) Validate() error

Validate ensures that session configuration cannot issue unsafe sessions.

type Store

type Store[User any] interface {
	// Create atomically persists a session hash and its expiry.
	Create(context.Context, string, User, time.Time) error
	// Lookup resolves a live session hash to an application user.
	Lookup(context.Context, string) (User, error)
	// Revoke permanently invalidates a session hash.
	Revoke(context.Context, string) error
}

Store persists only hashes of bearer session tokens, never raw tokens. Lookup must exclude expired and revoked sessions and disabled accounts.