credsource

type ClientCredential struct {
	// ClientID is the resolved OAuth client_id. Required — a resolver
	// that yields an empty ClientID has failed and returns an error
	// instead.
	ClientID string
	// ClientSecret is the resolved OAuth client_secret. NEVER logged.
	ClientSecret string
	// ExpiresAt is the credential's validity horizon. Zero means "no
	// expiry advertised" (env / static). The remote source's in-memory
	// serve horizon never exceeds this value.
	ExpiresAt time.Time
}

type Config struct {
	// ProviderName is the operator-facing provider name — surfaced in
	// boot / fetch error messages and used to attribute fetch events.
	ProviderName string
	// ProviderIndex is the provider's position in
	// `tools.oauth_providers[]`, used to reproduce the historical env
	// fail-loud message shape.
	ProviderIndex int

	// ClientIDEnv / ClientSecretEnv name the env vars the `env` source
	// reads. Empty for the remote source.
	ClientIDEnv     string
	ClientSecretEnv string

	// Remote carries the `remote` source's parameters; nil for env.
	Remote *RemoteConfig

	// HTTPClient is the client the remote source fetches through.
	// Optional — the remote driver applies a bounded default.
	HTTPClient *http.Client
	// Clock is the wall-clock source (cache math). Optional — defaults
	// to time.Now.
	Clock func() time.Time
	// Bus / Redactor let the remote source emit its SafePayload fetch
	// events. Mandatory for the remote source; unused by env.
	Bus      events.EventBus
	Redactor audit.Redactor
}

type Factory func(cfg Config) (Source, error)

type ProviderCredentialFetchFailedPayload struct {
	events.SafeSealed
	// Provider is the operator-facing provider name whose fetch failed.
	Provider string
	// Endpoint is the HOST of the configured remote `url`.
	Endpoint string
	// Reason is a short, redaction-safe classification of the failure
	// (e.g. "unreachable", "status 503", "malformed response"). NEVER
	// carries response bodies or credential bytes.
	Reason string
}

type ProviderCredentialFetchedPayload struct {
	events.SafeSealed
	// Provider is the operator-facing provider name whose client
	// credential was fetched.
	Provider string
	// Endpoint is the HOST of the configured remote `url` — never the
	// full URL with query material.
	Endpoint string
	// FormatVersion echoes the response's `format_version` — lets an
	// operator confirm the coordinator contract version in the audit
	// trail.
	FormatVersion int
	// ExpiresAt is the coordinator-advertised validity of the fetched
	// credential. Zero when the coordinator advertised no expiry. The
	// in-memory serve horizon never exceeds this value.
	ExpiresAt time.Time
}

type RemoteConfig struct {
	// URL is the coordinator credential endpoint (the authenticated GET
	// target). Required; validated well-formed at boot.
	URL string
	// AuthTokenEnv names the env var holding the runtime's own service
	// token — sent as `Authorization: Bearer <token>`. Required;
	// validated non-empty at boot (the token itself is read lazily at
	// fetch time so a rotated token is picked up without restart).
	AuthTokenEnv string
	// CacheTTL caps the in-memory serve horizon. Zero = the driver's
	// default cap. The effective horizon is min(response expires_in,
	// CacheTTL).
	CacheTTL time.Duration
	// Timeout bounds a single fetch. Zero = the driver's default.
	Timeout time.Duration
}

type Source interface {
	// ValidateAtBoot performs the source's boot-time readiness check,
	// called ONCE by `BuildProviders` while the config is still being
	// assembled.
	//
	//   - The env source RESOLVES and caches the credential now,
	//     reproducing the historical boot-time fail-loud (an unset env
	//     var crashes assembly with a message naming the field).
	//   - The remote source validates only the block SHAPE (url
	//     well-formed, auth-token env var non-empty) and DEFERS the
	//     network fetch to the first Resolve — so a coordinator-minted
	//     credential reaches an already-running runtime with zero touch.
	ValidateAtBoot(ctx context.Context) error

	// Resolve returns the current client credential, fetching or
	// refreshing as the source requires. Called by provider drivers at
	// credential-need time (the `oauth2` driver at construction; the
	// `tokenexchange` driver lazily at exchange time). Implementations
	// are single-flight and memory-cached where a fetch is involved.
	//
	// A failure returns a wrapped [ErrCredentialSourceUnavailable]
	// carrying the provider name and (for remote) the endpoint — with
	// ZERO secret bytes. Callers `errors.Is` against the sentinel.
	Resolve(ctx context.Context) (ClientCredential, error)
}