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.

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.

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

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 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.

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_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 stored refreshable credentials. This is a 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.