sessions

type Backend[T any] interface {
	// Load reads the record stored under id, reporting ErrNotFound when
	// there is none. It does not evaluate expiry — the Store does, from the
	// record's own anchors, so both backends answer the same question the
	// same way.
	Load(ctx context.Context, id string) (*Record[T], error)
	// Create stores a record under an identifier that must not already
	// exist, reporting ErrIDConflict if it does.
	Create(ctx context.Context, id string, record *Record[T], ttl time.Duration) error
	// Update overwrites the record stored under an existing identifier,
	// reporting ErrNotFound when there is none.
	//
	// The existence requirement is not bookkeeping. Without it a request
	// that read a session just before it was signed out would write it back
	// afterwards, and the sign-out would not have happened.
	Update(ctx context.Context, id string, record *Record[T], ttl time.Duration) error
	// Rename moves a record from oldID to newID, reporting ErrNotFound when
	// oldID holds nothing. On a nil return, oldID no longer resolves.
	Rename(ctx context.Context, oldID, newID string, record *Record[T], ttl time.Duration) error
	// Delete removes the record stored under id. An identifier that was
	// already absent is not an error.
	Delete(ctx context.Context, id string) error
	// ListHeld returns every record the holder holds, newest first, each
	// with the identifier it is stored under. It applies no expiry — the
	// Store filters, from the same anchors it refuses a single record by.
	//
	// A backend that keeps no index on the holder reports
	// ErrNoPrincipalIndex, and sessions/cache is one: a key-value store
	// answers "what is under this key" and cannot answer "which keys belong
	// to this person" without a second structure to maintain, which is a
	// second source of truth about which sessions are live.
	//
	// That is why these three are on the interface rather than living only
	// on the backend that has them. Sweep is not here because a caller who
	// chose a cache never needed one; this is here because a caller who
	// chose a cache and does need it has to be told so, in the one place
	// they would otherwise assume it worked.
	ListHeld(ctx context.Context, holder Holder) ([]*Identified[T], error)
	// DeleteHeld removes the record stored under id if — and only if — the
	// holder holds it, reporting how many rows went: one, or none.
	//
	// The holder is part of the statement rather than a check the caller
	// makes first. A revocation authorized in one round trip and executed
	// in another is one that can be got out of step; here the server
	// decides "this session, and it is theirs" at the instant it goes.
	DeleteHeld(ctx context.Context, holder Holder, id string) (int, error)
	// DeleteAllHeld removes every record the holder holds, sparing the one
	// stored under keepID when that is not empty, and reports how many
	// went.
	DeleteAllHeld(ctx context.Context, holder Holder, keepID string) (int, error)
	// Close releases the backend's resources and is safe to call more than
	// once.
	Close() error
}

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

type Expiry uint8

type Holder struct {
	// Principal is who holds the session within that scope.
	Principal string
	// Scope is the tenant whose data the session is. It must name
	// something — see tenancy.Scope, whose zero value names nobody and
	// which no query here accepts.
	Scope tenancy.Scope
}

type Identified[T any] struct {
	// Record is the stored record.
	Record *Record[T]
	// ID is the identifier it is stored under.
	ID string
}

type Metadata struct {
	// DeviceName is what the client called itself, in whatever vocabulary
	// the consumer chose.
	DeviceName string
	// IPAddress is the address the session was established from. It is
	// rendered, never trusted: deriving it from a forwarded-for header is
	// the caller's decision, and so is whether to believe it.
	IPAddress string
	// UserAgent is the client's self-description at establishment.
	UserAgent string
	// LoginMethod is how the principal proved themselves — a password, a
	// passkey, an OAuth provider's name. The vocabulary is the consumer's.
	LoginMethod string
}

type Option func(*storeOptions)

type Policy struct {
	// Absolute bounds a session's total lifetime from CreatedAt. Non-positive
	// disables it.
	Absolute time.Duration
	// Idle bounds how long a session may go unread. Non-positive disables it.
	Idle time.Duration
	// Touch is how much of the idle window must elapse before a read refreshes
	// the idle deadline.
	//
	// It exists because an idle timeout is otherwise a write on every read. At
	// a hundred requests a second against one session that is a hundred writes
	// a second to say the same thing; with a touch interval it is one write per
	// interval. What it costs is precision: a session's idle deadline can be up
	// to one interval stale, so a session expires up to Touch early rather than
	// late. Early is the safe direction for a security control, which is why
	// the trade is available at all.
	//
	// Zero refreshes on every read. It must be shorter than Idle, and is
	// irrelevant when Idle is disabled — there is no idle deadline to refresh,
	// so nothing is ever touched.
	Touch time.Duration

	// Grace is how long an expired record is kept before the backing store is
	// allowed to reclaim it.
	//
	// It exists because a backend's own expiry would otherwise decide when
	// sessions end, and it is the wrong thing to decide it. A record a cache
	// has already dropped cannot be told apart from one that never existed, so
	// a user who idled out and a client presenting a forged identifier would
	// get the same answer; worse, expiry would then be evaluated by the cache
	// server's clock rather than by the store's, which is neither the clock the
	// policy was written against nor one a test can move.
	//
	// So every write asks the backend to keep the record for its deadline plus
	// this, and the store refuses it the moment the deadline passes. The
	// backend's expiry becomes a garbage collector rather than a security
	// control. What it costs is retained bytes for expired sessions; what it
	// buys is a deterministic timeout and a returning user who can be told why
	// they were signed out.
	//
	// Non-positive lets the backend reclaim the record exactly at the deadline,
	// which is the cheaper setting and the one that gives up the distinction.
	Grace time.Duration
}

type Record[T any] struct {
	// CreatedAt is when the session was established. It survives Renew, so
	// rotating an identifier does not extend the absolute deadline — which
	// is the whole reason rotation is safe to do on every privilege change.
	CreatedAt time.Time
	// LastSeenAt is when the session was last read or written. It is the
	// idle deadline's anchor, and it is refreshed no more often than the
	// Policy's touch interval — see Policy.
	LastSeenAt time.Time
	// Data is the payload. It may be nil: a session that only needs to
	// exist is a legitimate session.
	Data *T
	// Metadata is what the session was established from. Like Holder it
	// survives Renew, and unlike the two anchors above it is never
	// reassigned: it describes an establishment rather than a state.
	Metadata Metadata
	// Holder is whose session this is. It survives Renew, so rotating an
	// identifier does not hand the session to somebody else — and it is
	// what makes a principal's sessions enumerable at all.
	Holder Holder
	// Version is the record shape this was written with.
	Version int
}

type Session[T any] struct {
	// CreatedAt is when the session was established, unchanged by Renew.
	CreatedAt time.Time
	// LastSeenAt is the idle deadline's anchor as of this read.
	LastSeenAt time.Time
	// ExpiresAt is the earlier of the absolute and idle deadlines: the
	// instant this session stops being usable if nothing touches it again.
	// It is what a cookie's MaxAge should be derived from, so the browser
	// and the store agree on when the session ended.
	ExpiresAt time.Time
	// Data is the payload, as stored.
	Data *T
	// Metadata is what this session was established from.
	Metadata Metadata
	// ID is the identifier this session was read under. It is the value the
	// cookie carries, and the only part of a session that ever leaves the
	// server.
	ID string
	// Holder is whose session this is.
	Holder Holder
	// IsCurrent reports whether this is the session the caller asked with.
	//
	// It is derived at read time from the identifier passed to Store.List
	// rather than stored, because "current" is a fact about a request and
	// not about a session: the same row is current to one browser and not
	// to the other four. A stored flag would have to be moved on every
	// read, and would be wrong for everybody but the last writer.
	//
	// It is always false outside List — the by-identifier reads answer
	// about the session the caller already named.
	IsCurrent bool
}

type Store[T any] interface {
	// New establishes a session around data and returns it, identifier
	// included. data may be nil.
	//
	// The session it establishes is attributed to nobody: the global scope
	// and the empty principal. It is therefore reachable only by its
	// identifier and appears in no List — which is what an anonymous
	// session is. Call NewFor once somebody has signed in.
	New(ctx context.Context, data *T) (*Session[T], error)
	// NewFor establishes a session held by somebody, with the metadata a
	// security page will render beside it.
	//
	// This is the call a sign-in makes. What separates it from New is that
	// the resulting session is enumerable and revocable as one of that
	// principal's — so a holder with no scope, or no principal, is refused
	// rather than quietly establishing a session nobody can find: see
	// tenancy.ErrNoScope and ErrPrincipalRequired.
	//
	// The holder and the metadata are stamped once. Renew carries both
	// across, and no other write moves either.
	NewFor(ctx context.Context, holder Holder, metadata Metadata, data *T) (*Session[T], error)
	// Get reads a session, refreshing its idle deadline when the Policy's
	// touch interval has elapsed.
	//
	// A session past either deadline is reported as ErrExpired and removed;
	// one that was never there, or whose record was written by another
	// shape of this package, is reported as ErrNotFound.
	Get(ctx context.Context, id string) (*Session[T], error)
	// Save replaces a session's payload. It refreshes the idle deadline and
	// leaves the absolute one alone.
	Save(ctx context.Context, id string, data *T) error
	// Renew rotates a session's identifier, carrying the payload and the
	// original CreatedAt across, and returns the new identifier.
	//
	// Call it on every privilege change — sign-in above all. Without it, an
	// identifier an attacker planted before sign-in is still valid after
	// it, which is session fixation. Because CreatedAt survives, rotating
	// on every privilege change cannot be used to extend a session forever.
	//
	// The old identifier stops working the moment this returns nil. If it
	// returns an error, assume it still works and refuse the privilege
	// change.
	Renew(ctx context.Context, oldID string) (newID string, err error)
	// Delete ends a session. An identifier that was already gone is not an
	// error: sign-out is not the place to surface a race.
	Delete(ctx context.Context, id string) error
	// List enumerates the live sessions holder holds, newest first.
	//
	// currentID is the identifier the caller is asking with, and decides
	// which of the returned sessions has IsCurrent set; the empty string
	// marks none of them. It is not a filter — the session it names is
	// still listed, since a security page that hid the reader's own session
	// would be listing the wrong set.
	//
	// Expired sessions are left out, decided by the same Policy the
	// by-identifier read decides with, so a session this omits is one Get
	// would refuse. Nothing is written: an enumeration does not touch idle
	// deadlines, or reading a security page would keep every session on it
	// alive.
	//
	// A holder with an empty principal is ErrPrincipalRequired. A backend
	// that keeps no principal index is ErrNoPrincipalIndex — see Backend.
	List(ctx context.Context, holder Holder, currentID string) ([]*Session[T], error)
	// Revoke ends one of a holder's sessions.
	//
	// The holder is part of the question rather than checked beforehand: the
	// session ends only if it is the named principal's within the named
	// scope, decided where the row is removed. A caller naming a session
	// that is not theirs is answered ErrNotFound, not a refusal, so the
	// answer does not confirm that the identifier names anything.
	//
	// Unlike Delete this is not idempotent: revoking a session that is
	// already gone is ErrNotFound. Delete ends the caller's own session,
	// where a race is a sign-out that already happened; this ends a session
	// somebody is looking at a list of, where "there was nothing there" is
	// the answer they need to see.
	Revoke(ctx context.Context, holder Holder, id string) error
	// RevokeAll ends every session a holder holds, including the caller's
	// own, and reports how many ended.
	//
	// It is the "sign out everywhere" a password change should trigger.
	RevokeAll(ctx context.Context, holder Holder) (int, error)
	// RevokeAllExcept ends every session a holder holds but one, and
	// reports how many ended.
	//
	// keepID is normally the caller's current session, which is what makes
	// this "sign out my other devices". An empty keepID spares nothing and
	// is exactly RevokeAll; an identifier the holder does not hold spares
	// nothing either, because sparing is by the same key everything else
	// here is.
	RevokeAllExcept(ctx context.Context, holder Holder, keepID string) (int, error)
	// Policy reports the expiry rule this store enforces.
	//
	// It is on the interface because the cookie has to agree with it:
	// sessions/http derives how long a browser should keep a session
	// cookie from the absolute timeout rather than from a second setting
	// that could drift from this one.
	Policy() Policy
	// Close releases what the store holds — the backend's connection pool,
	// a background sweep — and is safe to call more than once.
	Close() error
}