session

type Client string

type Config struct {
	Store Store
	Log   authlog.Log

	// AccessTTL is short because an access token is the one that travels. Ten
	// minutes bounds the damage of a leaked one without making refresh a
	// constant background hum.
	AccessTTL time.Duration
	// RefreshTTL is how long an ordinary session lasts.
	RefreshTTL time.Duration
	// RememberTTL is how long a session lasts when the person asked to stay
	// signed in.
	RememberTTL time.Duration

	// RotationLeeway is how long a refresh token stays usable after it has
	// been exchanged.
	//
	// Without one, a dropped response is a logout: the client never received
	// the new pair, retries with the old one, and gets its whole family
	// revoked for a network blip. Thirty seconds covers the retry and leaves a
	// real replay — which turns up minutes or hours later — firmly outside.
	RotationLeeway time.Duration

	// Limiter and RefreshLimit bound how hard one session may refresh.
	//
	// Both or neither. Nil is a manager nobody wired a limiter into, which has
	// to go on working: this package is constructible without the rest of auth,
	// and a refresh limit is a backstop rather than a security boundary — what
	// it catches is a client looping, not somebody with a stolen token, whose
	// second use is caught by reuse detection instead.
	//
	// The limit counts TokenRefreshed against the token family, so it is one
	// session's budget and not one person's: signing in on a phone and a laptop
	// does not make either of them closer to it.
	Limiter      *throttle.Limiter
	RefreshLimit throttle.Limit

	// Cache keeps verified access tokens in memory, and is told to stop.
	//
	// Nil, the default, means every request reads the row. A cache built by
	// [NewTokenCache] means most of them do not, and that a revocation reaches
	// every replica on the transaction that performed it — so the lifetime in
	// [TokenCacheConfig] is the backstop rather than the guarantee.
	//
	// There is no plain time-to-live here any more, and its absence is the
	// decision: a cache over authentication with nothing to withdraw an entry
	// is a revoked session that keeps working, which is not a trade this
	// package offers.
	Cache *TokenCache

	// OnRotate replaces a session's payload when it is refreshed.
	//
	// Nil — the default — carries the previous payload forward unchanged, which is
	// what an application that never sets one wants and what an application that
	// set one at sign-in usually wants too.
	//
	// It is handed the token being exchanged, so the current payload is
	// prev.Payload and everything else about the session is there to decide from.
	// Returning nil clears the payload; returning an error fails the refresh,
	// which means a session cannot be refreshed while this is broken — deliberate,
	// since the alternative is quietly serving a payload the application refused
	// to produce.
	//
	// It runs inside the rotation's transaction, once per refresh, and both new
	// tokens get the result. Keep it quick: it is on the path every client takes
	// when its access token expires.
	OnRotate func(ctx context.Context, prev *Token) (json.RawMessage, error)

	// Now is swappable for tests.
	Now func() time.Time
}

type Family struct {
	// Root is the token the session started from.
	Root *Token
	// LastUsedAt is the newest descendant's creation time, which is when the
	// session last refreshed. Deriving it beats maintaining a column that
	// every request would have to write.
	LastUsedAt time.Time
	// Tokens is how many tokens the family has produced.
	Tokens int
}

type Identity struct {
	ID         uuid.UUID
	IdentityID uuid.UUID

	SecretHash []byte

	CreatedAt time.Time
	ExpiresAt time.Time
	// RevokedAt is set by signing out, and by picking a tenant: once there is
	// a real session there is no reason to leave a second credential alive.
	RevokedAt *time.Time

	IPAddress string
	UserAgent string
}

type IdentityConfig struct {
	Store IdentityStore
	// TTL defaults to [DefaultIdentityTTL].
	TTL time.Duration
	// Now is swappable for tests.
	Now func() time.Time
}

type IdentityIssueInput struct {
	IdentityID uuid.UUID
	IPAddress  string
	UserAgent  string
}

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

type IdentityStore interface {
	InsertIdentitySession(ctx context.Context, s *Identity) error
	FindIdentitySession(ctx context.Context, id uuid.UUID) (*Identity, error)
	RevokeIdentitySession(ctx context.Context, id uuid.UUID, at time.Time) error
	// RevokeIdentitySessionsFor ends every one a person holds, which is what a
	// password change means.
	RevokeIdentitySessionsFor(ctx context.Context, identityID uuid.UUID, at time.Time) (int, error)
}

type IssueInput struct {
	TenantID  uuid.UUID
	AccountID uuid.UUID
	Client    Client

	IPAddress string
	UserAgent string

	// Remember asks for the long lifetime.
	Remember bool

	// ImpersonatedByAccountID marks a session an administrator opened as
	// somebody else. It propagates through every rotation, so a session that
	// began as impersonation cannot quietly become an ordinary one.
	ImpersonatedByAccountID *uuid.UUID
	// APIKeyID marks a session minted for a machine.
	APIKeyID *uuid.UUID

	// Payload is the application's own context for this session — which device,
	// which sign-in method, when step-up authentication was last satisfied. It is
	// carried forward by every rotation and reaches a handler as
	// [tenancy.Claims.Extra].
	//
	// Never authorization. It is written here and again only when the session is
	// refreshed, so a permission kept in it stays true for as long as the refresh
	// lifetime — twelve hours, or thirty days for "remember me" — after somebody
	// took it away.
	Payload json.RawMessage
}

type Issued struct {
	// Token is the value to hand the client. It cannot be recovered later:
	// only its hash is stored.
	Token     string
	TokenID   uuid.UUID
	ExpiresAt time.Time
}

type Kind string

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

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

type Pair struct {
	Access  Issued
	Refresh Issued
	// RootTokenID identifies the session the pair belongs to. It is what a
	// client shows on a "signed in devices" screen and what Revoke takes.
	RootTokenID uuid.UUID
}

type Store interface {
	// Insert writes a token.
	Insert(ctx context.Context, t *Token) error

	// Find reads a token by identifier, or returns nil when there is none.
	//
	// A missing token is not an error: it is the ordinary answer to a
	// presented value that was made up.
	Find(ctx context.Context, id uuid.UUID) (*Token, error)

	// Lock reads a token for update inside the caller's transaction.
	//
	// Rotation reads, decides, and writes, and two requests doing that at once
	// would both see an unconsumed token. The lock is what makes the second
	// one see the first one's work.
	Lock(ctx context.Context, id uuid.UUID) (*Token, error)

	// MarkRotated records the first exchange of a token.
	//
	// Implementations must leave an existing value alone. If a replay could
	// push the timestamp forward, an attacker replaying every twenty seconds
	// would keep a thirty-second leeway open indefinitely.
	MarkRotated(ctx context.Context, id uuid.UUID, at time.Time) error

	// RevokeFamily kills every live token descending from a root and returns
	// the identifiers of the ones it killed.
	//
	// The identifiers rather than a count, because a cache over verification is
	// keyed by the access token a request presents and not by the session it
	// belongs to — so "this session is over" has to be spelled out as the
	// tokens it was made of before anything can be told to forget them. A
	// caller that only wants the count takes len.
	RevokeFamily(ctx context.Context, rootID uuid.UUID, at time.Time) ([]uuid.UUID, error)

	// Families lists an account's sessions, newest first.
	Families(ctx context.Context, tenantID, accountID uuid.UUID) ([]Family, error)

	// TenantFamilies lists every session open in a tenant, newest first.
	//
	// A second method rather than a nullable account on the first, for the reason
	// [Store] is small: "every session in the tenant" and "this person's
	// sessions" are different questions with different authority behind them, and
	// a nil argument that silently widens a read is the kind of parameter that
	// gets passed a zero value by accident.
	TenantFamilies(ctx context.Context, tenantID uuid.UUID) ([]Family, error)

	// InTx runs fn inside one transaction, joining one already in progress.
	InTx(ctx context.Context, fn func(ctx context.Context) error) error
}

type Token struct {
	ID        uuid.UUID
	TenantID  uuid.UUID
	AccountID uuid.UUID
	Kind      Kind

	// RootTokenID is the family. The first token of a session is its own root,
	// which is what lets "revoke this session" be one indexed UPDATE.
	RootTokenID uuid.UUID
	// ParentTokenID is the token this one was minted from, nil for a root.
	ParentTokenID *uuid.UUID

	SecretHash []byte

	CreatedAt time.Time
	ExpiresAt time.Time
	// RotatedAt is when this token was first exchanged. It is a soft consume:
	// the row stays, because a replay of a consumed token is the signal that
	// matters and a deleted row cannot signal anything.
	RotatedAt *time.Time
	// RevokedAt is a hard kill.
	RevokedAt *time.Time

	IPAddress string
	UserAgent string
	Client    Client

	ImpersonatedByAccountID *uuid.UUID
	APIKeyID                *uuid.UUID

	// Payload is whatever the application wants to remember about this session.
	//
	// Opaque here on purpose: this package stores and copies it and never looks
	// inside. It survives every rotation, so a fact recorded at sign-in is still
	// there twelve hours later — and is only as fresh as the last refresh, which
	// is why nothing deciding what somebody may do belongs in it. Grants are
	// resolved per request for exactly that reason.
	Payload json.RawMessage
}

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

type TokenCacheConfig struct {
	// TTL is how long a verified token may be reused with no invalidation
	// arriving, and the whole cost of the cache stated as time.
	//
	// It is the backstop rather than the guarantee: a revocation is published on
	// the transaction that performed it, so the ordinary case is that every
	// replica has forgotten before the next request arrives. This is what
	// remains if one of them was not listening.
	//
	// Zero or less caches nothing.
	TTL time.Duration

	// MaxEntries bounds the map. Zero takes the package default.
	MaxEntries int

	// Now is the clock, for tests.
	Now func() time.Time
}