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)

Re-exports

pub use broker::broker_from_source;

pub use broker::global_broker;

pub use broker::preflight_cloud_capability;

pub use broker::set_global_broker;

pub use broker::AccessToken;

pub use broker::BrokerError;

pub use broker::CredentialBroker;

pub use broker::CredentialKind;

pub use broker::LocalBroker;

pub use broker::ProviderStatus;

pub use broker::ProxyByteStream;

pub use broker::ProxyMethod;

pub use broker::ProxyRequest;

pub use broker::ProxyResponse;

pub use broker::RemoteBroker;

pub use broker::StaticKeyStatus;

pub use broker::MAX_PROXY_REQUEST_BYTES;

pub use broker::MAX_PROXY_RESPONSE_BYTES;

pub use broker::MAX_UPSTREAM_ERROR_BYTES;

pub use broker::PROXY_REQUEST_TIMEOUT;

pub use cloud::AuthIdentity;

pub use cloud::AwsBedrockConfig;

pub use cloud::AzureOpenAiConfig;

pub use cloud::BrokerMessage;

pub use cloud::BrokerOperation;

pub use cloud::BrokerTool;

pub use cloud::CloudProviderId;

pub use cloud::GoogleVertexConfig;

pub use cloud::InvokeOptions;

pub use cloud::InvokeRequest;

pub use cloud::MessageRole;

pub use cloud::ProviderId;

pub use github_copilot::login as login_github_copilot;

pub use provider::BrokerCredentialStrategy;

pub use provider::OAuthProviderDescriptor;

pub use provider::OAuthProviderId;

pub use provider::OAuthProviderRegistry;

pub use static_providers::static_provider;

pub use static_providers::StaticProviderSpec;

pub use static_providers::LOCAL_PROVIDER_KEY;

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.

provider

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

providers

static_providers

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

Structs

AuthFile

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.

BrokerToken

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

CallbackResult

Result from the OAuth callback.

CallbackServerHandle

OAuthCredentials

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

CallbackOutcome

CredentialSource

Where a client gets its provider credentials.

Constants

DEFAULT_MARGIN_MS

Default refetch margin: 5 minutes (mirrors is_token_expired).

Traits

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

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.

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_openai_codex

login_xai

open_browser

Open a URL in the default browser.

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.

start_callback_server

start_callback_server_at