auth

type Provider interface {
	// Type returns the discriminator that identifies the protocol.
	// Must match one of the Type* constants above.
	Type() string

	// LoginURL builds the URL the user's browser is redirected to in
	// order to start the authentication flow. The State is opaque to
	// the caller; the caller is responsible for transporting it back
	// to HandleCallback via a state cookie (see pkg/auth/state.go).
	//
	// Implementations MUST embed unguessable nonces / verifiers in the
	// returned URL and the State so the callback can detect CSRF and
	// replay attempts. See threat IDs T6, T7, T9 in the spec.
	LoginURL(ctx context.Context, state State) (string, error)

	// HandleCallback consumes the provider's callback request,
	// validates everything (signature, issuer, audience, expiry,
	// nonce, PKCE verifier as applicable) and returns a
	// ResolvedIdentity describing the authenticated user.
	//
	// The State argument is the State that the caller previously
	// transported via cookie. Implementations MUST treat any
	// mismatch as a fatal authentication failure and MUST NOT
	// continue to user resolution. See threat IDs T6, T18.
	//
	// Implementations MUST NOT return raw tokens, claims, or
	// provider error bodies in the error message; those go to
	// server-side structured logging only. See spec hardening rule
	// "no raw token logging".
	HandleCallback(ctx context.Context, r *http.Request, state State) (ResolvedIdentity, error)
}

type ResolvedIdentity struct {
	// Subject is the stable, opaque identifier issued by the IdP
	// (typically the `sub` claim in OIDC). Never an email, never a
	// preferred name — those can change. Callers that need to
	// preserve identity across renames MUST use Subject.
	Subject string

	// PreferredUsername is what the user sees and types. Defaults to
	// the OIDC `preferred_username` claim; configurable per-provider
	// to fall back to email or sub. Used as the AdminUser.Username
	// after passing validation.
	PreferredUsername string

	// Email is informational; do NOT use it as a stable identifier
	// (mutable in most IdPs; spoofable in poorly-configured ones —
	// see threat T24).
	Email string

	// Name is the human display name (OIDC `name` claim) or a
	// concatenation of given+family if absent.
	Name string

	// Groups carries the user's IdP group memberships (after the
	// optional protocol-mapper claim shaping). v1 uses this only for
	// the RequiredGroups gate; future versions may map groups to
	// osctrl roles. See spec §"What this design does NOT do".
	Groups []string

	// Raw exposes the underlying provider-specific claim set for
	// debugging and future feature work. Callers MUST NOT read Raw
	// to bypass any of the typed fields above; that would defeat the
	// validation layer. Always nil for SAML when it lands; OIDC sets
	// it after id_token verification.
	Raw map[string]any

	// IDToken is the raw, signed id_token bytes the IdP returned.
	// Already verified at this point (sig + iss + aud + exp + nonce
	// checks all passed). The caller's only legitimate use is
	// id_token_hint on RP-initiated logout — DO NOT use it as an
	// authentication credential anywhere else. Empty for SAML.
	IDToken string
}

type State struct {
	// EnvUUID locks this State to a specific osctrl environment.
	// Callbacks for env A using state issued for env B MUST be
	// rejected — see threat T18 (cross-env auth confusion).
	EnvUUID string

	// Nonce is a 256-bit cryptorandom value. For OIDC, this is
	// embedded in the authorize URL via the `nonce` parameter and
	// must match the `nonce` claim on the returned id_token. SAML
	// does not use Nonce (it has no equivalent protocol slot).
	//
	// Defense-in-depth invariant: Nonce and OAuthState MUST be
	// independent random values, NOT the same value. Earlier
	// versions reused a single random value for both slots; a
	// pentest finding (May 2026) called out that a leak of either
	// — e.g. `state` ending up in a Referer log — would
	// simultaneously compromise the other. Two independent values
	// mean two independent leak surfaces.
	Nonce string

	// OAuthState is the OAuth2 / SAML RelayState parameter. For
	// OIDC, this is what the callback's `state` query param must
	// echo (CSRF defense — threat T6). For SAML, this is the
	// RelayState the ACS POST must echo (threat S10). Always a
	// 256-bit cryptorandom value, INDEPENDENT of Nonce.
	OAuthState string

	// Verifier is the PKCE code_verifier (RFC 7636) when the
	// provider has PKCE enabled. Empty otherwise. The callback
	// presents this to the token endpoint along with the code; the
	// IdP recomputes the challenge and compares.
	//
	// Empty Verifier with a PKCE-enabled provider MUST cause
	// HandleCallback to reject — see threat T10.
	Verifier string

	// SAMLRequestID is the AuthnRequest ID minted at LoginURL time,
	// round-tripped through the state cookie, and passed back to
	// ParseResponse as the expected InResponseTo. Closes threat S7
	// (InResponseTo replay/forgery) — without it, crewjam either
	// rejects every response (when nil is passed) or accepts any
	// InResponseTo (when an empty slice is passed). Always empty
	// for OIDC; populated for SAML SP-initiated flows.
	SAMLRequestID string
}