oidcauth

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

type ClaimFreshnessError struct {
	// Age is how stale the claims were, and Limit the configured bound.
	Age   time.Duration
	Limit time.Duration

	// Reason is the machine-readable cause, also used as the audit reason:
	// no_refresh_token, idp_unreachable, or claims_rejected.
	Reason string

	// Err is the underlying failure, if there was one. Nil for
	// no_refresh_token, where nothing was attempted because nothing could be.
	Err error
}

type Config struct {
	Enabled  bool
	Issuer   string // e.g. https://auth.example.com/realms/main
	ClientID string

	// ClientSecret is optional. Empty means cloop registers as a public
	// client and presents no credential at the token endpoint, relying on
	// the PKCE S256 binding that every authorization request carries
	// regardless. That is the default the Terraform module provisions,
	// because a credential that must be rotated, distributed and revoked is
	// the most expensive part of running this and PKCE removes the need for
	// one. Set it to add client authentication on top.
	ClientSecret string

	RedirectURL  string   // e.g. https://cloop.example.com/auth/callback
	Scopes       []string // default: openid profile email
	AdminEmails  []string // users who see every project regardless of owner
	SessionTTL   time.Duration
	CookieSecure string // "auto" (default), "always", "never"

	// IdleTimeout ends a session that has gone unused for this long, even
	// though its absolute ceiling has not been reached. Zero uses
	// DefaultIdleTimeout; negative disables the idle clock entirely, which is
	// only appropriate on a single-operator loopback deployment.
	IdleTimeout time.Duration

	// RefreshInterval is how often a session is revalidated against the IdP
	// using its stored refresh token. Zero uses DefaultRefreshInterval;
	// negative disables the check, which also disables IdP-side revocation —
	// the two timeouts then become the only way a session ends.
	RefreshInterval time.Duration

	// MaxClaimAge bounds how stale a session's group and role claims may be at
	// the moment it exercises a permission above operator — granting a
	// credential, minting a token, rewriting role bindings (Task 20273). Past
	// it, EnsureFreshClaims re-asserts them against the IdP synchronously and
	// the operation is refused if the provider cannot be asked.
	//
	// Zero uses DefaultMaxClaimAge; negative disables the check, which is the
	// documented opt-out for a deployment that cannot retain refresh tokens.
	// Anything above MaxMaxClaimAge is rejected by New — past an hour this has
	// stopped being a freshness bound.
	//
	// It is deliberately independent of RefreshInterval. That knob sets a
	// background cadence and can be switched off entirely; this one is a
	// property the privileged path must hold whatever the background pass is
	// doing, so "never re-check" must not be expressible for it by accident.
	MaxClaimAge time.Duration

	// Store persists sessions. Nil installs a process-local store, which is
	// the pre-Task-20176 behaviour: a restart signs everyone out.
	Store SessionStore

	// Audit receives every session lifecycle event. Nil discards them.
	//
	// A callback rather than a direct write to the trail because this package
	// is stdlib-only by design and the trail lives in SQLite. pkg/ui supplies
	// the sink. Implementations must not block: they are called while a
	// request or the janitor is waiting.
	Audit func(SessionAudit)

	// ClockSkew is the leeway applied to an ID token's exp and iat claims.
	// Zero uses DefaultClockSkew; negative means no leeway at all (the
	// strictest setting, appropriate where both clocks are known-good).
	// Anything above MaxClockSkew is rejected by New.
	//
	// It is a knob rather than a constant because the deployments that need
	// it are the ones that cannot fix the underlying problem: an on-premise
	// IdP on a host whose NTP is blocked by the same firewall that makes it
	// on-premise. The bound is what keeps it from being used as a way to
	// accept tokens that expired ten minutes ago.
	ClockSkew time.Duration

	// Clock supplies the current time. Nil means time.Now. It exists so the
	// two expiry clocks can be tested without sleeping through them.
	Clock func() time.Time

	// SessionLimit reports how many concurrent sessions one identity may
	// hold. Zero (and a nil hook) means unlimited. Supplied by pkg/ui from
	// the per-identity quota policy; this package stays stdlib-only and
	// holds no opinion about where the number comes from (Task 20182).
	//
	// The cap is enforced by evicting the identity's least recently used
	// sessions, never by refusing the login. Refusing would leave the user
	// with no session at all — and the self-service remedy, POST
	// /api/session/logout-all, requires one, so a capped user could be
	// locked out of their own account with no way back in. Eviction keeps
	// the invariant the cap exists for (no identity holds more than N)
	// without that failure mode.
	SessionLimit func(identity string, groups, roles []string) int

	// EffectiveRole reports the role a set of claims resolves to, and its
	// rank on the role ladder (higher is more authority). It exists so a
	// revalidation that narrows somebody's authority can say *what* they
	// lost — "admin → viewer" rather than "claims changed".
	//
	// Supplied by pkg/ui from the pkg/authz resolver, for the same reason
	// SessionLimit is: this package stays stdlib-only and holds no opinion
	// about how claims become roles. Nil is fully supported — narrowing is
	// then reported by the claims that disappeared, which is the fact this
	// package can establish on its own.
	//
	// It is consulted only on the revalidation path, never per request, so
	// its cost is paid once per session per refresh interval.
	EffectiveRole func(identity string, groups, roles []string) (role string, rank int)

	// StatePrefix, when set, begins every login's state parameter, followed
	// by a dot (Task 20354). The state is the one value the identity
	// provider hands back unchanged on the callback, and a login's nonce and
	// PKCE verifier live only in the memory of the process that began it —
	// so on a control plane served by several hub processes the state has to
	// say which one that was, and the process the callback reaches forwards
	// it there. See StateOwner. It must not contain a dot.
	StatePrefix string

	// OnCacheInvalidate, when set, is told each time a session's cached copy
	// is dropped because the session changed — revoked, logged out, expired,
	// or its claims refreshed (Task 20354). Other hub processes sharing the
	// session store keep their own caches, and without this they would go on
	// honouring a revoked session until their copy aged out. It must not
	// block.
	//
	// It is called once the change is in the store, so a listener that
	// re-reads the session on the strength of it — CheckSession, to decide
	// whether a stream opened with it may stay open (Task 20398) — reads the
	// new row, or its absence. It names the session, not the change: a claim
	// refresh is announced exactly as a revocation is, so a listener must
	// re-check rather than conclude.
	OnCacheInvalidate func(sessionID string)

	// RefreshLock, when set, serialises refresh-token redemptions for one
	// session across every process sharing the session store (Task 20354).
	// It returns once the caller holds the right to redeem, and the release
	// to call afterwards. A single process collapses concurrent refreshes of
	// one session into one flight; several processes cannot see each other's
	// flights, and a provider that rotates refresh tokens answers the second
	// redemption of one token with invalid_grant — which ends the session. A
	// dashboard's page load fans out across processes, so without this the
	// first privileged page load after the claims went stale would sign the
	// user out.
	RefreshLock func(ctx context.Context, sessionID string) (release func(), err error)

	// RenewObserver receives the verdict of every silent renewal that reached
	// one (Task 20359). Nil discards them.
	//
	// A callback for the same reason Audit is one: the outcome belongs in
	// hubmetrics, which is not stdlib. It is also the only way the verdict
	// leaves this package, because a renewal completes inside HandleCallback,
	// whose return value describes sign-ins — overloading that would put a
	// background re-check into the ratio an operator reads as "can people sign
	// in". Called on verdicts only, never on the redirect to the provider.
	// Implementations must not block.
	RenewObserver func(RenewOutcome)

	// DeviceLogin turns on the device authorization grant that signs a
	// terminal in (Task 20412, device.go): `cloop login` against this hub.
	DeviceLogin bool

	// CLISessionTTL and CLIIdleTimeout are a terminal session's two clocks.
	// Zero uses the browser's; anything longer than the browser's is held
	// down to it, because a terminal session — the credential that sits in a
	// file — is never longer-lived than a browser one. A negative
	// CLIIdleTimeout turns the terminal's idle clock off only where the
	// browser's is off too.
	CLISessionTTL  time.Duration
	CLIIdleTimeout time.Duration

	// DeviceApprovalMaxAge is how long ago a browser session may have signed
	// in and still approve a terminal without signing in again at the
	// identity provider. Zero uses DefaultDeviceApprovalMaxAge; negative
	// never asks.
	DeviceApprovalMaxAge time.Duration

	// Devices persists device authorizations. Nil uses Store when it is also
	// a DeviceStore (pkg/sessionstore is), and process memory otherwise.
	Devices DeviceStore

	// SessionGate is asked before a terminal session is written for an
	// approved code, with the identity the provider just asserted; an error
	// refuses it and denies the code. pkg/ui supplies a check of the runtime
	// deny bindings, so an account being offboarded cannot start a terminal
	// session on the way out. Nil admits everyone the provider vouches for.
	SessionGate func(Identity) error

	// RequestIsTLS reports whether a request reached the hub over TLS as the
	// browser sees it: the hub's own listener, or a proxy the hub trusts that
	// said so in X-Forwarded-Proto (Task 20394). cookie_secure "auto"
	// follows it. Nil believes X-Forwarded-Proto from a loopback peer only —
	// the hub's rule with no ui.trusted_proxies — because the header is
	// anybody's to send, and a session cookie's attributes are not theirs to
	// choose.
	RequestIsTLS func(*http.Request) bool
}

type ConfigError struct {
	Field string
	Err   error
}

type DeviceApproval struct {
	// RedirectURL is the identity provider's authorization endpoint. The
	// approval completes when the provider sends the browser back.
	RedirectURL string
	// Reauth reports that the provider was asked to have the person sign in
	// again (prompt=login, max_age=0).
	Reauth bool
}

type DeviceAuditDetail struct {
	ID              string
	ClientIP        string
	ClientUserAgent string
	ClientHostname  string
	ExpiresAt       time.Time
	// Reauth reports that approving it demanded a fresh sign-in at the
	// identity provider.
	Reauth bool
}

type DeviceGrant struct {
	DeviceCode string
	// UserCode is formatted for reading: two groups of five.
	UserCode  string
	ExpiresIn time.Duration
	Interval  time.Duration
}

type DeviceRecord struct {
	DeviceHash     string
	UserCodeHash   string
	CredentialHash string
	Status         DeviceStatus

	// ClientIP, ClientUserAgent and ClientHostname describe who asked: the
	// first two as the hub saw the request, the last as the terminal reported
	// it. Labels for the person deciding, never inputs to the decision.
	ClientIP        string
	ClientUserAgent string
	ClientHostname  string

	CreatedAt time.Time
	ExpiresAt time.Time

	// Interval is how often the terminal may poll, and LastPolledAt when it
	// last did. Polling faster earns slow_down and a longer interval.
	Interval     time.Duration
	LastPolledAt time.Time

	// Approver is who decided (an owner key, or "hub" when the hub denied it
	// on someone's behalf), ApproverSession the hashed id of the browser
	// session that did, Subject their IdP subject, and Reason why a denial
	// happened.
	Approver        string
	ApproverSession string
	Subject         string
	DecidedAt       time.Time
	Reason          string
}

type DeviceRequest struct {
	// CredentialHash is HashSessionID of the credential the terminal generated
	// and will present once approved: 64 lower-case hex digits.
	CredentialHash string
	// Hostname is what the terminal calls the machine it runs on.
	Hostname string
	// IP and UserAgent are the request's, as the hub saw it.
	IP        string
	UserAgent string
}

type DeviceSession struct {
	// SessionID is the session's public id — the digest the terminal
	// committed to — as the Active Sessions table lists it.
	SessionID string
	Identity  Identity
	ExpiresAt time.Time
	// ExpiresIn is what is left of the session's absolute lifetime, on the
	// authenticator's clock.
	ExpiresIn time.Duration
	// IdleTimeout is the idle window, zero when the clock is off.
	IdleTimeout time.Duration
	// Revalidated reports that the hub keeps a refresh grant for the session,
	// so the identity provider is asked about it again: a demotion or a
	// disabled account reaches it, and privileged actions can re-check their
	// claims. False on a hub with no CLOOP_SECRET_KEY, or a provider that
	// issues no refresh token.
	Revalidated bool
}

type DeviceStatus string

type DeviceStore interface {
	// PutDevice records a new authorization. It must not overwrite one.
	PutDevice(DeviceRecord) error

	// GetDevice returns the authorization for a device code digest, or an
	// error wrapping ErrDeviceNotFound.
	GetDevice(deviceHash string) (DeviceRecord, error)

	// GetDeviceByUserCode returns the newest authorization for a user code
	// digest, or an error wrapping ErrDeviceNotFound.
	GetDeviceByUserCode(userCodeHash string) (DeviceRecord, error)

	// UpdateDevice reads the authorization for deviceHash, applies change
	// to it, and writes it back if change reports a change — atomically. It
	// returns the record as stored afterwards. change must not call the
	// store.
	UpdateDevice(deviceHash string, change func(*DeviceRecord) (bool, error)) (DeviceRecord, error)

	// DeleteDevicesBefore removes the authorizations whose ExpiresAt is at or
	// before cutoff, returning them.
	DeleteDevicesBefore(cutoff time.Time) ([]DeviceRecord, error)

	// CountDevicesSince counts the authorizations issued after since: the
	// hub-wide issuing rate.
	CountDevicesSince(since time.Time) (int, error)
}

type DeviceTokenError struct {
	// Code is one of the DeviceErr* values.
	Code string
	// Description says it in words, for the terminal to print.
	Description string
	// Interval is the polling interval from now on; set with slow_down.
	Interval time.Duration
}

type DeviceView struct {
	// UserCode is the code, formatted.
	UserCode string
	Status   DeviceStatus
	Expired  bool

	// Who is asking, as the hub saw them and as the terminal said. Empty
	// once somebody else decided the code: what another person's terminal
	// is called is none of the caller's business.
	ClientIP        string
	ClientUserAgent string
	ClientHostname  string
	CreatedAt       time.Time
	ExpiresAt       time.Time
	// ExpiresIn is what is left of the code's life, on the authenticator's
	// clock; zero once it has run out.
	ExpiresIn time.Duration

	// DecidedByCaller reports that the person asking decided the code.
	DecidedByCaller bool
	DecidedAt       time.Time

	// Reauth reports that approving will ask the caller to sign in again at
	// the identity provider, and SignedInAt when their browser session did.
	Reauth     bool
	SignedInAt time.Time

	// Identity is who approving would sign the terminal in as — the caller.
	Identity Identity
}

type ExpiryCutoffs struct {
	Absolute time.Time
	Idle     time.Time
	CLIIdle  time.Time
}

type Identity struct {
	Sub   string `json:"sub"`
	Email string `json:"email,omitempty"`
	Name  string `json:"name,omitempty"`

	// Groups and Roles carry the group/role claims the IdP released,
	// flattened from whatever shape it used. They are the input to
	// pkg/authz role mappings; an IdP that releases neither leaves both
	// empty and every identity falls back to oidc.default_role.
	Groups []string `json:"groups,omitempty"`
	Roles  []string `json:"roles,omitempty"`

	// Username is the preferred_username claim, and OID Microsoft Entra
	// ID's oid claim — the account's login and directory object id at the
	// provider (Task 20415). They are what a SCIM directory is matched
	// against (ui.oidc.scim.match_claim), and what a deny binding written
	// when the provider deactivates the account names. Empty when the
	// provider released neither.
	Username string `json:"username,omitempty"`
	OID      string `json:"oid,omitempty"`

	// AuthTime is the id_token's auth_time: when the person last actually
	// authenticated at the provider, as opposed to when the token was minted.
	// Read once, by an approval that demanded a fresh sign-in (device.go), and
	// never stored or serialised.
	AuthTime time.Time `json:"-"`
}

type LiveCounter interface {
	CountLive(c ExpiryCutoffs) (int, error)
}

type LoginOutcome string

type PreflightError struct {
	// Issuer is the configured issuer, always populated — it is the value
	// an operator most likely needs to correct.
	Issuer string

	// Stage is StageDiscovery or StageJWKS.
	Stage string

	// URL is the endpoint that failed.
	URL string

	// Status is the HTTP status when the endpoint answered, 0 when it did
	// not answer at all (DNS, refused connection, TLS, timeout).
	Status int

	// Reason is one of the Preflight* constants.
	Reason string

	// Detail is the human-readable specifics.
	Detail string

	// Resolved carries what the preflight did establish before it failed,
	// which for a StageJWKS failure is the whole discovery document. A
	// diagnostic reports the two stages separately — "the issuer resolved,
	// its keys did not" is a different problem with a different fix — and
	// without this it would have to re-fetch the document to say so.
	// Nil for a StageDiscovery failure, where nothing was established.
	Resolved *PreflightResult

	// Err is the underlying error, if any.
	Err error
}

type PreflightOptions struct {
	// Timeout bounds the whole preflight. Zero uses DefaultPreflightTimeout.
	Timeout time.Duration

	// Client performs the requests. Nil builds one bounded by Timeout. A
	// caller supplying one (the doctor, tests) owns its transport and its
	// own timeout.
	Client *http.Client
}

type PreflightResult struct {
	Issuer                string `json:"issuer"`
	AuthorizationEndpoint string `json:"authorization_endpoint"`
	TokenEndpoint         string `json:"token_endpoint"`
	JWKSURI               string `json:"jwks_uri"`
	EndSessionEndpoint    string `json:"end_session_endpoint,omitempty"`

	// SigningKeys is how many keys in the set cloop can actually verify
	// with, which is the number that decides whether a token validates —
	// not how many the provider published.
	SigningKeys int `json:"signing_keys"`
}

type RefreshResult struct {
	// RefreshToken is the token to present next time: the provider's
	// replacement when it rotated, otherwise the one just redeemed. Empty
	// clears the stored token, which is how a session that can no longer be
	// revalidated stops being retried.
	RefreshToken string

	// CheckedAt stamps when the IdP last answered for this session.
	CheckedAt time.Time

	// ClaimsAsserted reports whether the refresh response carried an id_token
	// that verified. Only then are Groups and Roles meaningful; when it is
	// false the stored claims must be left exactly as they are, because
	// "the IdP did not say" is not "the IdP said nothing applies".
	ClaimsAsserted bool
	Groups         []string
	Roles          []string

	// ClaimsAsOf and ClaimsExpireAt update the session's claim-freshness clocks
	// (Task 20273). A zero value leaves the stored one alone, which is what
	// makes the three outcomes of a revalidation expressible:
	//
	//	claims re-asserted   both set — the assertion, and how long the IdP
	//	                     stands behind it (from the access token's
	//	                     expires_in, or zero when it named none)
	//	claims repudiated    ClaimsExpireAt set to the instant of the refusal,
	//	                     ClaimsAsOf untouched — the row still records when
	//	                     the claims were last true, and now also records
	//	                     that they have stopped being so
	//	nothing learned      both zero — the grant is alive, the claims are as
	//	                     stale as they were, and nothing may pretend
	//	                     otherwise
	//
	// They are part of RefreshResult, and therefore of its single atomic write,
	// for the reason in the type comment: a stamp written without the claims it
	// stands for is a session that looks re-authorized while holding authority
	// the provider has withdrawn.
	ClaimsAsOf     time.Time
	ClaimsExpireAt time.Time
}

type RenewOutcome string

type SessionAudit struct {
	Event     auditaction.Action
	SessionID string
	Subject   string
	Email     string
	Actor     string
	Reason    string
	IP        string
	UserAgent string
	At        time.Time

	// PriorRole and Role name the effective role before and after a claim
	// refresh, and are set only by AuditSessionRoleNarrowed. They are empty
	// when the deployment supplies no EffectiveRole hook, in which case
	// DroppedClaims alone describes the narrowing.
	PriorRole string
	Role      string

	// DroppedClaims lists the group and role values the IdP released at
	// sign-in and no longer releases. Naming them is the difference between
	// an event an auditor can act on and one that only says something changed.
	DroppedClaims []string

	// Kind and Client describe the session the event is about (Task 20412):
	// browser or cli, and for a terminal the host name it reported. Empty
	// Kind means the emitter did not know, which the sink leaves out.
	Kind   SessionKind
	Client string

	// Device is set on the device.* events and names the authorization; the
	// sink files those under it rather than under SessionID.
	Device *DeviceAuditDetail

	// Via names the path an event arrived by when it was not the hub's own
	// doing: "browser_renewal" for claims a silent renewal re-asserted from
	// the user's browser (Task 20359). Empty for the server-side refresh.
	Via string
}

type SessionClock struct {
	// ClaimAge is how old the session's claims are, and MaxClaimAge the bound
	// they are held to; zero MaxClaimAge means the bound is off.
	ClaimAge    time.Duration
	MaxClaimAge time.Duration

	// Renew reports whether the browser should re-assert the claims through
	// /auth/renew on a timer, and RenewIn when. See BrowserRenewIn.
	Renew   bool
	RenewIn time.Duration

	// ExpiresIn is what is left of the absolute lifetime, which no renewal
	// lifts. Meaningful when HasExpiry.
	ExpiresIn time.Duration
	HasExpiry bool
}

type SessionKind string

type SessionRecord struct {
	ID       string
	Identity Identity

	IP        string
	UserAgent string

	IssuedAt  time.Time
	LastSeen  time.Time
	ExpiresAt time.Time

	RefreshToken     string
	RefreshCheckedAt time.Time

	// ClaimsAsOf is when the identity provider last asserted Identity's groups
	// and roles, and ClaimsExpireAt is the provider's own deadline on that
	// assertion (Task 20273).
	//
	// They are separate from RefreshCheckedAt because the two answer different
	// questions and routinely disagree. RefreshCheckedAt is stamped on every
	// revalidation attempt including the ones that learned nothing, so it means
	// "the grant was still alive at this instant" — which is what bounds
	// IdP-initiated revocation. These two mean "the claims in this row were
	// true at this instant", which is what bounds authorization staleness. A
	// provider that renews the grant without restating claims advances the
	// first and not the second, and collapsing them would report such a hub as
	// re-authorizing every fifteen minutes while its roles never move.
	//
	// See claimfresh.go for how they are read; ClaimsAssertedAt handles the
	// zero value, which is a session created before these columns existed.
	ClaimsAsOf     time.Time
	ClaimsExpireAt time.Time

	// Kind is what the session authenticates (Task 20412): a browser, by its
	// cookie, or a terminal, by `Authorization: Bearer cloop_cli_…`. Neither
	// is accepted the other way. Empty reads as a browser session — see
	// IsCLI — and Client is the host name a terminal reported, a label like
	// IP and UserAgent.
	Kind   SessionKind
	Client string
}

type SessionState string

type SessionStore interface {
	// Put writes a new session. It must not overwrite an existing id.
	Put(SessionRecord) error

	// Get returns the session with id, or an error wrapping
	// ErrSessionNotFound.
	Get(id string) (SessionRecord, error)

	// List returns every session, most recently active first.
	List() ([]SessionRecord, error)

	// Touch records that a session was used at t. Called off the
	// authentication path and throttled by the caller; failures are advisory
	// and must not fail a request.
	Touch(id string, t time.Time) error

	// Delete removes one session and reports whether it existed.
	Delete(id string) (bool, error)

	// DeleteBySubject removes every session for subject except keepID (empty
	// removes all of them), returning what it deleted so each can be audited.
	DeleteBySubject(subject, keepID string) ([]SessionRecord, error)

	// DeleteExpired removes sessions past one of c's cutoffs, returning what
	// it deleted. The cutoffs are absolute times: the store holds no opinion
	// about how long a session should live.
	DeleteExpired(c ExpiryCutoffs) ([]SessionRecord, error)

	// DueForRefresh returns up to limit sessions holding a refresh token whose
	// last IdP check is at or before cutoff, oldest first.
	DueForRefresh(cutoff time.Time, limit int) ([]SessionRecord, error)

	// ApplyRefresh records the outcome of one IdP revalidation. It must apply
	// every field of res in a single atomic write — see RefreshResult for why
	// splitting it is a privilege-retention bug.
	ApplyRefresh(id string, res RefreshResult) error
}