Module broker 

The credential broker — the mandatory boundary between runtimes and provider secrets (Checkpoint 1 decision, docs/decisions/credential-broker-checkpoint-1.md).

Invariants (enforced by construction and tests)

• Runtime/TUI code talks to a CredentialBroker and never reads auth.json, provider-key config, or credential environment variables. All of that discovery lives inside LocalBroker — behind the boundary.
• OAuth responses vend access token + expiry only (AccessToken has no refresh field to put one in). Refresh tokens stay broker-owned.
• Static API keys are never vended, locally or remotely. They are applied broker-side via the typed request proxy (ProxyRequest): the broker pins the destination URL from its own static_providers table and attaches the bearer key itself.
• Capability/status queries (ProviderStatus) expose configured-ness only — never key material.
• Fail closed: a missing credential is an error, never a fallback to a direct read at the call site.

Structs

AccessToken

An OAuth access token vended by the broker.

CloudCatalogEntry

Normalized dynamic cloud model returned across local/remote broker boundaries.

LocalBroker

In-process credential broker. This module is the ONLY place runtime-serving code may read auth.json, provider.<key> config values, or credential environment variables.

PinnedToken

The selected/pinned pair a runtime works with for one attempt: the credential the broker chose and the token vended for exactly that credential. Account-specific headers (e.g. the Codex account id) must be derived from token, never from a second lookup.

ProviderStatus

Non-secret capability/status row for one provider.

ProxyRequest

A typed, credential-free request the broker executes on the caller’s behalf against an OpenAI-compatible provider endpoint.

ProxyResponse

Buffered (non-streaming) proxy result: upstream status + body text.

RemoteBroker

Client for a remote synaps auth-broker. Presents the machine’s own bearer token; receives access tokens (OAuth) and proxied responses (static-key providers). Never receives refresh tokens or raw keys.

Enums

BrokerError

Broker failures. Messages never contain credential values. Non-exhaustive: new failure kinds are added as brokers gain operations.

CloudEvent

Credential-free normalized cloud invocation event.

CredentialKind

What kind of credential a provider uses. Never carries key material.

ProxyMethod

HTTP method subset the proxy protocol supports.

StaticKeyStatus

Non-secret display status for one static key (settings UI).

Constants

BROKER_STREAM_IDLE_TIMEOUT

Idle timeout between bytes on the broker’s per-request no-redirect client (Muse, Kimi, Gemini, Codex/Anthropic catalog). Matches the runtime client’s 90s read timeout that xAI streams already get.

DEFAULT_MAX_SNAPSHOT_AGE

Default staleness bound for automatic selection. Short on purpose: a selection is a spend decision and should rest on a fresh reading.

GEMINI_STREAM_IDLE_TIMEOUT

Gemini (Code Assist) sends no data chunk while it thinks (thought streaming is off), and a hard prompt can think silently for minutes; its stream has no retry, so it gets a longer idle limit.

GOOGLE_GEMINI_CODE_ASSIST_BASE_URL

Pinned Code Assist host for the broker-only Google Gemini proxy runtime. The service is treated as experimental and only the exact v1internal method paths reviewed in the spec are permitted (setup + streaming).

MAX_PROXY_REQUEST_BYTES

Maximum serialized size of a proxy request body.

MAX_PROXY_RESPONSE_BYTES

Maximum buffered (non-streaming) response body size.

MAX_UPSTREAM_ERROR_BYTES

Historical cap for upstream error-body snippets. Upstream/broker error bodies are no longer read at all (spec §5.1: they may echo the request); the constant remains only because it is re-exported from auth::mod.

OPENAI_CODEX_BACKEND_BASE_URL

Pinned ChatGPT backend host for OpenAI Codex catalog traffic.

PROXY_REQUEST_TIMEOUT

Total time budget for a buffered (non-streaming) broker-executed request.

Traits

CloudBackend

CredentialBroker

The typed credential broker protocol. One implementation runs in-process (LocalBroker) so normal local use needs no daemon; the other talks to a remote synaps auth-broker over authenticated HTTP(S) (RemoteBroker).

Functions

anthropic_credential_available

True if any Anthropic credential is available through the broker (OAuth login under the active account policy, or ANTHROPIC_API_KEY). Non-secret answer for first-run UX.

broker_access_token

Legacy signature bridge: resolve an access token via the appropriate broker for source. Kept for CLI paths (synaps status).

broker_from_source

remote transport. There is no third option — and no direct-read fallback.

capacity_from_snapshot

Map a typed usage snapshot onto the pure capacity policy’s input. Only account-wide and model-scoped quota windows constrain inference; feature-scoped windows (e.g. code review) are not inference limits.

configured_static_provider_keys

The set of static providers with an available credential. Non-secret.

global_broker

The process-wide broker. Defaults to the in-process LocalBroker so normal local use never requires a separately launched daemon.

global_broker_install_count

How many times set_global_broker has run in this process.

local_auth_state

synaps auth state for the local broker cache holds for the current credential store and config (the one requests use) or, when no request has built one yet, the account list with nothing recorded. live: the caller is the process that serves requests (the daemon). No network request, no refresh; query.clear never writes the store.

local_endpoint_config

The explicitly-configured local endpoint, if any (None → default in use).

local_endpoint_url

The local endpoint URL (non-secret configuration: provider.local.url config → LOCAL_ENDPOINT env → default).

local_model_ids

Comma-separated local model ids from non-secret config (provider.local.models).

oauth_provider_logged_in

True if the OAuth provider has a stored, refreshable credential the active account policy (env > config > default) can reach. Non-secret availability query for UI surfaces; an expired access token is still a valid login when the broker can refresh it on first use.

preflight_cloud_capability

Build the right broker for a credential source. Local sources get the in-process broker (no daemon needed); remote sources get the authenticated Pre-flight capability check for a cloud route (spec §5.5). Pure function: callers MUST run it before constructing a broker, looking up credentials, or opening any connection. The invoke-time guard inside the broker remains in place as defense in depth.

set_global_broker

Install the process-wide broker (called once from runtime configuration). Every call is counted (global_broker_install_count) and, when SYNAPS_MEM_TRACE=1, logged — the daemon-mode S7 gate asserts the count stays at 1 across subagent spawns.

static_key_configured

True if a static key is available through the broker (storage, login config, or env). Never returns the key.

static_key_status

Non-secret display status for a static key: configured (with masked preview), from-env, or not set. The mask keeps at most the first 4 and last 4 characters and is safe to render.

static_key_status_map

Non-secret map of static key display statuses for every provider, plus the local endpoint. For settings UI snapshots.

Type Aliases

CloudEventStream

ProxyByteStream

Streaming proxy result: raw upstream bytes (SSE), post-authorization.