oidc

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

type Config struct {
	// IssuerURL is the OIDC provider's public issuer — the browser redirect target and "iss" claim.
	IssuerURL string
	// InternalIssuerURL, when set, is where wardynd itself reaches the IdP for server-side calls,
	// solving split-horizon where the browser and control plane see different hostnames.
	InternalIssuerURL string
	// ClientID is the OAuth2 client identifier registered with the IdP.
	ClientID string
	// ClientSecret is the OAuth2 client secret; never logged. Optional: empty registers a public
	// client (PKCE S256 is still sent on every login), not a weaker registration.
	ClientSecret string
	// RedirectURL is the callback URL registered with the IdP; must be <wardynd-base>/auth/callback.
	RedirectURL string
	// BasePath is WARDYN_BASE_PATH ("" = host root): prefix of every console redirect and cookie Path.
	BasePath string
	// AllowedEmailDomains, when non-empty, restricts login to emails whose domain exactly matches
	// one of the listed values case-insensitively, AND requires email_verified=true. Entra tokens
	// typically omit email_verified, fail-closing every Entra login — prefer Entra App Roles instead.
	AllowedEmailDomains []string
	// RequireEmailVerified (WARDYN_OIDC_REQUIRE_EMAIL_VERIFIED, default false) applies the same
	// email_verified gate AllowedEmailDomains implies, without a domain list: an ID token with no
	// email_verified claim counts as unverified and is refused, false is refused, true passes.
	RequireEmailVerified bool
	// ExtraScopes is WARDYN_OIDC_EXTRA_SCOPES (CSV), appended to the fixed "openid profile email"
	// request. Validated at boot against discovery scopes_supported, so an unadvertised scope
	// refuses boot by name instead of locking every human out at login with invalid_scope.
	ExtraScopes []string
	// RoleMap maps a case-insensitive claim/email value to RoleAdmin or RoleUser (WARDYN_OIDC_ROLE_MAP,
	// parsed by ParseRoleMap). Any RoleAdmin match wins. Empty (default) keeps every human RoleAdmin.
	RoleMap map[string]string
	// DefaultRole is the role a human gets when RoleMap is non-empty but nothing matched: RoleAdmin,
	// RoleUser, or "" (default) to DENY the login.
	DefaultRole string
	// LegacyAdminEmails (WARDYN_OIDC_OPERATOR_EMAILS) is the sole admin-tier source when no RoleMap
	// is set; an email on it always derives RoleAdmin, top precedence like a RoleMap match.
	LegacyAdminEmails []string
	// SecureCookies, when true, marks every cookie Secure (HTTPS only) and adds __Host-/Path=/. MUST
	// be true exactly when the connection is TLS-protected; false is required for plain-HTTP demo
	// deployments, since a Secure cookie is never sent over plain HTTP and login would silently break.
	SecureCookies bool
	// Revocations is the pg-backed revoke-a-human-now lever: sessions are stateless signed cookies
	// with nothing to delete, so this tracks a per-principal (and global) cutoff time and Middleware
	// treats any session issued at-or-before it as invalid. nil (default) means never checked.
	Revocations SessionRevocations

	// RoleMappings is the console-managed role-mapping store, merged with RoleMap on each login
	// (RoleMap wins a duplicate key). A read error DENIES the login rather than falling back to the
	// env-only map, which could widen access under DefaultRole=admin. nil is env-only derivation.
	RoleMappings RoleMappingSource

	// UserTypes is the store of user types, read once per login beside RoleMappings. A read error
	// denies the login. nil means only "standard" exists.
	UserTypes UserTypeSource

	// RoleStampTTL is WARDYN_ROLE_STAMP_TTL: the oldest a session's role stamp may be, measured from
	// the session's IssuedAt (the cookie's role is fixed then; only a sign-in changes it). An older
	// session is rejected as "role_stamp_stale" and its owner signs in again. A cookie without an
	// IssuedAt is older than any TTL. Zero is off. A session also ends at Expiry (the ID token's
	// expiry, or SessionTTL from sign-in when that is set), so this only matters when it is shorter.
	RoleStampTTL time.Duration

	// SessionTTL is WARDYN_OIDC_SESSION_TTL: when set, a console session lasts this long from
	// sign-in instead of ending at the ID token's expiry. Zero (the default) keeps the ID token's
	// expiry. Boot refuses more than 24 hours. Nothing re-checks the identity provider during a
	// session, so a longer session should be paired with RoleStampTTL.
	SessionTTL time.Duration

	// OnLogin, when set, is called synchronously after an APPROVED login with what that login
	// established (LoginFacts). A failure inside it must never fail the login; nil is a no-op.
	OnLogin func(ctx context.Context, facts LoginFacts)

	// Identities, when set, is the per-identity gate (identity_gate.go): admission refuses a
	// deactivated identity on every issuer, issuance records the identity row and stamps the
	// session with its authority epoch, and a Revocations that implements IdentityRevocations
	// refuses a cookie whose epoch a later suspension passed. nil is no gate.
	Identities IdentityGate
}

type Derivation struct {
	Role     string
	UserType string
	Matches  []Match
	Denial   string
	// Tied is the custom types that tied at the top priority, sorted.
	Tied []string
	// Unknown is the named types that do not exist, sorted.
	Unknown []string
}

type IdentityGate interface {
	// Refused reports, without writing, whether the identity a sign-in names is deactivated or
	// purged. An error fails the sign-in closed.
	Refused(ctx context.Context, ref IdentityRef) (bool, error)
	// Issue upserts and binds the sign-in's identity row, re-checks its deactivation and returns
	// the authority epoch the session cookie must carry, all under the row's lock so a suspension
	// either precedes it (ErrIdentityDeactivated) or leaves the cookie's epoch stale. An error
	// fails the sign-in closed.
	Issue(ctx context.Context, f LoginFacts) (epoch int64, err error)
	// Bound reports, without writing, the principal the identity row keyed by ref's issuer, tenant
	// and object id is bound to: "" when there is no such row or it is bound to no one yet. An error
	// fails the caller closed.
	Bound(ctx context.Context, ref IdentityRef) (string, error)
}

type IdentityRef struct {
	Issuer, TenantID, ObjectID, Principal string
}

type IdentityRevocations interface {
	SessionStatus(ctx context.Context, sub, email string, issue Issue, epoch int64) (SessionStatus, error)
}

type Issue struct {
	At  time.Time
	Seq int64
}

type LoginFacts struct {
	// Sub is the principal the session carries.
	Sub      string
	Role     string
	UserType string
	Groups   []string
	// GroupsTruncated reports Groups is a partial snapshot.
	GroupsTruncated bool
	// Issuer is the verified token's issuer.
	Issuer string
	// TenantID and ObjectID are Entra ID's tenant and object id, set together and only on an Entra
	// sign-in whose token carries both; empty for every other issuer.
	TenantID, ObjectID string
	// Email is the token's email claim as sent, possibly empty.
	Email string
}

type LoginGrant struct {
	// Generation is the sink's durable erasure snapshot taken before exchange.
	Generation int64
	// RefreshToken is the durable half of the grant; empty if the provider
	// issued none (`offline_access` not asked for, or not granted).
	RefreshToken string
	// Scope is the GRANTED scope string, verbatim — may differ from what was
	// requested; only the sink knows what it was hoping for.
	Scope string
	// Expiry is the access token's expiry, as reported by the exchange.
	Expiry time.Time
}

type LoginGrantSink interface {
	// LoginGrantGeneration snapshots the sink before the exchange establishes
	// an owner. An error skips capture while the login proceeds.
	LoginGrantGeneration(ctx context.Context) (int64, error)
	// LoginScopes returns extra scopes to request, or nil. Called once per
	// authorization request.
	LoginScopes(ctx context.Context) []string
	// CaptureLoginGrant is offered the grant once login is APPROVED — past
	// every denial branch, so a refused login never yields a credential.
	// subject is the verified id_token subject the session is about to be
	// issued for.
	CaptureLoginGrant(ctx context.Context, subject string, grant LoginGrant)
}

type Match struct {
	// Value is the claim/email value that matched, exactly as carried. Empty for a default match.
	Value string `json:"value"`
	// Role is the tier this value maps to; UserType is set only when Role is the user tier.
	Role     string      `json:"role"`
	UserType string      `json:"user_type,omitempty"`
	Source   MatchSource `json:"source"`
}

type MatchSource string

type PersonKeying interface {
	// PrincipalFor is the principal s signs in as: the person keyed by exactly s.Issuer,
	// s.TenantID and s.ObjectID if there is one and s.Sub names no one yet, else s.Sub. refused is true when s.Sub itself
	// names a person keyed by an object id this token does not carry. An email never enters it.
	PrincipalFor(ctx context.Context, s Subject) (principal string, refused bool, err error)
	// Attached records an admitted sign-in that resolved to such a person, naming both parties.
	Attached(r *http.Request, s Subject, principal string)
}

type RevocationOrder interface {
	RevocationSeq(ctx context.Context) (int64, error)
	// IsSessionRevokedSeq is IsSessionRevoked for a credential that recorded seq (> 0): revoked when a
	// matching cut drew a greater sequence, with no comparison of clocks.
	IsSessionRevokedSeq(ctx context.Context, sub, email string, seq int64) (bool, error)
}

type RoleMapping struct {
	Value    string
	Role     string
	UserType string
}

type RoleMappingSource interface {
	// ListRoleMappings: a non-nil error DENIES the login rather than falling back to env-only,
	// which could WIDEN access under WARDYN_OIDC_DEFAULT_ROLE=admin.
	ListRoleMappings(ctx context.Context) ([]RoleMapping, error)
}

type Session struct {
	// V is the payload format version (SessionCodecVersion); any other value, including an absent
	// key, is not a session.
	V     int    `json:"v"`
	Sub   string `json:"sub"`
	Email string `json:"email"`
	// Name is the IdP's display-name claim, for the console header ONLY — gates nothing, keys
	// nothing, never logged. omitempty: an absent key falls back to email (fail-safe).
	Name string `json:"name,omitempty"`
	// ObjectID is the Entra object id (`oid`) the ID token named, stamped only on an Entra sign-in.
	// It is an identity INPUT (ObjectIDFromContext: an own Azure DevOps token is bound to the person
	// by it), never logged and never echoed. omitempty: a cookie without it is still a session and
	// the reader falls back to the person row or the email, so its absence is never a refusal.
	ObjectID string    `json:"oid,omitempty"`
	Role     string    `json:"role"`
	Expiry   time.Time `json:"expiry"`
	// UserType is stamped beside the tier at sign-in; everyone carries "standard" until the role
	// map names custom ones.
	UserType string `json:"ut"`
	// IssuedAt is when CallbackHandler minted this cookie, compared against a revoke cutoff by
	// IsSessionRevoked. omitempty: an absent key decodes to the zero time either way.
	IssuedAt time.Time `json:"iat,omitempty"`
	// AuthorityEpoch is the identity's authority epoch when this cookie was minted (Config.Identities).
	// A suspension raises the epoch, so a cookie minted before it is refused at its next request, and
	// stays refused after a reactivation. omitempty: a cookie without it is epoch 0.
	AuthorityEpoch int64 `json:"ae,omitempty"`
	// RevocationSeq is the revocation sequence read just before the sign-in's identity was admitted
	// (RevocationOrder). A revocation cut with a greater sequence ends this session, whatever the
	// clock says. omitempty: a cookie without it was issued by a replica that predates it and is
	// compared on IssuedAt, as before.
	RevocationSeq int64 `json:"rseq,omitempty"`
	// Groups is the LOGIN-TIME SNAPSHOT of the human's group identity (normalized union of the ID
	// token's "roles"/"groups" claims), against which a `group`-subject grant matches. Nothing
	// refreshes it — a group added at the IdP reaches Wardyn on the next login. NO omitempty,
	// deliberately: nil vs empty is the only signal for groups_snapshot_stale (nil = "never asked").
	Groups []string `json:"groups"`
	// GroupsTruncated reports Groups is a PARTIAL snapshot (hit maxSessionGroupsBytes). AUTHORIZATION
	// INPUT, not telemetry: without it the ceiling resolver would silently widen instead of refusing.
	GroupsTruncated bool `json:"groups_truncated,omitempty"`
	// MemberMode is the "view as member" flag. CLAMP INPUT only — Role stays the sign-in-derived
	// truth; the effective role is only ever LOWERED, keeping a cookie flag from being a privilege
	// primitive. omitempty: absent decodes to false (fail-safe); a rolling k8s upgrade can let an
	// old replica answer as admin for that window (documented ceiling, not proof of refusal).
	MemberMode bool `json:"mm,omitempty"`
	// MemberModeNoCredential is the mode's second posture: "view as a NEW member, not yet signed
	// in". Clamps the ROLE only — Sub (ownership, secrets, audit rows) stays the admin's own.
	MemberModeNoCredential bool `json:"mmnc,omitempty"`
	// UserViewType is the user type the user view looks through; the view always clamps the tier
	// to user regardless.
	UserViewType string `json:"uvt,omitempty"`
	// UserViewTypeName caches that type's display name from the instant the
	// view entered it (SetUserView). Meaningful only with MemberMode, same as
	// UserViewType. It exists ONLY so DropUserView can still name the type in
	// UserViewDroppedName after its row is gone — the row's deletion is WHY
	// the drop fires, so nothing can look the name up again at that point.
	UserViewTypeName string `json:"uvtn,omitempty"`
	// UserViewDropped names the type whose deletion turned the view off, so GET /me can say why
	// until the next switch clears it.
	UserViewDropped string `json:"uvd,omitempty"`
	// UserViewDroppedName is that same type's display name, copied from
	// UserViewTypeName the instant DropUserView fires, before it is cleared —
	// see UserViewTypeName's doc for why this is the only chance to record it.
	UserViewDroppedName string `json:"uvdn,omitempty"`
	// contains filtered or unexported fields
}

type SessionCutter interface {
	// CutSessions invalidates every current browser session for sub, matched against both identities.
	CutSessions(ctx context.Context, sub string) error
}

type SessionRevocations interface {
	// IsSessionRevoked reports whether a session for this human, issued at issuedAt, must be treated
	// as revoked, by a revoke targeting either identity or the reserved "" (global) sub, whichever
	// cutoff is later. A zero issuedAt is always revoked once any matching cutoff exists (fail
	// closed). Checked against BOTH identities since sub and email can diverge (Entra's opaque
	// per-app sub): sub compares exactly, email case-insensitively.
	//
	// ponytail: no in-process cache; add a short-TTL cache keyed on sub if latency shows up.
	IsSessionRevoked(ctx context.Context, sub, email string, issuedAt time.Time) (bool, error)
	// RevokeSub invalidates every CURRENT session for sub, matched against both identities.
	RevokeSub(ctx context.Context, sub string) error
	// RevokeAll invalidates every CURRENT session for every principal.
	RevokeAll(ctx context.Context) error
}

type SessionStatus int

type Subject struct {
	Issuer, Sub, TenantID, ObjectID string
}

type UserTypeSource interface {
	ListUserTypes(ctx context.Context) ([]types.UserType, error)
}