session

Documentation

Overview

Package session defines the server-side session model and the Store interface that persists it.

Index

• Variables
• type Filter
• type Lister
• type Session
  • func (s *Session) Active() bool
  • func (s *Session) Pending() bool
  • func (s *Session) Valid() bool
• type Status
• type Store
  • func NewCacheStore(c *cache.Cache) (Store, error)
  • func NewMemoryStore() Store

Variables

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

ErrNotFound is returned when no session matches the given ID.

Types

type Filter

type Filter struct {
	// ActiveOnly returns only active sessions.
	ActiveOnly bool
}

Filter narrows which of a user's sessions to return.

type Lister

type Lister interface {
	// List returns userID's sessions matching filter ordered by LastSeen descending.
	List(ctx context.Context, userID string, filter *Filter, page *paginator.Paginator) (sessions []*Session, pages *paginator.Paginator, err error)
}

Lister is an optional Store capability for listing of a user's sessions ordered by LastSeen descending, narrowed by an optional filter and paging.

type Session

type Session struct {
	ID        string
	UserID    string
	ClientID  string
	Scope     string
	Status    Status
	Step      string // name of the unresolved login step when Status == pending_step ("" otherwise)
	MFAMethod string // name of the MFA method used to verify (empty until MFA passed)
	// AuthProvider is the external provider name that authenticated this session ("" = local
	// login); used as id_token_hint source for RP-initiated federated logout.
	AuthProvider string
	ACR          string   // satisfied authentication context class (trust level)
	AMR          []string // authentication methods references actually used, e.g. ["pwd","otp"]
	// Context carries application-defined selections bound to the session - the active tenant,
	// the selected role(s), an accepted agreement version, etc.
	Context   map[string]any
	CreatedAt time.Time
	LastSeen  time.Time
	ExpiresAt time.Time
	RevokedAt *time.Time
}

Session is the server-side record for an authenticated (or pending) login.

func (*Session) Active

func (s *Session) Active() bool

Active returns true when the session is valid and in the active status.

func (*Session) Pending

func (s *Session) Pending() bool

Pending returns true when the session is valid but has unresolved steps.

func (*Session) Valid

func (s *Session) Valid() bool

Valid returns true when the session is still alive, not revoked and not expired.

type Status

type Status string

Status is the lifecycle/step state of a session.

const (
	// StatusActive is fully authenticated; access tokens may be issued.
	StatusActive Status = "active"
	// StatusPendingPasswordChange requires the user to change their password before
	// the session is promoted to active.
	StatusPendingPasswordChange Status = "pending_password_change"
	// StatusPendingMFASetup requires the user to enrol in an MFA method.
	StatusPendingMFASetup Status = "pending_mfa_setup"
	// StatusPendingMFA requires MFA verification before the session is active.
	StatusPendingMFA Status = "pending_mfa"
	// StatusPendingStep is an application-defined gate that has not yet been satisfied
	// (e.g. tenant/role selection, consent, accepting the portal usage agreement).
	StatusPendingStep Status = "pending_step"
)

type Store

type Store interface {
	// Create a new session.
	Create(ctx context.Context, s *Session) error
	// Get session by ID.
	Get(ctx context.Context, id string) (*Session, error)
	// Touch updates session as active (usually by updating LastSeen time).
	Touch(ctx context.Context, id string) error
	// Revoke session and invalidate it.
	Revoke(ctx context.Context, id string) error
}

Store persists server-side sessions by ID. These are the operations any backend can support, including a plain key-value store (e.g. a cache).

func NewCacheStore

func NewCacheStore(c *cache.Cache) (Store, error)

NewCacheStore creates a cache-backed session Store over the app's cache.

func NewMemoryStore

func NewMemoryStore() Store

NewMemoryStore creates an empty in-memory session Store.

Warning: Use it only for development and/or testing.