Module auth 

OAuth 2.0 Authorization Code + PKCE flow for Anthropic (Claude Pro/Max).

Implements the same flow as Claude Code and Pi coding agent:

1. Generate PKCE verifier + challenge
2. Start localhost callback server
3. Open browser to claude.ai/oauth/authorize
4. Capture redirect with auth code
5. Exchange code for access + refresh tokens
6. Save to ~/.pi/agent/auth.json (shared with Pi)

Modules

aws_bedrock

Provider-local IAM Identity Center and Bedrock broker boundary. The transport trait is intentionally typed: it cannot sign arbitrary URLs or vend credentials.

azure_openai

Provider-local Azure OpenAI OAuth, catalog, and broker request contracts. No function in this module performs network I/O or returns credentials.

broker

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

cloud

Shared, credential-free cloud provider contracts.

cloud_login

Provider-specific interactive cloud login protocols. Credentials remain persisted only through the broker-owned auth store.

github_copilot

GitHub Copilot OAuth (device authorization + broker-owned session mint).

google_gemini

Google Gemini (Code Assist) OAuth: authorization-code + PKCE.

google_vertex

Provider-local Google Vertex AI installed-app OAuth primitives.

kimi_code

Kimi Code OAuth (RFC 8628 device authorization; direct bearer, no mint).

provider

Typed OAuth provider identity, descriptors, registry validation, and dispatch.

providers

static_providers

Static-key provider connection metadata, owned by the credential broker.

Structs

AccessToken

An OAuth access token vended by the broker.

AuthFile

AwsBedrockConfig

AzureOpenAiConfig

BrokerClient

HTTP client for a credential broker. Presents the machine’s own bearer token (NOT the provider credential) and receives a short-lived access token.

BrokerMessage

BrokerToken

An access token as returned by the broker’s GET /token.

BrokerTool

CallbackResult

Result from the OAuth callback.

CallbackServerHandle

GoogleVertexConfig

InvokeOptions

InvokeRequest

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.

OAuthCredentials

OAuthProviderDescriptor

OAuthProviderRegistry

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.

StaticProviderSpec

Connection/credential metadata for one static-key provider.

TokenCache

Thread-safe, per-provider cache of broker access tokens. Cloneable handle over shared state. Holds ONLY short-lived access tokens, never a refresh token, never persisted to disk.

Enums

AuthIdentity

Credential mechanism used behind the broker boundary.

BrokerCredentialStrategy

How a runtime may obtain a usable credential from the broker.

BrokerError

Broker failures. Messages never contain credential values.

BrokerOperation

CallbackOutcome

CloudProviderId

CredentialKind

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

CredentialSource

Where a client gets its provider credentials.

MessageRole

OAuthProviderId

ProviderId

General auth identity. Existing OAuth identity remains strongly typed.

ProxyMethod

HTTP method subset the proxy protocol supports.

StaticKeyStatus

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

Constants

DEFAULT_MARGIN_MS

Default refetch margin: 5 minutes (mirrors is_token_expired).

LOCAL_PROVIDER_KEY

The local OpenAI-compatible endpoint pseudo-provider (Ollama, LM Studio…). Its endpoint URL is non-secret user configuration; its optional key is still broker-owned.

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.

PROXY_REQUEST_TIMEOUT

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

Traits

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

TokenFetcher

“Get a fresh access token from somewhere.” Abstracted so the cache/resolve logic is unit-testable without real HTTP. The real impl is BrokerClient.

Functions

auth_file_path

Get the path to auth.json (~/.synaps-cli/auth.json).

broker_from_source

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

build_auth_url

Build the full authorize URL for the browser.

ensure_fresh_provider_token

Ensure an OAuth provider (including Anthropic) has a fresh token.

ensure_fresh_token

Acquire the Anthropic refresh gate, check token freshness, refresh if needed, and persist the result atomically. Returns the current (possibly refreshed) credentials.

exchange_code_for_tokens

Exchange an authorization code for access + refresh tokens.

extract_codex_account_id

generate_code_challenge

Compute S256 code challenge from verifier.

generate_code_verifier

Generate a cryptographically random code verifier (43-128 chars, base64url).

generate_state

Generate a random state parameter.

global_broker

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

is_expired_with_margin

True if expires_ms is already past, or within margin_ms of now.

is_token_expired

Check if the current token is expired.

load_auth

Load credentials from auth.json.

load_cloud_state

Load an opaque broker-owned cloud provider state object.

load_provider_auth

Load one provider’s OAuth credential from auth.json.

load_static_key

Load one provider’s broker-owned static API key from auth.json.

login

Run the full OAuth login flow. Returns saved credentials.

login_github_copilot

Production login entry (real network + system browser + auth.json).

login_kimi_code

Production login entry (real network + system browser + auth.json).

login_openai_codex

login_xai

open_browser

Open a URL in the default browser.

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.

refresh_token

Refresh an expired OAuth token.

resolve_access_token

Provider-aware token resolution honoring the credential source — kept as a compatibility adapter for CLI callers (synaps status). Delegates to the typed credential broker: the local in-process broker or the authenticated remote transport. Vends the access token only.

resolve_remote

Resolve a provider token via cache-or-fetch, returning the full BrokerToken (access + expiry). The runtime needs the expiry to drive its in-memory refresh trigger. NEVER touches a refresh token or auth.json.

resolve_remote_token

Like resolve_remote but returns only the access token string.

save_auth

Save credentials to auth.json.

save_cloud_state

Atomically persist opaque cloud state while preserving every unrelated field.

save_provider_auth

Save one provider credential while preserving other auth.json entries.

save_static_key

Persist a broker-owned static API key while preserving every other auth.json entry and any provider metadata.

set_global_broker

Install the process-wide broker (called once from runtime configuration).

start_callback_server

start_callback_server_at

static_provider

Look up a static provider spec by key.

Type Aliases

ProxyByteStream

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