resolvers

type ActiveKeyScanOptions struct {
	// MaxScan optionally bounds how many keys are examined in document order. nil
	// (the zero value) scans EVERY key — unbounded. A non-nil bound caps the scan at
	// max(0, *MaxScan) keys: 0 or negative scans none. When a non-nil positive bound
	// is exhausted without selecting a key AND the directory holds MORE keys than the
	// bound, the exhaustion is LOGGED (a valid key beyond the cap is unreachable), so a
	// bounded miss is never silently indistinguishable from a genuine "no active key".
	MaxScan *int
	// Logger receives the explicit-bound exhaustion warning (nil → slog.Default()).
	// Consulted ONLY on the bounded-exhaustion path; the unbounded default never logs.
	Logger *slog.Logger
}

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

type CachedOfferKeyResolverConfig struct {
	// Fetch resolves a domain to its WBA directory. REQUIRED —
	// NewCachedOfferKeyResolver panics when it is nil.
	Fetch OfferDirectoryFetcher
	// TTL bounds the per-domain cache; <=0 uses defaultOfferKeyTTL. The stored
	// entry's expiry is clamped to min(now+TTL, key.not_after) so a key is never
	// served past its validity window.
	TTL time.Duration
	// Now is the cache-freshness + selection clock; nil uses time.Now. Tests inject.
	Now func() time.Time
	// Revoked screens a candidate offer-signing key by its RFC 7638 thumbprint: a
	// revoked key is skipped during selection so the resolver never serves a
	// window-active-but-revoked key on the verification path. nil screens nothing —
	// inject WBAKeyResolver.Revoked (or an equivalent revoked-set predicate) on any
	// verification path; leaving it nil is a visible waiver of emergency revocation.
	Revoked func(thumbprint string) bool
}

type Content struct {
	// URL is the signed delivery URL that was fetched, echoed back so a caller
	// correlating a batch does not have to keep its own map.
	URL string
	// MIMEType is the media type the edge served, parameters stripped.
	MIMEType string
	// Body is the fetched bytes.
	Body []byte
}

type ContentFetchOptions struct {
	// BaseTransport carries the caller's own transport settings — a tuned
	// connection pool, client certificates via TLSClientConfig — UNDERNEATH the
	// SSRF guard. It is never a replacement for the guard: a delivery URL names a
	// host chosen by another party, so the address pin and the https-only scheme
	// check are applied in every case. Nil means a fresh transport under the guard.
	//
	// A custom TLS dialer on this base is dropped rather than honoured: net/http
	// would prefer it over the pinned dialer on https and the address check would
	// never run. Configure TLS through TLSClientConfig, which is kept.
	//
	// The redirect policy is likewise a property of this profile rather than a
	// detail a caller supplies. A caller that could inject a whole client would be
	// asserting against its own policy instead of the one production runs.
	//
	// The only way to reach a private or plaintext endpoint is the deliberate,
	// deployment-level SKIP_SSRF / ALLOW_INSECURE opt-out, which is one decision
	// recorded in one place instead of a per-caller copy of it.
	BaseTransport *http.Transport
	// Timeout bounds one fetch, proof minting included. Defaults to
	// DefaultContentTimeout.
	Timeout time.Duration
	// MaxBytes caps one fetched body. Defaults to DefaultMaxContentBytes.
	MaxBytes int64
	// RequestID mints the value of the X-Request-ID correlation header stamped on
	// each delivery GET. Nil sends no header.
	//
	// It matters on THIS leg in particular. The RPC legs correlate through an
	// interceptor, which a plain GET never traverses, so without a hook here the
	// delivery fetch is the one leg carrying no id — and a delivery edge that mints
	// its own when the header is absent then logs a refusal under an id nothing
	// else knows. That is the leg where delivery failures are diagnosed.
	//
	// A func rather than a string because one fetcher serves many requests, and the
	// point of the header is that each carries its own id. It is `func() string`
	// rather than the transport tier's named RequestIDFunc so this package needs no
	// dependency on that tier for one alias; a named type is assignable here.
	RequestID func() string
}

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

type FetchError struct {
	Failure FetchFailure
	Op      string
	Status  int    // HTTP status when the edge answered; 0 otherwise
	Reason  string // the edge's refusal token when it sent one
	Err     error
}

type FetchFailure int

type OfferDirectoryFetcher func(ctx context.Context, domain string) (*forav1.WBAFile, error)

type ProofSigner interface {
	// SignFetch returns the agent binding for a GET of targetURL. The URL is
	// passed verbatim because the proof covers it as an exact string.
	SignFetch(ctx context.Context, targetURL string) (helpers.AgentBinding, error)
}

type RegistrationRequirements struct {
	// TermsDigest is the manifest's terms_digest, nil when the Exchange publishes
	// none. Copy it onto RegisterRequest.terms_digest unchanged: the request
	// signature covers the echo, and that echo is the durable record of which
	// terms revision the operator accepted.
	//
	// A pointer rather than a string because absent and empty are different
	// answers on the wire, and only the pointer can carry the difference.
	TermsDigest *string

	// Schema validates registration_data before anything is signed. It is nil in
	// TWO cases — the Exchange publishes none, and the Exchange publishes one this
	// SDK refuses — and Verdict is what tells them apart. Both are deliberately
	// the same VALUE, because a nil *helpers.RegistrationSchema reports no
	// failures and that is the behaviour the contract requires of a client in both
	// cases: a local check that cannot run must not become a local veto.
	Schema *helpers.RegistrationSchema

	// Verdict is the SDK's answer for the published schema. SchemaNotPublished is
	// the ordinary absent case; SchemaAccepted means Schema is usable; anything
	// else names why a published schema was refused, which is worth logging and is
	// never worth refusing the registration over.
	Verdict helpers.SchemaVerdict
}

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

type WBAKeyResolverOptions struct {
	// HTTP overrides the client used for directory and revocation GETs. When nil,
	// the resolver installs a safe-by-default SSRF-guarded client (see
	// newGuardedWBAClient): the directory host is derived from request input (the
	// Signature-Agent header) and fetched before the ed25519 check, so the default
	// refuses private/link-local/loopback targets. Inject a client only to REACH a
	// private directory (tests, on-prem) or to apply a custom dialer/timeout.
	HTTP *http.Client
	// TTL bounds how long a fetched directory is reused (≤0 → 1 hour).
	TTL time.Duration
	// PollInterval is the base revocation-poll cadence for Run (≤0 → 300s).
	PollInterval time.Duration
	// SyncDebounce bounds how often the unknown-thumbprint force-refresh may fire
	// per directory host (≤0 → 5s). It caps the outbound directory fetches an
	// unauthenticated caller can drive by presenting unknown thumbprints — the
	// resolver runs before the ed25519 check and the host is the caller-supplied
	// Signature-Agent. The TTL-cache refresh path is NOT gated by it; only the
	// self-heal force-fetch on an unknown thumbprint is.
	SyncDebounce time.Duration
	// Now overrides the clock for TTL and validity-window comparisons (nil →
	// time.Now). Tests inject.
	Now func() time.Time
	// After overrides the poll-tick timer source (nil → time.After). Tests
	// inject a deterministic clock.
	After func(time.Duration) <-chan time.Time
	// Scheme is applied when the Signature-Agent value carries no scheme
	// (empty → "https"). Tests inject "http" to drive an httptest server.
	Scheme string
	// RequireRevocation makes Resolve fail closed with ErrRevocationUnevaluated
	// when a key's directory declares a revocation_url but no snapshot has been
	// fetched (unreachable or not host-anchored) — i.e. revocation could not be
	// evaluated. Default false keeps the best-effort behavior (a declared-but-
	// unreachable revocation channel does not block resolution). Set it where a
	// revoked-key must never resolve even if the revocation channel is down.
	RequireRevocation bool
	// Logger receives best-effort revocation-refresh diagnostics (nil →
	// slog.Default()).
	Logger *slog.Logger
	// OnPollArmed and OnPollCycle are optional determinism seams for the Run
	// poller (nil in production). OnPollArmed fires each time the poller has
	// registered its next tick timer and is about to block; OnPollCycle fires
	// after each completed refresh. A deterministic-clock test waits for
	// OnPollArmed, advances the clock to fire the tick, then waits for
	// OnPollCycle — proving a poll boundary was crossed without sleeping.
	OnPollArmed func()
	OnPollCycle func()
}

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

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

type WellKnownOptions struct {
	// HTTP overrides the client used to fetch. The nil-default differs by resolver
	// because the URL's provenance differs: WellKnownKeyResolver fetches a
	// fixed, operator-chosen JWKS URL, so it defaults to the unguarded
	// http.DefaultClient; WellKnownEndpointResolver fetches a REQUEST-DERIVED
	// Offer.exchange host, so it defaults to the SSRF-guarded
	// NewGuardedClientFromEnv (same threat shape as the WBA directory fetch).
	HTTP *http.Client
	// TTL is how long a successful fetch is cached (≤0 → 5 minutes).
	TTL time.Duration
	// Now overrides the clock for cache freshness (nil → time.Now). Tests inject.
	Now func() time.Time
	// Allow, when set, gates which keyids (WellKnownKeyResolver) or hosts
	// (WellKnownEndpointResolver) may resolve (nil → allow all known). It is the
	// trust-allowlist seam: an Exchange host the application does not trust can be
	// rejected here before any fetch.
	Allow func(id string) bool
	// Scheme is the URL scheme the WellKnownEndpointResolver uses to build
	// {scheme}://{host}/.well-known/fora.json (empty → "https"). Tests inject
	// "http" to drive an httptest server. Unused by WellKnownKeyResolver, which
	// is constructed with a full URL.
	Scheme string
}

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