oidc

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

type Config struct {
	// IssuerURL is the OIDC provider's PUBLIC issuer — the URL the user's
	// browser is redirected to and the value of the "iss" claim in ID tokens
	// (e.g. http://localhost:5556). Must match the IdP's configured issuer.
	IssuerURL string
	// InternalIssuerURL, when set, is the address at which wardynd itself
	// reaches the IdP for server-side calls (discovery, token exchange, JWKS)
	// — e.g. http://dex:5556 on a Docker network. It solves the split-horizon
	// problem where the browser and the control plane reach the IdP at
	// different hostnames: the browser-facing endpoints keep the public
	// IssuerURL, while wardynd's HTTP client transparently rewrites the public
	// authority to this internal one. Empty => IssuerURL is used for both.
	InternalIssuerURL string
	// ClientID is the OAuth2 client identifier registered with the IdP.
	ClientID string
	// ClientSecret is the OAuth2 client secret. Never log this value.
	ClientSecret string
	// RedirectURL is the callback URL registered with the IdP.
	// Must be <wardynd-base>/auth/callback.
	RedirectURL string
	// AllowedEmailDomains, when non-empty, restricts login to email addresses
	// whose domain — the part after the last '@' — exactly equals one of the
	// listed values, case-insensitively. Matching is exact, not suffix-based:
	// listing "example.com" does NOT admit "eng.example.com", which must be
	// listed separately; wildcards are not supported.
	// An empty list allows any verified email. Fail closed: if the IdP does not
	// return a verified email and AllowedEmailDomains is non-empty, login is denied.
	// Entra ID tokens typically OMIT email_verified entirely, so this option
	// fail-closes on every login against an Entra tenant; prefer Entra App Roles
	// (WARDYN_OIDC_ROLE_MAP against the "roles" claim, below) plus the app
	// registration's "assignment required" setting there instead.
	AllowedEmailDomains []string
	// RoleMap maps a case-insensitive claim/email value — an Entra App Role
	// from the ID token's "roles" claim, a "groups" claim entry, or the user's
	// email — to a Wardyn role, RoleAdmin or RoleMember. Parsed from
	// WARDYN_OIDC_ROLE_MAP by ParseRoleMap ("value=role" CSV pairs, e.g.
	// "Wardyn.Admin=admin,eng-team=member,alice@corp.com=admin"); ParseRoleMap
	// is also where a bad role value is rejected, so every entry here is
	// already valid. Precedence when more than one entry matches: ANY match
	// resolving to RoleAdmin wins over one resolving to RoleMember, regardless
	// of which claim produced it (see deriveRole). Empty (the default) disables
	// role derivation entirely: every signed-in human keeps today's pre-0.5
	// behavior (RoleAdmin) — opt-in and upgrade-safe.
	RoleMap map[string]string
	// DefaultRole is the role a signed-in human gets when RoleMap is non-empty
	// but nothing in their roles/groups/email matched an entry: RoleAdmin,
	// RoleMember, or "" (the default) to DENY the login instead, with a message
	// telling them to ask their operator for a WARDYN_OIDC_ROLE_MAP entry.
	// Ignored when RoleMap is empty (see RoleMap's own empty-map behavior).
	DefaultRole string
	// LegacyAdminEmails is WARDYN_OIDC_OPERATOR_EMAILS — the operator allowlist,
	// now the SOLE source of the admin tier (internal/api's isOperator reads the
	// derived role, not this list directly). An email on it always derives
	// RoleAdmin, same top precedence as any RoleMap admin match, and with no
	// RoleMap at all the list alone splits admin from member — so a 0.4.5
	// deployment keeps its operators as admins and everyone else as members
	// (viewers) with zero re-configuration, with or without a role map.
	LegacyAdminEmails []string
	// SecureCookies, when true, marks every cookie Wardyn issues (the session
	// cookie and the one-time login state/nonce/pkce cookies) with the Secure
	// attribute, so browsers only send them over HTTPS. It MUST be true exactly
	// when the connection is TLS-protected — either wardynd serves TLS directly
	// or TLS terminates at an upstream reverse proxy. CRITICAL: Secure cookies
	// are never sent over plain HTTP, so leaving this false (the default) is
	// required for plain-HTTP demo deployments — otherwise login silently breaks.
	SecureCookies bool
	// Revocations is the pg-backed revoke-a-human-now lever (D16). Sessions
	// are stateless signed cookies with no server-side session table (see the
	// package doc's "Session storage" section), so there is nothing to delete
	// on revoke — instead Revocations tracks a per-principal (and a global)
	// CUTOFF time, and Middleware treats any session whose IssuedAt is
	// at-or-before the applicable cutoff as invalid. nil (the default) means
	// revocation is never checked — unset changes nothing, same as every
	// other optional Config field.
	Revocations SessionRevocations

	// OnLogin, when set, is called synchronously from CallbackHandler after a
	// login is APPROVED (role derived, session about to be issued) with the
	// ID token's sub and the freshly-derived role. It exists for exactly one
	// caller today — internal/api wires it to refresh ssh_public_keys.role /
	// role_checked_at (migration 0046) for every key this principal owns, the
	// bounded-stale re-check the SSH gateway's admin override reads — but this
	// package stays store-agnostic: it knows nothing about SSH keys, only that
	// a login happened. A failure inside OnLogin must never fail the login
	// itself (the integrator is expected to log-and-continue, not panic);
	// CallbackHandler does not inspect its return because it has none. nil
	// (the default) is a plain no-op, so every existing caller is unaffected.
	OnLogin func(ctx context.Context, sub, role string)
}

type Session struct {
	Sub    string    `json:"sub"`
	Email  string    `json:"email"`
	Role   string    `json:"role"`
	Expiry time.Time `json:"expiry"`
	// IssuedAt (D16) is when CallbackHandler minted this cookie — the value
	// SessionRevocations.IsSessionRevoked compares against a revoke cutoff.
	// omitempty, unlike Groups below: an absent key decodes to the zero
	// time either way (a pre-D16 cookie or a same-version cookie that
	// happened to omit it are indistinguishable, and both SHOULD read as
	// "issued at the beginning of time" — see IsSessionRevoked's doc — so
	// there is no second state worth spending cookie bytes to keep apart).
	IssuedAt time.Time `json:"iat,omitempty"`
	// Groups is the LOGIN-TIME SNAPSHOT of the human's group identity: the
	// normalized union of the ID token's "roles" and "groups" claims (see
	// sessionGroups). It is what a `group`-subject capability grant matches
	// against — folding Entra App Roles in for free, since those arrive on
	// "roles" and are the claim an Entra admin can actually assign.
	//
	// It is a SNAPSHOT and nothing refreshes it: a group added at the IdP
	// reaches Wardyn on the human's next login, and that ceiling is published
	// rather than hidden (grants themselves resolve per request from the DB, so
	// only MEMBERSHIP is stale, never the grant list).
	//
	// NO omitempty, deliberately. nil and empty must stay distinguishable
	// across the cookie round trip: a PRE-0.6 cookie has no groups key at all
	// and decodes to nil ("we never asked"), while a 0.6 login with no groups
	// encodes `[]` and decodes to an empty non-nil slice ("we asked, there were
	// none"). That is the ONLY signal for groups_snapshot_stale — with
	// omitempty both cases would encode identically and a member holding a
	// pre-upgrade cookie would be told their group grants simply do not apply.
	// The cost is 12 bytes of cookie.
	//
	// decodeSession is deliberately NOT widened to require this field: a
	// pre-0.6 cookie stays VALID and nobody is forced to re-login by an
	// upgrade.
	Groups []string `json:"groups"`
}

type SessionRevocations interface {
	// IsSessionRevoked reports whether a session for sub, issued at issuedAt,
	// must be treated as revoked — because of a revoke targeting exactly sub,
	// or the reserved "" (global revoke-all) sub, whichever cutoff is later.
	// issuedAt.IsZero() (a pre-D16 cookie with no iat) is always revoked once
	// ANY matching cutoff exists: an old session predating this feature has
	// no reliable issued-at to compare, so it fails closed the moment revoke
	// is used for the first time against it, rather than staying immune.
	//
	// ponytail: Middleware calls this on every authenticated request with no
	// in-process cache — one extra indexed point-lookup per request against
	// the store wardynd already requires (Postgres). Add a short-TTL
	// in-memory cache keyed on sub if that round trip ever shows up in
	// latency; a POC-scale deployment's request volume doesn't justify one
	// yet, and a cache is one more place revocation could go stale.
	IsSessionRevoked(ctx context.Context, sub string, issuedAt time.Time) (bool, error)
	// RevokeSub invalidates every CURRENT session for sub, effective now —
	// a targeted "log this one person out everywhere".
	RevokeSub(ctx context.Context, sub string) error
	// RevokeAll invalidates every CURRENT session for every principal,
	// effective now — the incident-response "log everyone out" lever.
	RevokeAll(ctx context.Context) error
}