upstreamauth

type Authenticator interface {
	Apply(req *http.Request) error
}

type Config struct {
	// Kind is the connoauth connection kind ("api", "graphql"). It
	// keys the persisted OAuth token row and identifies the connection
	// in connoauth's deduplicated configuration warnings, so two kinds
	// with a same-named connection do not share a token.
	Kind string
	// ErrPrefix names the calling kind in every error this package
	// produces. Empty falls back to the package name. Set it: an
	// operator whose connection save is refused should read
	// "apigateway: credential is required ...", not the name of an
	// internal seam they cannot see in any configuration file.
	ErrPrefix string
	// ConnectionName is the audit-visible connection identifier. Used
	// as the OAuth token-row key for the authorization_code grant.
	// Kinds populate it from the toolkit instance name after Parse.
	ConnectionName string

	// AuthMode selects the credential scheme: one of the AuthMode*
	// constants.
	AuthMode string
	// Credential is the bearer token or API key. Ignored when AuthMode
	// is "none". Encrypted at rest via the platform's FieldEncryptor.
	Credential string
	// CredentialPlacement is "header" (default) or "query" — only consulted
	// when AuthMode is "api_key".
	CredentialPlacement string
	// APIKeyHeader is the header name to set when CredentialPlacement is
	// "header". Defaults to DefaultAPIKeyHeader.
	APIKeyHeader string
	// APIKeyParam is the query parameter name when CredentialPlacement is
	// "query". No default — required when placement is "query".
	APIKeyParam string
	// Username is the userid for HTTP Basic auth (RFC 7617). Required
	// when AuthMode is "basic". Ignored otherwise. Not a secret on its
	// own (per RFC 7617 §2 the userid is sent in clear after base64
	// decoding regardless), so it is not encrypted at rest.
	Username string
	// Password is the password for HTTP Basic auth. May be empty: some
	// legacy APIs accept a bearer token in the userid slot with an empty
	// password (the "token:" pattern). Encrypted at rest via the
	// platform's FieldEncryptor.
	Password string
	// OAuth2 carries the OAuth 2.1 parameters used when AuthMode is
	// AuthModeOAuth. Empty for non-OAuth modes.
	OAuth2 OAuth2Config
	// SignedJWT carries the assertion parameters used when AuthMode is
	// AuthModeSignedJWT. Empty for every other mode.
	SignedJWT SignedJWTConfig

	// ConnectTimeout caps the dial step (TCP + TLS handshake) on each
	// invocation.
	ConnectTimeout time.Duration
	// CallTimeout caps the total per-invocation time.
	CallTimeout time.Duration
	// MaxResponseBytes is the upstream read cap: the most a kind reads
	// of any one response. Defaults to DefaultMaxResponseBytes.
	MaxResponseBytes int64
	// StaticHeaders are operator-configured headers attached to every
	// outbound request, in addition to whatever AuthMode contributes.
	// Operator-supplied; the model never sets or overrides these.
	// Values are encrypted at rest.
	StaticHeaders map[string]string

	// MTLSClientCertPEM is the PEM-encoded X.509 client certificate
	// chain (leaf first) presented during the TLS handshake. Public
	// material, stored in plain text. Required alongside
	// MTLSClientKeyPEM and optional otherwise; an ambiguous config
	// (one set, the other empty) is refused.
	MTLSClientCertPEM string
	// MTLSClientKeyPEM is the PEM-encoded private key matching
	// MTLSClientCertPEM. Encrypted at rest via the platform's
	// FieldEncryptor. Validation runs the cert + key through
	// tls.X509KeyPair so a key that does not match the cert is
	// rejected at write time, not on first outbound call.
	MTLSClientKeyPEM string
	// TLSCABundlePEM is an optional PEM bundle of root CA
	// certificates added to the TLS trust store for outbound
	// requests on this connection. Appended to the system root
	// pool, not substituted: public CAs remain trusted. Required
	// when the upstream's TLS certificate is signed by a private
	// CA (cluster-internal CA, mesh CA, corporate root) that the
	// host's default cert store does not carry.
	TLSCABundlePEM string

	// IdentityPassthrough forwards the acting caller's inbound bearer
	// token as the outbound Authorization header, instead of applying
	// this connection's shared credential. When set, AuthMode must be
	// "none": the shared-credential Authenticator is skipped, and two
	// sources for one header would be ambiguous. Reading the caller's
	// token off the request context is the kind's job, not this
	// package's — only the invariant lives here.
	IdentityPassthrough bool
}

type OAuth2Config struct {
	// Grant is the OAuth flow, populated by Parse from the canonical
	// oauth_grant (or derived from a legacy auth_mode). One of
	// connoauth.GrantClientCredentials or
	// connoauth.GrantAuthorizationCode. The authenticator and
	// validation dispatch on this rather than on the auth_mode string.
	Grant string
	// TokenURL is the upstream's token endpoint. Required.
	TokenURL string
	// ClientID is the platform's registered client id. Required.
	ClientID string
	// ClientSecret is the platform's registered client secret.
	// Required. Encrypted at rest via the platform's FieldEncryptor.
	ClientSecret string
	// Scopes is an optional list of OAuth scopes to request.
	Scopes []string
	// EndpointAuthStyle controls how the client credentials are
	// transmitted at token-fetch time. "header" (default) sends
	// them as HTTP Basic auth on the token request; "params"
	// sends them as POST body parameters. Some IdPs require one
	// or the other; "header" is the OAuth 2.1 default.
	EndpointAuthStyle string
	// AuthorizationURL is the upstream's authorization endpoint.
	// Required only for the authorization_code grant — that's
	// where the platform redirects the admin's browser to start
	// the flow.
	AuthorizationURL string
	// Prompt is an optional OIDC prompt parameter (RFC OIDC
	// §3.1.2.1). Common values: "login" (force credential prompt),
	// "consent" (force consent screen), "select_account",
	// "none" (silent auth). Empty by default — the IdP decides.
	// Operators of strict OIDC realms (Keycloak, Auth0, Okta)
	// typically set this to "login" so admin Reconnect actions
	// always re-prompt the user. Pure-OAuth (non-OIDC) providers
	// often reject unknown parameters with invalid_request, so
	// leave empty for those.
	Prompt string
}

type SignedJWTConfig struct {
	// Algorithm is one of SignedJWTAlgHS256 (the default),
	// SignedJWTAlgRS256 or SignedJWTAlgES256. It selects the signing
	// method and which key field is required.
	Algorithm string
	// ClientSecret is the HMAC shared secret. Required for HS256 and
	// refused for the asymmetric algorithms. Encrypted at rest via the
	// platform's FieldEncryptor.
	ClientSecret string
	// PrivateKeyPEM is the PEM-encoded private key (PKCS#1 or PKCS#8
	// for RSA, SEC 1 or PKCS#8 for ECDSA). Required for RS256 and
	// ES256 and refused for HS256. Encrypted at rest via the
	// platform's FieldEncryptor.
	PrivateKeyPEM string
	// KeyID is emitted as the token's "kid" header when set. Upstreams
	// that hold several registered keys for one account select by it.
	// Optional; no header is emitted when empty.
	KeyID string
	// Issuer is the "iss" claim, and Subject the "sub" claim. Each is
	// omitted from the token when empty, because an upstream that
	// registered no value for one rejects a token that carries it: a
	// Sage X3 connected application checks both, an Apple App Store
	// Connect team key checks iss alone, and an Apple individual key
	// checks sub alone. At least one must be set — a token that
	// identifies nobody is not one any upstream in this class accepts.
	Issuer  string
	Subject string
	// Audience is the "aud" claim. Defaults to the connection's
	// endpoint URL at parse time; the value must match what the
	// upstream registered, byte for byte.
	Audience string
	// TokenLifetime is exp - iat. Defaults to
	// DefaultSignedJWTTokenLifetime.
	TokenLifetime time.Duration
	// IssuedAtSkew is how far back iat is set to absorb clock drift
	// between the platform and the upstream. It is also the renewal
	// margin: a cached assertion is abandoned once it is this close to
	// expiry, so one is never presented so near exp that the upstream's
	// clock could have passed it in flight. Setting it to zero is an
	// operator stating that the two clocks agree, and gives up the
	// margin as well as the backdating. Defaults to
	// DefaultSignedJWTIssuedAtSkew and must be under TokenLifetime —
	// a skew at or past the lifetime mints a token that is already
	// expired.
	IssuedAtSkew time.Duration
}