oidc

type Config struct {
	// IssuerURL is the OIDC issuer (typically the realm root for
	// Keycloak, the tenant URL for Auth0/Entra, etc.). Must be a
	// well-formed http(s) URL.
	//
	// http:// is permitted but production callers should reject it
	// unless an explicit opt-in flag is set; the package itself
	// allows http to support dev IdPs (Keycloak on localhost) but
	// emits no production guarantees over plaintext.
	IssuerURL string

	// ClientID is the OIDC client identifier registered with the IdP.
	ClientID string

	// ClientSecret is the OIDC client secret. Required for the
	// "confidential client" pattern; may be empty when UsePKCE is
	// true and the client is registered as public.
	ClientSecret string

	// RedirectURL is the absolute callback URL osctrl-api advertises
	// to the IdP. Must match exactly what's registered IdP-side; any
	// drift causes the IdP to reject the authorize request.
	//
	// Must be https in production. The package permits http for the
	// same reason as IssuerURL (dev IdPs) but callers are expected
	// to enforce https for non-dev configs.
	RedirectURL string

	// Scopes are passed verbatim to the authorize endpoint. If empty,
	// the provider injects ["openid", "profile", "email"]. If non-empty
	// without "openid", "openid" is prepended.
	Scopes []string

	// UsernameClaim is the OIDC claim used as the AdminUser.Username.
	// Values: "preferred_username" (default), "email", "sub". An
	// invalid value falls back to "sub" (always available, always
	// stable, but unfriendly to humans).
	UsernameClaim string

	// GroupsClaim is the OIDC claim consulted for group membership.
	// Default: "groups". Used only when RequiredGroups is non-empty.
	GroupsClaim string

	// RequiredGroups, if non-empty, gates HandleCallback so only users
	// whose group claim contains at least one of these strings can
	// authenticate. Empty list disables the gate entirely.
	RequiredGroups []string

	// JITProvision controls whether HandleCallback's downstream
	// caller (cmd/api/handlers/auth_callback.go) should auto-create a
	// new AdminUser on first login. The package itself never creates
	// users; this field is plumbed through ResolvedIdentity-adjacent
	// caller logic.
	//
	// We expose this on Config rather than on the resolved-identity
	// path so per-env policy can vary: some envs JIT, others don't.
	JITProvision bool

	// UsePKCE enables PKCE (RFC 7636) on the authorize + token
	// requests. Recommended for any deployment; mandatory for public
	// clients (those without a client secret).
	UsePKCE bool

	// LegacyPermissiveUsername disables the strict character-class
	// validation on the resolved username, passing the IdP-supplied
	// value (after TrimSpace) directly into ResolvedIdentity.
	// PreferredUsername.
	//
	// New callers MUST leave this false — strict validation is the
	// safe default and prevents audit-log poisoning (T26) and
	// injection-shaped usernames (T23) from reaching downstream
	// code.
	//
	// This flag exists ONLY to preserve backwards compatibility with
	// legacy osctrl-admin deployments where operators may have
	// pre-existing AdminUser rows whose usernames contain `.`, `@`,
	// or spaces (typical when an IdP emits `preferred_username` as
	// an email). Setting this true bypasses the regex but leaves
	// every other verification step intact (signature, iss, aud,
	// exp, nonce, groups).
	//
	// cmd/admin/oidc.go sets this true. cmd/api/handlers/oidc.go
	// MUST leave it false.
	LegacyPermissiveUsername bool
}

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