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

	// OnLogin, when set, is called synchronously after an APPROVED login with the derived role/user
	// type and group snapshot. A failure inside it must never fail the login; nil is a no-op.
	OnLogin func(ctx context.Context, sub, role, userType string, groups []string, groupsTruncated bool)
}

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 LoginGrant struct {
	// 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 {
	// 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 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"`
	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"`
	// 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 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 Subject struct {
	Issuer, Sub, TenantID, ObjectID string
}

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