authn

type Code string

type Config struct {
	// Issuer is the expected iss claim value. When JWKSURL is empty it is
	// also the base for OIDC discovery ({Issuer}/.well-known/openid-configuration).
	// Must be an https URI unless InsecureAllowHTTP is set.
	//
	// At least one of Issuer or JWKSURL is required. Leaving Issuer EMPTY
	// (only legal alongside an explicit JWKSURL) DISABLES iss verification
	// entirely: any issuer that can present a key from the configured JWKS is
	// accepted. Only do this when the JWKS endpoint itself is the trust
	// boundary.
	Issuer string

	// Audiences lists acceptable aud claim values; a token is accepted when
	// ANY of its aud values matches ANY entry here.
	//
	// Each entry is compared byte-exact against the token's aud values and is
	// validated only as a bounded, control-character-free string: RFC 7519
	// §4.1.3 types aud as StringOrURI, so bare identifiers (an OAuth
	// client_id) and opaque GUIDs (Entra ID) are conformant and accepted.
	//
	// Required and non-empty unless AllowAnyAudience is set.
	Audiences []string

	// AllowAnyAudience disables audience verification. It exists so a
	// deployment with no audience policy can be expressed explicitly rather
	// than by leaving Audiences unset, since a silently absent audience check
	// is how confused-deputy bugs reach production: any token the issuer minted
	// for ANY relying party is accepted by this resource server.
	//
	// Setting it together with a non-empty Audiences is an error, so the two
	// cannot silently disagree.
	AllowAnyAudience bool

	// JWKSURL, when set, points directly at the JWKS endpoint and skips OIDC
	// discovery. Optional. Must be an https URI unless InsecureAllowHTTP is
	// set.
	JWKSURL string

	// Leeway is the clock-skew tolerance applied to exp/nbf/iat. Zero uses
	// the default of 60s; negative is an error; values above 2m are an
	// error.
	Leeway time.Duration

	// DisableLeeway sets the clock-skew tolerance to zero, so exp is enforced
	// exactly. It exists because Leeway == 0 means "use the 60s default", which
	// left no way to ask for no tolerance at all. Setting it together with a
	// non-zero Leeway is an error, so the two cannot silently disagree.
	//
	// IMPORTANT for anyone setting this for parity with a validator that has no
	// leeway: it applies to nbf and iat as well as exp, and this package checks
	// iat (a token issued in the future beyond tolerance is rejected) where many
	// validators do not check it at all. So NEITHER setting is exact parity with
	// such a validator:
	//
	//   - set     → exp and nbf match exactly, but iat becomes zero-tolerance
	//               where the other validator ignores iat entirely, so IdP clock
	//               skew that was previously invisible starts failing.
	//   - unset   → 60s of slack on exp that the other validator does not give.
	//
	// Pick based on which mismatch your deployment can absorb. There is
	// deliberately no separate iat opt-out: adding one before a concrete
	// deployment needs it would be a speculative knob.
	DisableLeeway bool

	// MaxJWKSStaleness bounds how long cached JWKS key material stays trusted
	// without a confirmed successful fetch. Negative is an error.
	//
	// Zero DISABLES the bound, and is the default. The bound exists because the
	// cache keeps serving its last good key set after every failed refresh, so a
	// key revoked at the IdP stays trusted for as long as the endpoint is
	// unreachable — the trust window equals the outage length.
	//
	// Enabling it trades availability for that bound: once exceeded, validation
	// fails with CodeUnavailable/ReasonKeysStale, so a prolonged IdP outage
	// becomes an authentication outage instead of an invisible one. Pick a value
	// that reflects how long you are willing to honour a revoked key; hours
	// rather than minutes is usually the right order of magnitude.
	//
	// Freshness is self-correcting rather than schedule-based: when the bound is
	// exceeded the validator attempts a refresh before rejecting anything, so a
	// healthy endpoint never trips it regardless of when the background refresh
	// last ran. It applies only to JWKS material — keys from a KeyProvider are
	// resolved in-process and are never considered stale.
	MaxJWKSStaleness time.Duration

	// AcceptedTokenTypes, when non-empty, requires the token's `typ` header to
	// match one of these media types. Comparison is case-insensitive and an
	// `application/` prefix is optional on both sides (RFC 7515 §4.1.9), so
	// "at+jwt" matches a token carrying "application/at+JWT".
	//
	// Empty (the default) accepts any `typ`, including none. It cannot default
	// to requiring RFC 9068's "at+jwt": that is a SHOULD, and many IdPs emit
	// "JWT" or omit the header entirely, so a default would reject conformant
	// tokens.
	//
	// This guards against ID-token substitution — an ID token sharing the
	// issuer, audience, subject and expiry of an access token. Note the AUDIENCE
	// check is the primary defence there, since an ID token's aud is the
	// client_id rather than the resource: this matters most when
	// AllowAnyAudience is set, or when a deployment uses its client_id as the
	// resource audience, because in those cases the audience check cannot tell
	// the two kinds of token apart.
	AcceptedTokenTypes []string

	// MaxTokenLifetime rejects tokens whose exp-iat span exceeds it, when both
	// claims are present. Negative is an error.
	//
	// Zero DISABLES the check, and is the default: a resource server that
	// accepts long-lived tokens today (service-account credentials commonly
	// outlive a day) must not start rejecting them merely by adopting this
	// package. Set it explicitly to opt into a lifetime bound.
	MaxTokenLifetime time.Duration

	// HTTPClient is used for discovery and JWKS fetches. Leave it nil unless you
	// need something the default cannot express: the default is built by
	// toolhive-core's networking package and is secure by default (private-IP
	// dial guard, 15s timeout, redirects refused, 1 MiB body cap).
	//
	// IMPORTANT — a supplied client OPTS OUT of the address-level SSRF guard.
	// That guard lives in the transport's DialContext, which this package cannot
	// retrofit onto a client it did not build; AllowPrivateIP and CACertPath are
	// likewise ignored. Build your client with
	// networking.NewHttpClientBuilder() (or install
	// networking.NewPrivateIPBlockingDialContext yourself) or you will have a
	// weaker configuration than the default.
	//
	// What IS still enforced for a supplied client: the 1 MiB response-body cap
	// (its Transport is wrapped), plus redirect refusal and the 15s timeout when
	// the caller left CheckRedirect / Timeout unset — so a bare &http.Client{}
	// cannot silently drop them. Explicit caller values are preserved.
	//
	// To attach a bearer token to the OUTBOUND JWKS/discovery request (an IdP
	// whose JWKS endpoint is itself gated), supply a client whose Transport
	// injects the Authorization header. That RoundTripper must be the innermost
	// one — this package wraps whatever it is given in its body-capping
	// transport, so set it as your client's Transport and let the wrapping
	// happen around it.
	//
	// If your IdP legitimately redirects its discovery or JWKS endpoint, set
	// JWKSURL to the final target rather than relaxing the redirect policy.
	HTTPClient *http.Client

	// InsecureAllowHTTP permits http:// Issuer and JWKSURL values. It exists
	// for development and test environments only; never set it in
	// production.
	InsecureAllowHTTP bool

	// AllowPrivateIP permits discovery and JWKS fetches to reach private,
	// loopback, and link-local addresses. It defaults to FALSE, which is what
	// blocks a jwks_uri resolving to cloud instance metadata
	// (169.254.169.254) or an in-cluster address.
	//
	// The check runs on the resolved address at dial time, so it also defends
	// against DNS rebinding and re-applies per redirect hop. Set it only for an
	// issuer that legitimately lives on a private network — an in-cluster OIDC
	// provider, or a test server on localhost.
	//
	// It applies ONLY to the default client. A caller-supplied HTTPClient brings
	// its own dial policy; see that field.
	AllowPrivateIP bool

	// CACertPath optionally points at a PEM CA bundle used to verify the
	// discovery and JWKS endpoints, for an issuer fronted by a private CA.
	//
	// It applies ONLY to the default client, for the same reason as
	// AllowPrivateIP.
	CACertPath string

	// AuthTokenFile optionally points at a file containing a bearer token to
	// attach to the OUTBOUND discovery and JWKS requests, for an IdP whose own
	// endpoints are gated behind auth (mirrors ToolHive's
	// --jwks-auth-token-file). The networking package re-reads the file per
	// request, so a rotated token is picked up without restarting the
	// validator.
	//
	// It applies ONLY to the default client, for the same reason as
	// AllowPrivateIP and CACertPath: it is implemented by networking's HTTP
	// client builder, which cannot be retrofitted onto a caller-supplied
	// HTTPClient.
	AuthTokenFile string

	// KeyProvider optionally supplies verification keys in-process, for an
	// embedded issuer. It is consulted BEFORE the JWKS cache on every
	// validation.
	//
	// A provider MISS falls through to the JWKS when one is configured. A
	// provider REJECTION does not: if the provider offers a key for the token's
	// kid but that key is unusable — a sub-2048-bit modulus, a declared alg that
	// disagrees, a malformed key — validation fails immediately with
	// ReasonKeyUnsupported and the JWKS is never consulted. An unusable key is a
	// permanent condition, so reporting it beats masking it behind a fallback
	// that would end up reporting an unknown kid instead.
	//
	// The practical effect is that an unusable provider key shadows a usable
	// JWKS key under the same kid. That is accepted: in the only topology that
	// has a provider, the provider and the JWKS are the same key source, so the
	// two disagreeing means something is wrong that a silent fallback would
	// hide.
	//
	// Setting it also relaxes construction, because an embedded issuer's JWKS
	// endpoint is characteristically not reachable at the moment the Validator
	// is built:
	//
	//   - OIDC discovery failure becomes non-fatal.
	//   - The first JWKS fetch is no longer required to succeed; key material
	//     is fetched lazily by the background refresh instead.
	//
	// Until that first fetch lands, a token whose kid the provider does not
	// offer fails with CodeUnavailable/ReasonKeysUnavailable rather than being
	// rejected as invalid — the verifier could not make a determination.
	//
	// With no KeyProvider, construction stays fail-closed: discovery and the
	// first JWKS fetch must both succeed or NewValidator returns an error.
	KeyProvider KeyProvider
}

type Error struct {
	// Code is the coarse, client-safe OAuth2 error code.
	Code Code
	// Reason is the finer-grained, client-safe failure cause.
	Reason Reason
	// contains filtered or unexported fields
}

type KeyProvider interface {
	// PublicKeys returns the currently valid verification keys. It is called
	// per validation, so an implementation that computes or reads keys should
	// cache them itself; this package deliberately does not, so that key
	// rotation inside the provider takes effect immediately.
	PublicKeys(ctx context.Context) ([]PublicKey, error)
}

type Principal struct {
	// Issuer is the verified `iss` claim.
	Issuer string
	// Subject is the verified `sub` claim, guaranteed non-empty.
	Subject string
	// Name is the `name` claim, may be empty.
	Name string
	// Claims is the full verified claim set. It is the raw credential (the
	// serialized token) that is deliberately absent, never claim data. Claims
	// beyond iss/sub/name — e.g. the `email` claim ToolHive's claimsToIdentity
	// uses for its display-name fallback, or an IdP-specific claim like Okta's
	// `tsid` — are read here by consumers; they are intentionally NOT
	// first-class fields, since the struct carries only what every resource
	// server needs.
	Claims map[string]any
}

type PublicKey struct {
	// KeyID is the JWK kid this key answers to. It may be empty, in which case
	// the key is considered a candidate for any token — including one that
	// carries a kid, since an embedded issuer with a single key commonly omits
	// it on one side or the other.
	KeyID string

	// Alg optionally restricts the key to a single JWA algorithm (e.g.
	// "RS256"). When empty the key is eligible for any allow-listed algorithm
	// its type supports, subject to the same kty/curve backstop applied to
	// JWKS keys.
	Alg string

	// Key is the public key itself: *rsa.PublicKey or *ecdsa.PublicKey. Any
	// other type is rejected, since the algorithm allow-list admits only RSA
	// and ECDSA families.
	Key crypto.PublicKey
}

type Reason string

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