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)

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

Handle to shut down the callback server.

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

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 a non-Anthropic OAuth provider has a fresh token.

ensure_fresh_token

Acquire an exclusive lock on auth.json, 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_provider_auth

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

login

Run the full OAuth login flow. Returns saved credentials.

login_openai_codex

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 — the single entry point both the Anthropic and the OpenAI/codex paths use. (#158 C4)

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_provider_auth

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

start_callback_server

Start a temporary HTTP server on localhost that captures the OAuth callback. Returns a oneshot receiver that resolves with the auth code + state.