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)
}

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"`
}

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 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
}

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
}

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 whose ExpiresAt is at or before
	// absoluteCutoff, or whose LastSeen is at or before idleCutoff, returning
	// what it deleted. Both cutoffs are absolute times: the store holds no
	// opinion about how long a session should live.
	DeleteExpired(absoluteCutoff, idleCutoff time.Time) ([]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
}