session

type Config struct {
	// CookieName defaults to "vukem_session"; with Secure, Path "/" and no
	// Domain the "__Host-" prefix is added automatically.
	CookieName string
	// Path defaults to "/".
	Path string
	// Domain is empty (host-only cookie) by default.
	Domain string
	// Secure sends the cookie over HTTPS only. Required in production.
	Secure bool
	// SameSite defaults to Lax.
	SameSite http.SameSite
	// IdleTimeout ends sessions after inactivity (default 2h).
	IdleTimeout time.Duration
	// Lifetime ends sessions this long after creation (default 24h).
	Lifetime time.Duration
	// Store keeps sessions server-side; nil stores them in an encrypted
	// cookie (CookieKey required).
	Store Store
	// CookieKey is the 32-byte AES-256-GCM key for cookie sessions; derive
	// it from APP_KEY with the purpose vukem.New uses:
	// app.DeriveKey("SESSION_DRIVER=cookie", 32).
	CookieKey []byte
	// PreviousCookieKeys still open cookie sessions sealed before an
	// APP_KEY rotation (derive them from APP_PREVIOUS_KEYS with
	// app.DerivePreviousKeys); such a session is re-sealed with CookieKey on
	// that request. Each must be 32 bytes.
	PreviousCookieKeys [][]byte
	// Production enables boot-time checks (Secure must be true).
	Production bool
	// Now is the clock (tests); defaults to time.Now. When set, New hands
	// it to the store so expiry and Prune follow the same clock: the
	// built-in MemoryStore and SQLStore, and any store (or wrapper
	// embedding one) with a setClock(func() time.Time) method.
	Now func() time.Time
	// Log receives security events and storage errors.
	Log *slog.Logger
	// RecordClient stores the User-Agent (capped at 256 bytes) and the
	// client network (IPv4 /24, IPv6 /48) with each new logged-in session
	// of a ListStore, for Manager.UserSessions. Off by default: both are
	// personal data, so turn it on only with a reason to show them.
	RecordClient bool
}

type Info struct {
	// Handle names the session for RevokeSession: the first 16 hex digits
	// of SHA-256(storage key). It is safe to show and cannot load the
	// session.
	Handle string
	// CreatedAt is when the session started (the login regenerates it).
	CreatedAt time.Time
	// LastSeenAt is the last request, to the minute (writes that only
	// refresh the idle timeout happen at most once a minute).
	LastSeenAt time.Time
	// ExpiresAt is when the session ends unless it is used again.
	ExpiresAt time.Time
	// UserAgent and IP are recorded at login only with Config.RecordClient;
	// IP keeps the network part only (IPv4 /24, IPv6 /48). UserAgent comes
	// from the client: control and format runes are removed, but escape it
	// when rendering (html/template does).
	UserAgent, IP string
	// Current is true for the session of the currentID given to
	// UserSessions.
	Current bool
}

type ListStore interface {
	UserStore
	// ListUser returns the live sessions of userID.
	ListUser(ctx context.Context, userID string) ([]StoredSession, error)
	// DeleteUserKey deletes the session stored under key when it belongs
	// to userID and reports whether one was deleted.
	DeleteUserKey(ctx context.Context, userID, key string) (bool, error)
}

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

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

type SQLOption func(*SQLStore)

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

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

type Store interface {
	// Load returns the data saved for id; found is false when the session
	// does not exist or expired.
	Load(ctx context.Context, id string) (data []byte, found bool, err error)
	// Save stores data for id until expiry.
	Save(ctx context.Context, id string, data []byte, expiry time.Time) error
	// Delete removes id.
	Delete(ctx context.Context, id string) error
}

type StoredSession struct {
	// Key is hex(SHA-256(session id)), never the id itself.
	Key string
	// Data is the encoded session, as passed to Create and Update.
	Data []byte
	// Expiry is when the session ends unless it is used again.
	Expiry time.Time
}

type UserStore interface {
	Store
	// Create stores a new session owned by userID ("" for a guest).
	Create(ctx context.Context, id, userID string, data []byte, expiry time.Time) error
	// Update rewrites an existing session and returns ErrSessionNotFound
	// when it is gone (revoked, logged out, pruned): a request that was in
	// flight during a revocation must not write the session back.
	Update(ctx context.Context, id, userID string, data []byte, expiry time.Time) error
	// RevokeOthers deletes every session of userID except keepID ("" keeps
	// none).
	RevokeOthers(ctx context.Context, userID, keepID string) error
}