dcr

type CloseableCredentialStore interface {
	CredentialStore
	io.Closer
}

type CredentialStore interface {
	// Get returns the cached resolution for key, or (nil, false, nil) if the
	// key is not present. An error is returned only on backend failure.
	Get(ctx context.Context, key Key) (*Resolution, bool, error)

	// Put stores the resolution for key, overwriting any existing entry.
	// Implementations must reject a nil resolution with an error rather
	// than silently succeeding — a no-op would leave callers with no
	// debug trail for the subsequent Get miss.
	Put(ctx context.Context, key Key, resolution *Resolution) error
}

type Key = storage.DCRKey

type Request struct {
	// Issuer is the caller's logical scope for cache keying and (when
	// RedirectURI is empty) the basis for the default redirect URI
	// ({Issuer}/oauth/callback). Required.
	//
	// What each consumer puts here:
	//
	//   - Embedded authserver: its own issuer identifier. The authserver
	//     owns a distinct logical identity from the upstream IdP, and
	//     defaulting RedirectURI to {Issuer}/oauth/callback lands the
	//     callback on the authserver's origin (correct).
	//   - CLI OAuth flow: the upstream OAuth provider's issuer URL,
	//     because the CLI has no separate logical issuer of its own. The
	//     CLI always supplies an explicit loopback RedirectURI per
	//     RFC 8252 §7.3, so the redirect-URI defaulting is never
	//     exercised on this path.
	//
	// The resolver's cache key is (Issuer, RedirectURI, ScopesHash); the
	// two consumers do not collide on the key because the embedded
	// authserver's RedirectURI lives on the authserver's origin and the
	// CLI's lives on a loopback (RFC 8252 §7.3) — even when Issuer
	// happens to match between the two profiles, the RedirectURI
	// component keeps the cache key distinct. See the cross-consumer
	// caveat on dcrFlight in resolver.go for the wider invariant.
	//
	// Issuer is *not* used for RFC 8414 §3.3 metadata verification —
	// that uses an issuer recovered from DiscoveryURL inside the
	// resolver.
	Issuer string

	// RedirectURI is the redirect URI to register with the upstream. When
	// empty, the resolver derives {Issuer}/oauth/callback. HTTPS is required
	// except for loopback hosts (RFC 8252 §7.3 — the CLI flow uses
	// http://localhost:{port}/callback).
	RedirectURI string

	// Scopes are the OAuth scopes to request in the registration body.
	// May be empty; the resolver will fall back to discovered scopes if the
	// upstream advertises any.
	Scopes []string

	// DiscoveryURL points at the upstream's RFC 8414 / OIDC Discovery
	// document. The resolver fetches this URL exactly once and reads
	// registration_endpoint, authorization_endpoint, token_endpoint,
	// token_endpoint_auth_methods_supported, scopes_supported, and
	// code_challenge_methods_supported from it.
	//
	// Mutually exclusive with RegistrationEndpoint.
	DiscoveryURL string

	// RegistrationEndpoint is used directly when set, bypassing discovery.
	// On this branch the caller is expected to also supply AuthorizationEndpoint
	// and TokenEndpoint explicitly; the resolver's auth-method selection
	// defaults to client_secret_basic because no server-capability fields
	// are available.
	//
	// Mutually exclusive with DiscoveryURL.
	RegistrationEndpoint string

	// AuthorizationEndpoint, when non-empty, overrides any value discovered
	// via DiscoveryURL. Explicit caller configuration always wins.
	AuthorizationEndpoint string

	// TokenEndpoint, when non-empty, overrides any value discovered via
	// DiscoveryURL. Explicit caller configuration always wins.
	TokenEndpoint string

	// InitialAccessToken is the RFC 7591 initial access token presented to
	// the registration endpoint as a Bearer header. The caller resolves any
	// file-or-env reference before populating this field.
	InitialAccessToken string

	// ClientName is sent as the RFC 7591 "client_name" registration
	// metadata. When empty, the resolver uses
	// oauthproto.ToolHiveMCPClientName.
	ClientName string

	// PublicClient, when true, instructs the resolver to register as a
	// public PKCE client (token_endpoint_auth_method=none) regardless of
	// what other methods the upstream advertises. This matches the CLI
	// flow's intent (RFC 8252 §8.4 native public clients) and the
	// resolver still enforces the RFC 7636 / OAuth 2.1 S256 PKCE gate:
	// when the upstream's discovery metadata does not advertise S256 in
	// code_challenge_methods_supported, the registration is refused with
	// a clear error rather than silently downgrading.
	//
	// When false (the embedded-authserver default), the resolver picks
	// the strongest auth method the upstream advertises (private_key_jwt
	// > client_secret_basic > client_secret_post > none, with the same
	// S256 gate on "none").
	//
	// Has no effect on the RegistrationEndpoint-direct branch when the
	// caller has not also supplied a DiscoveryURL: without
	// code_challenge_methods_supported the S256 gate cannot be evaluated,
	// so the resolver refuses to register as a public client.
	PublicClient bool
}

type Resolution struct {
	// ClientID is the RFC 7591 "client_id" returned by the authorization
	// server.
	ClientID string

	// ClientSecret is the RFC 7591 "client_secret" returned by the
	// authorization server. Empty for public PKCE clients.
	ClientSecret string

	// AuthorizationEndpoint is the discovered (or configured) authorization
	// endpoint for this upstream.
	AuthorizationEndpoint string

	// TokenEndpoint is the discovered (or configured) token endpoint for this
	// upstream.
	TokenEndpoint string

	// RegistrationAccessToken is the RFC 7592 "registration_access_token"
	// required for subsequent registration management operations (update,
	// read, delete).
	RegistrationAccessToken string

	// RegistrationClientURI is the RFC 7592 "registration_client_uri" for
	// registration management operations.
	RegistrationClientURI string

	// TokenEndpointAuthMethod is the authentication method negotiated at the
	// token endpoint for this client.
	TokenEndpointAuthMethod string

	// RedirectURI is the redirect URI presented to the authorization server
	// during registration. When the caller's Request did not specify one,
	// this holds the defaulted value derived from the issuer + /oauth/callback
	// (via resolveUpstreamRedirectURI). Persisting it on the resolution lets
	// consumers (pkg/authserver/runner.consumeResolution) write it back onto
	// the run-config COPY so that downstream code (buildPureOAuth2Config,
	// upstream.OAuth2Config validation) sees a non-empty RedirectURI.
	RedirectURI string

	// ClientIDIssuedAt is the RFC 7591 §3.2.1 "client_id_issued_at" value
	// converted to a Go time.Time. Zero when the upstream omitted the field
	// (the field is OPTIONAL per RFC 7591). Informational; not used to
	// invalidate the cache.
	ClientIDIssuedAt time.Time

	// ClientSecretExpiresAt is the RFC 7591 §3.2.1 "client_secret_expires_at"
	// value converted to a Go time.Time. The wire convention is that 0 means
	// "the secret does not expire"; in this struct that is represented by
	// the zero time.Time so callers can use IsZero() rather than special-
	// casing 0.
	//
	// When non-zero, this field is the authoritative signal that
	// lookupCachedResolution uses to refetch credentials before the upstream
	// rejects them at the token endpoint. The 90-day dcrStaleAgeThreshold
	// is a heuristic for "consider rotating"; this is a hard expiry asserted
	// by the upstream itself.
	ClientSecretExpiresAt time.Time

	// CreatedAt is the wall-clock time at which the resolution was completed.
	// Used by the staleness observability in lookupCachedResolution to
	// compute age against dcrStaleAgeThreshold and emit a warn log when a
	// cached registration exceeds the threshold.
	CreatedAt time.Time
}