remote

Overview ¶

Package remote ships the coordinator-served credential source: the runtime PULLS an OAuth provider's client credential (`client_id` / `client_secret`) from an operator-configured endpoint at first need, authenticated by the runtime's own service token.

Why it exists ¶

A provider whose credential is env-resolved once at boot can never receive a credential a coordinator mints AFTER the runtime booted — the process environment is fixed at exec. The remote source closes that gap: the credential resolves lazily at first use, so a coordinator that provisions the runtime's credential post-boot reaches an already-running runtime with zero touch. This is the token-exchange pull posture one level up — the broker CLIENT credential is itself an externally owned secret, pulled from the authority that owns it and never persisted.

The fetch contract (Harbor-defined, versioned) ¶

A single authenticated GET:

GET <url>
Authorization: Bearer <token from auth_token_env>
Accept: application/json

The coordinator responds with a strict JSON object:

{
  "format_version": 1,          // REQUIRED — the contract version
  "client_id":      "...",      // REQUIRED
  "client_secret":  "...",      // REQUIRED
  "expires_in":     3600        // OPTIONAL — seconds; omitted / 0 = no expiry
}

Unknown top-level fields are rejected (strict) so contract drift fails loud instead of silently ignoring a mis-served field. The `format_version` lets the shape evolve; the runtime accepts version 1.

The endpoint MUST be https — the request carries the runtime's service bearer token; plaintext http is accepted only for a loopback host (127.0.0.0/8 / ::1 / localhost — the fixture / dev case). The fetch is terminal: redirects are refused, never followed (a credential endpoint that redirects is a fault, and following one could replay the bearer to a host the operator never configured).

Memory-only, TTL-capped, single-flight ¶

The fetched credential is held in memory only — never persisted (a sealed on-disk copy would recreate the shadow-store revocation hole a persisted externally-owned credential creates). The serve horizon is the EARLIER of the response's `expires_in` and the operator `cache_ttl` cap; a fetch on expiry refetches. A burst of concurrent misses collapses onto ONE fetch (single-flight per source instance — the client credential is runtime-level, not identity-scoped, so one credential serves every identity).

Fail loud, never fall back ¶

An unreachable endpoint, a non-200 status, or a malformed / strict- parse-rejected body fails the tool call with the typed credsource.ErrCredentialSourceUnavailable (provider + endpoint, ZERO secret bytes) and emits a `tool.provider_credential_fetch_failed` SafePayload event. There is NEVER a fallback to env, to an unauthenticated call, or to the interactive flow (§13). A successful fetch emits `tool.provider_credential_fetched`.