session

Documentation

Overview

Package session provides session contracts and storage backends.

Index

• Variables
• func NewID() (string, error)
• type CookieRevocationStore
• type CookieStorage
  • func NewCookieStorage(secret []byte, revocations CookieRevocationStore) (*CookieStorage, error)
  • func (storage *CookieStorage) Delete(ctx context.Context, id string) error
  • func (storage *CookieStorage) Encode(ctx context.Context, values map[string]any, ttl time.Duration) (string, error)
  • func (storage *CookieStorage) EncodeWithFamily(ctx context.Context, values map[string]any, ttl time.Duration, family string) (string, error)
  • func (storage *CookieStorage) Family(id string) string
  • func (storage *CookieStorage) Get(ctx context.Context, id string) (map[string]any, error)
  • func (storage *CookieStorage) RevokeToken(ctx context.Context, id string) error
  • func (storage *CookieStorage) Set(context.Context, string, map[string]any, time.Duration) error
• type MemoryCookieRevocationStore
  • func NewMemoryCookieRevocationStore() *MemoryCookieRevocationStore
  • func (store *MemoryCookieRevocationStore) IsRevoked(_ context.Context, tokenDigest, familyDigest string, now int64) (bool, error)
  • func (store *MemoryCookieRevocationStore) RegisterFamilyToken(_ context.Context, familyDigest string, expiresAt, now int64) error
  • func (store *MemoryCookieRevocationStore) RevokeFamily(_ context.Context, familyDigest string, expiresAt, now int64) error
  • func (store *MemoryCookieRevocationStore) RevokeToken(_ context.Context, tokenDigest string, expiresAt int64) error
• type MemoryStorage
  • func NewMemoryStorage() *MemoryStorage
  • func (storage *MemoryStorage) Delete(_ context.Context, id string) error
  • func (storage *MemoryStorage) Get(_ context.Context, id string) (map[string]any, error)
  • func (storage *MemoryStorage) Set(_ context.Context, id string, values map[string]any, ttl time.Duration) error
• type Session
• type Storage

Variables

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

Functions

func NewID

func NewID() (string, error)

NewID returns a cryptographically random identifier suitable for sessions and signed-cookie nonces.

Types

type CookieRevocationStore

type CookieRevocationStore interface {
	IsRevoked(ctx context.Context, tokenDigest, familyDigest string, now int64) (bool, error)
	RegisterFamilyToken(ctx context.Context, familyDigest string, expiresAt, now int64) error
	RevokeToken(ctx context.Context, tokenDigest string, expiresAt int64) error
	RevokeFamily(ctx context.Context, familyDigest string, expiresAt, now int64) error
}

CookieRevocationStore is the persistence boundary for signed-cookie revocation. CookieStorage passes only SHA-256 hex digests, never raw tokens or family identifiers. Implementations intended for multiple processes must use shared durable storage.

RegisterFamilyToken must atomically reject a currently revoked family with ErrNotFound and update that family's latest token expiry. RevokeFamily must revoke through the greater of expiresAt and every expiry previously observed for the family, so Logout also covers tokens issued by requests already in flight.

type CookieStorage

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

CookieStorage stores signed, JSON-encoded session values in the cookie. It deliberately does not own revocation persistence; the application chooses a process-local or durable shared CookieRevocationStore explicitly.

func NewCookieStorage

func NewCookieStorage(secret []byte, revocations CookieRevocationStore) (*CookieStorage, error)

NewCookieStorage creates signed-cookie session storage. The HMAC key must be at least 32 bytes of application-supplied secret material and a revocation store is mandatory so process-local revocation is never selected implicitly.

func (*CookieStorage) Delete

func (storage *CookieStorage) Delete(ctx context.Context, id string) error

func (*CookieStorage) Encode

func (storage *CookieStorage) Encode(ctx context.Context, values map[string]any, ttl time.Duration) (string, error)

Encode creates a signed cookie value for SessionManager.

func (*CookieStorage) EncodeWithFamily

func (storage *CookieStorage) EncodeWithFamily(ctx context.Context, values map[string]any, ttl time.Duration, family string) (string, error)

EncodeWithFamily creates a signed cookie value in family. An empty family starts a new independent session family.

func (*CookieStorage) Family

func (storage *CookieStorage) Family(id string) string

Family returns the signed cookie's session family, or an empty string when the value is not a valid signed token.

func (*CookieStorage) Get

func (storage *CookieStorage) Get(ctx context.Context, id string) (map[string]any, error)

func (*CookieStorage) RevokeToken

func (storage *CookieStorage) RevokeToken(ctx context.Context, id string) error

RevokeToken invalidates one signed cookie while leaving newer tokens in its session family usable. It is used during token rotation.

func (*CookieStorage) Set

func (storage *CookieStorage) Set(context.Context, string, map[string]any, time.Duration) error

type MemoryCookieRevocationStore

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

MemoryCookieRevocationStore is an explicit process-local implementation for tests and single-process applications. Its state is intentionally lost on process restart; authentication deployments that require logout/revocation across restart or multiple instances should provide a durable shared store.

func NewMemoryCookieRevocationStore

func NewMemoryCookieRevocationStore() *MemoryCookieRevocationStore

func (*MemoryCookieRevocationStore) IsRevoked

func (store *MemoryCookieRevocationStore) IsRevoked(_ context.Context, tokenDigest, familyDigest string, now int64) (bool, error)

func (*MemoryCookieRevocationStore) RegisterFamilyToken

func (store *MemoryCookieRevocationStore) RegisterFamilyToken(_ context.Context, familyDigest string, expiresAt, now int64) error

func (*MemoryCookieRevocationStore) RevokeFamily

func (store *MemoryCookieRevocationStore) RevokeFamily(_ context.Context, familyDigest string, expiresAt, now int64) error

func (*MemoryCookieRevocationStore) RevokeToken

func (store *MemoryCookieRevocationStore) RevokeToken(_ context.Context, tokenDigest string, expiresAt int64) error

type MemoryStorage

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

MemoryStorage is a process-local session store. Expired entries are swept opportunistically during writes, bounding stale-session growth without a background goroutine or an additional storage lifecycle contract.

func NewMemoryStorage

func NewMemoryStorage() *MemoryStorage

func (*MemoryStorage) Delete

func (storage *MemoryStorage) Delete(_ context.Context, id string) error

func (*MemoryStorage) Get

func (storage *MemoryStorage) Get(_ context.Context, id string) (map[string]any, error)

func (*MemoryStorage) Set

func (storage *MemoryStorage) Set(_ context.Context, id string, values map[string]any, ttl time.Duration) error

type Session

type Session interface {
	Get(key string) (any, error)
	Set(key string, value any) error
	Delete(key string) error
	Clear() error
	ID() string
	Regenerate() error
	Logout() error
}

Session is the application-facing session contract. Values must be JSON-safe; implementations return detached values so callers cannot mutate session state through shared maps, slices, pointers, or struct fields.

type Storage

type Storage interface {
	Get(ctx context.Context, id string) (map[string]any, error)
	Set(ctx context.Context, id string, values map[string]any, ttl time.Duration) error
	Delete(ctx context.Context, id string) error
}

Storage is the context-first persistence boundary for session implementations. Implementations must not retain ctx or caller-owned value references after an operation returns.