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.
	// OPTIONAL (C2): empty registers this as a PUBLIC client — PKCE S256 is
	// sent on every login regardless (LoginHandler), so a public client is
	// not weaker, just a different registration shape some IdPs require
	// (a SPA/native-app client type with no secret at all). See New's
	// AuthStyleInParams wiring for why omitting the field here is not
	// enough on its own.
	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 checks neither the email domain nor email_verified.
	// With a non-empty list, login is denied unless the IdP returns
	// email_verified=true and the email's domain matches.
	// 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

	// RoleMappings is the console-managed (Getting Started → People) role-
	// mapping store. When wired, CallbackHandler reads it once per login and
	// MERGES its rows with the chart's WARDYN_OIDC_ROLE_MAP (RoleMap, above) —
	// see mergeRoleMaps: the chart wins a duplicate key. A wired store's read
	// error DENIES the login exactly like the no-match case, via the distinct
	// authErrorRoleCheckUnavailable code — it never falls back to the
	// env-only map on error, since that could WIDEN access under
	// DefaultRole=admin. nil (the default) is env-only role derivation,
	// byte-identical to before this field existed — the same
	// optional-Config-field rule Revocations, above, follows.
	RoleMappings RoleMappingSource

	// 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 LoginGrant struct {
	// RefreshToken is the durable half of the grant. Empty means the provider
	// issued none — `offline_access` was not asked for, or not granted.
	RefreshToken string
	// Scope is the GRANTED scope string, verbatim and unparsed. It is not the
	// requested one: a provider may grant more or less than was asked for, and
	// only the sink knows which scopes it was hoping for.
	Scope string
	// Expiry is the access token's expiry, carried as the one freshness signal
	// the exchange actually reported.
	Expiry time.Time
}

type LoginGrantSink interface {
	// LoginScopes returns the extra scopes this login should request, or nil
	// for none. Called once per authorization request.
	LoginScopes(ctx context.Context) []string
	// CaptureLoginGrant is offered the grant once the login is APPROVED —
	// past every denial branch, so a refused login never yields a credential.
	// subject is the verified id_token subject, which is the principal 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 the ID token
	// or email carried it — matching itself is case-insensitive (deriveRole
	// lowers before lookup) but Value is not lowered, so a preview can show
	// the human the literal claim that hit. Empty for a MatchSourceDefaultRole
	// match, which was not driven by any claim value at all.
	Value  string      `json:"value"`
	Role   string      `json:"role"`
	Source MatchSource `json:"source"`
}

type MatchSource string

type RoleMapping struct {
	Value string
	Role  string
}

type RoleMappingSource interface {
	// ListRoleMappings returns every console-managed row. A non-nil error
	// DENIES the login in progress (CallbackHandler fails closed rather than
	// falling back to env-only, which could WIDEN access under
	// WARDYN_OIDC_DEFAULT_ROLE=admin) — this is not a best-effort read.
	ListRoleMappings(ctx context.Context) ([]RoleMapping, error)
}

type Session struct {
	// V is the payload format version (SessionCodecVersion), stamped by
	// encodeSession so no caller has to remember it. A payload carrying any
	// other value — a pre-0.7 cookie's absent key decodes to 0 — is not a
	// session.
	V     int    `json:"v"`
	Sub   string `json:"sub"`
	Email string `json:"email"`
	// Name is the IdP's display-name claim ("name"), carried for the console
	// header ONLY: it gates nothing, keys nothing, and is never logged (the
	// same hygiene Email already keeps). omitempty and no codec bump on
	// purpose — an absent key decodes to "" and the header falls back to the
	// email, which is fail-safe, so a pre-0.7.1 cookie stays a session.
	Name   string    `json:"name,omitempty"`
	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 — but it
	// does require the codec VERSION, and that is the fact that decides who is
	// signed out. `sess.V != SessionCodecVersion` (session_codec.go) is an exact
	// compare, and a pre-0.7 cookie carries no "v" key at all, so it decodes to
	// 0 and is refused outright: upgrading to 0.7 signs every SSO human out
	// ONCE, on their next request. This comment used to assert the opposite —
	// that an older cookie survived the upgrade and nobody was forced to sign in
	// again — and three shipped documents were written from it.
	//
	// So the nil-vs-empty signal above discriminates within ONE codec version:
	// a session this binary wrote either has groups or has `[]`. The pre-0.6
	// no-groups-key case it was designed for cannot reach the decoder any more —
	// keeping the distinction is what lets the NEXT codec-compatible change
	// carry a "we never asked" session without inventing a second flag.
	Groups []string `json:"groups"`
	// GroupsTruncated reports that Groups is a PARTIAL snapshot — sessionGroups
	// hit the maxSessionGroupsBytes cap and dropped the alphabetically-last
	// entries (PF-26).
	//
	// It is an AUTHORIZATION INPUT, not telemetry. A member in enough groups
	// loses the very group whose governance assignment walls them, and without
	// this bit the ceiling resolver would answer "no group matched" and hand
	// them the deployment ceiling — a silent widening with no refusal and no
	// audit line. internal/api therefore treats a truncated snapshot exactly as
	// it treats a missing one.
	//
	// omitempty is SAFE here only because SessionCodecVersion exists: false and
	// "key absent" mean the same thing within one codec version, and a
	// pre-0.7 cookie — where they would NOT mean the same thing — never
	// decodes at all.
	GroupsTruncated bool `json:"groups_truncated,omitempty"`
	// MemberMode (0.7.4, P2) is the "view as member" flag: this human asked to
	// be treated as a member for the rest of this session, so an admin can see
	// what a member sees without a second identity.
	//
	// It is a CLAMP INPUT and nothing else. Role above stays the
	// sign-in-derived truth — never rewritten — and contextWithPrincipal is the
	// single place the two meet: the EFFECTIVE role published on the context is
	// RoleMember while this is set. That split is what makes toggling OFF safe:
	// the stamped role is read back off the cookie rather than re-derived from
	// the Groups snapshot above, which is a SNAPSHOT and may be truncated, so a
	// re-derivation could answer "member" and strand an admin outside their own
	// deployment.
	//
	// It only ever LOWERS. No code path writes Role, and there is no value of
	// this field that widens anybody — which is the property that keeps a
	// session-cookie flag from being a privilege primitive.
	//
	// omitempty and NO codec bump, the same argument Name above makes: an absent
	// key decodes to false, which is the ordinary signed-in admin, and false is
	// the FAIL-SAFE answer here (unlike GroupsTruncated, where false is the
	// fail-open one). The cost is the rolling-upgrade window: during a k8s
	// rollout a 0.7.3 replica ignores "mm" and answers as admin. A bump would
	// close that window by 401-ing every live cookie mid-rollout, which is
	// worse — so docs/OPERATIONS.md publishes the window as a ceiling and
	// phrases the mode as "see what a member sees", never as proof that a
	// member is refused.
	MemberMode bool `json:"mm,omitempty"`
	// MemberModeNoCredential (0.7.5, field report finding 3) is the SECOND
	// posture of the same mode: "view as a NEW member — one who has not signed
	// in yet". Meaningful only with MemberMode; SetMemberMode writes it as
	// `on && noCredential`, so turning the mode off clears it by construction
	// and it can never be set on its own.
	//
	// MemberMode alone cannot show that state. It clamps the effective ROLE and
	// deliberately leaves Sub — ownership, the secret namespace, every audit row
	// — the admin's own, so an admin who has completed their own AWS SSO sign-in
	// keeps reading their own live credential while "viewing as member", which
	// is the one state every new member on a per_user deployment is NOT in.
	// Clamping Sub instead would have rewritten identity, which is the property
	// the whole mode rests on not doing.
	//
	// A SEPARATE BOOL, not an enum on "mm": a 0.7.4 replica decodes "mm" as a
	// bool, so a non-bool value there would fail json.Unmarshal in decodeSession
	// and 401 a live cookie mid-rollout. An unknown omitempty key is simply
	// ignored (the codec sets no DisallowUnknownFields), so no codec bump.
	//
	// The rolling-upgrade window is the same one MemberMode publishes and it
	// fails SAFE in the same direction: an older replica ignores this key and
	// shows the admin their own credential — the 0.7.4 behaviour, never a
	// widening. docs/OPERATIONS.md publishes it as a ceiling.
	MemberModeNoCredential bool `json:"mmnc,omitempty"`
}

type SessionRevocations interface {
	// IsSessionRevoked reports whether a session for this human, issued at
	// issuedAt, must be treated as revoked — because of a revoke targeting
	// EITHER of their identities, 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.
	//
	// BOTH IDENTITIES, for the reason every other user-addressing surface in
	// the product already takes: an admin naming a human "shouldn't have to
	// guess which the IdP made authoritative" (docs/OPERATIONS.md on a
	// subject_type=user capability grant, which matches the sub OR the email;
	// capabilitySubjects in internal/api offers both the same way). Revocation
	// was the one such surface keyed on sub ALONE, and on any IdP where the two
	// differ — Entra, where sub is an opaque per-app identifier — a revoke
	// naming the email stamped a cutoff that matched nobody: 204, an audited
	// success, and a compromised human still signed in. sub is compared
	// EXACTLY (an OIDC sub is opaque and case-sensitive); email is compared
	// case-insensitively, since that is how humans type one.
	//
	// ponytail: Middleware calls this on every authenticated request with no
	// in-process cache — one extra lookup per request against the store
	// wardynd already requires (Postgres), over a table holding one row per
	// revoked principal plus the global one. 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, email string, issuedAt time.Time) (bool, error)
	// RevokeSub invalidates every CURRENT session for sub, effective now —
	// a targeted "log this one person out everywhere". sub is whichever
	// identity the caller named; IsSessionRevoked matches it against both.
	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
}