sessions

Documentation

Index

• Variables
• type Config
• type CookieStore
  • func New[T any](cfg Config) *CookieStore[T]
  • func (tss *CookieStore[T]) Delete(ctx context.Context, writer http.ResponseWriter, session *Session[T]) error
  • func (tss *CookieStore[T]) DeleteUnparsed(writer http.ResponseWriter, req *http.Request) error
  • func (tss *CookieStore[T]) Get(r *http.Request) (*Session[T], error)
  • func (tss *CookieStore[T]) New() (*Session[T], error)
  • func (tss *CookieStore[T]) Save(writer http.ResponseWriter, req *http.Request, session *Session[T]) error
• type EncryptedStore
  • func (es *EncryptedStore) Delete(ctx context.Context, key string) error
  • func (es *EncryptedStore) Get(ctx context.Context, key string) ([]byte, error)
  • func (es *EncryptedStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
• type Session
• type Store
  • func NewEncryptedStore(store Store) Store

Variables

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

Types

type Config

type Config struct {
	Store      Store
	CookieName string
	SessionTTL time.Duration
	TrustProxy bool
}

type CookieStore

type CookieStore[T any] struct {
	// contains filtered or unexported fields
}

func New

func New[T any](cfg Config) *CookieStore[T]

func (*CookieStore[T]) Delete

func (tss *CookieStore[T]) Delete(ctx context.Context, writer http.ResponseWriter, session *Session[T]) error

func (*CookieStore[T]) DeleteUnparsed

func (tss *CookieStore[T]) DeleteUnparsed(writer http.ResponseWriter, req *http.Request) error

func (*CookieStore[T]) Get

func (tss *CookieStore[T]) Get(r *http.Request) (*Session[T], error)

func (*CookieStore[T]) New

func (tss *CookieStore[T]) New() (*Session[T], error)

New session with random ID and pre-created state. Doesn't save it to storage.

func (*CookieStore[T]) Save

func (tss *CookieStore[T]) Save(writer http.ResponseWriter, req *http.Request, session *Session[T]) error

type EncryptedStore

type EncryptedStore struct {
	// contains filtered or unexported fields
}

EncryptedStore provides encryption for session data using the session key itself as the encryption key.

⚠️ CRITICAL SECURITY REQUIREMENTS:

• Session keys MUST be 32+ bytes cryptographically secure random data
• Use Session.New() to generate proper keys - never use user-provided or predictable keys
• Keys shorter than 32 bytes will cause encryption failures

SECURITY MODEL:

• The session key IS the encryption key (derived via SHA3)
• If the session key is unknown, data is undecryptable
• Storage compromise alone cannot decrypt session data
• Even with full database access, attackers cannot impersonate users without session keys

KEY DERIVATION:

• Storage Key: SHA3(session_key) → hex encoded (used in underlying storage)
• Encryption Key: SHA3(saltPrefix + session_key) → 32 bytes (used for AES-256-GCM)

func (*EncryptedStore) Delete

func (es *EncryptedStore) Delete(ctx context.Context, key string) error

Delete removes a value from the underlying storage.

func (*EncryptedStore) Get

func (es *EncryptedStore) Get(ctx context.Context, key string) ([]byte, error)

Get retrieves and decrypts a value from the underlying storage.

func (*EncryptedStore) Set

func (es *EncryptedStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error

Set stores an encrypted value in the underlying storage.

type Session

type Session[T any] struct {
	ID    string
	State *T
}

type Store

type Store interface {
	// Set stores value for a given key. Replaces existent if needed.
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
	// Get returns stored value or nil if key not found.
	// Important: key not found case treated as non-error - nil, nil should be returned in this case.
	Get(ctx context.Context, key string) ([]byte, error)
	// Delete key from store. Should not return an error if the key is not found.
	Delete(ctx context.Context, key string) error
}

Store is used to store session data. All methods should be thread-safe. Value is guaranteed to not be used after functions call (ie: no need for manual cloning).

func NewEncryptedStore

func NewEncryptedStore(store Store) Store

NewEncryptedStore creates a new encrypted session store wrapper. It requires cryptographically secure session keys (32+ bytes) - use Session.New() to generate them.