Crate car_auth 

Shared Parslee OAuth2 PKCE + token/keychain logic.

Used by car-cli (car auth login parslee, loopback flow) and by car-server (the auth.* JSON-RPC surface that CAR Host.app’s signup GUI drives). The keychain keys + default service exactly match what car-inference reads at request time. The serialized PARSLEE_AUTH_STATE_V2 record under the default "car" service is the durable authority; the old fixed slots are read only by locked migration.

Structs

AccountMeta

Non-secret metadata for one signed-in Parslee login.

AuthAttemptFailure

Safe terminal failure metadata persisted for one exact attempt.

AuthCompletionRecord

The latest causally-bound browser completion. Only one completion can remain current because every identity-changing credential mutation advances generation; a later mutation therefore supersedes this proof.

AuthCompletionStatus

One authoritative, coordinator-locked view of completion, generation, and attempt lifecycle. Optional fields are populated only for their matching state.

CredentialAuthorityHint

Non-secret routing/presentation metadata. Configured is never proof of authenticated identity; authoritative operations still read the OS store.

CredentialReadError

One terminal authoritative-read failure.

CredentialReadEventHandoff

Atomic starting point for an ordered credential-event consumer.

CredentialReadEventSubscription

One owned subscription to future credential-read lifecycle events.

CredentialReadStatus

Latest process-owned credential-read generation and its public state.

LocalAuthSnapshot

A local, non-mutating view of the persisted Parslee login state.

LoginAttemptLease

Persisted reservation and worker fence for one browser login attempt. auth.start publishes the awaiting-callback form. auth.complete may atomically populate the worker fields exactly once before network I/O; only a completion carrying that exact claimed lease may replace credentials.

RefreshedTokens

Result of a refresh_grant. The gateway may omit a rotated refresh token (reuse the prior one) and/or an expiry, so both are optional.

ResolvedParsleeCredential

Parslee request authority resolved from one credential snapshot.

TokenSet

/connect/token success body.

Enums

AuthAttemptPhase

Durable phase of an incomplete browser login attempt.

AuthCompletionState

Typed result returned by the local-only completion-status read.

AuthOperationError

Classified failure for coordinator-backed auth operations.

CredentialAuthorityState

Non-secret presentation state for passive auth surfaces.

CredentialReadEventCloseReason

Why an ordered credential-event subscription stopped.

CredentialReadFailureKind

Stable recovery classes. No variant contains secret material.

CredentialReadMode

Whether an authoritative credential use may start a new physical read.

CredentialReadStatusState

Secret-free state suitable for daemon event fanout.

CredentialState

Why there is no usable Parslee access token — for ERROR MESSAGES, not for control flow.

Constants

AUTH_COMPLETION_NETWORK_DEADLINE

Maximum time allowed for the aggregate token-exchange and completion-session network phase.

AUTH_COORDINATOR_QUEUE_TIMEOUT

Maximum time an auth operation may wait behind another in-process coordinator operation before failing safely without starting storage work.

AUTH_PROCESS_LOCK_TIMEOUT

Maximum time allowed to acquire the per-user cross-process auth-state lock.

AUTH_STATE_OPERATION_BUDGET

Bound used for one authoritative credential-store read or publication in the login-worker budget. The macOS keychain helper enforces this duration; the other local backends are expected to complete within the same budget.

DEFAULT_API_BASE

LOGIN_ATTEMPT_CALLBACK_TTL

The host allows up to 300 seconds for the browser callback. Keep the durable reservation valid beyond that window so a callback at the edge can still atomically claim its bounded completion worker.

LOGIN_ATTEMPT_WORKER_SCHEDULING_MARGIN

Explicit scheduler/runtime headroom after every bounded serial phase.

LOGIN_ATTEMPT_WORKER_SERIAL_BUDGET

Worst-case serial work between calculating the redeeming lease expiry and the strict expiry check immediately before credential publication:

LOGIN_ATTEMPT_WORKER_TTL

Redeeming-worker lease derived from the complete serial budget plus positive scheduling margin. Keep this below the host’s 480-second reconciliation horizon when changing any component.

PARSLEE_ACCESS_TOKEN_KEY

PARSLEE_API_BASE_KEY

PARSLEE_EXPIRES_AT_KEY

PARSLEE_REFRESH_TOKEN_KEY

REFRESH_SKEW_SECS

Seconds before the stored expiry at which access_token_refreshing proactively refreshes — absorbs clock skew plus a slow request. Public so the daemon’s load_or_refresh shares the same threshold (#320).

Functions

access_token

Current access token (env override first, then authoritative V2 record).

access_token_is_available

Whether Parslee inference may enter request-time credential reconciliation.

access_token_lifetime_remaining

Seconds of life left in the active access token, for callers that want to warn before a long operation dies rather than diagnose it afterwards.

access_token_refreshing

Compatibility token-only view of resolve_credential.

account_id_from_session

Parse the stable account id from a /connect/session response.

api_base

Resolve the API base: explicit override → process environment → authoritative V2 record → default.

auth_completion

Read the latest browser completion without refreshing or mutating tokens.

auth_completion_status

One local-only, coordinator-locked completion/lifecycle snapshot.

auth_completion_status_classified

Read completion proof while preserving a typed pre-operation deadline.

auth_generation

Current durable generation of the active Parslee credential identity.

authorize_url

Build the /connect/authorize URL the user opens in a browser.

claim_login_attempt

Atomically claim one exact awaiting-callback attempt for a single daemon worker. Duplicate, missing, stale, or expired attempts fail before OAuth token exchange.

claim_login_attempt_classified

Claim a login attempt while preserving a typed pre-operation deadline.

commit_login

Atomically publish a newly-authorized login and its attempt-bound completion.

credential_authority_hint

Read the passive, non-authoritative auth hint from CAR_HOME.

credential_state

Classify the current credential state. See CredentialState.

exchange_code

Exchange an authorization code + PKCE verifier for tokens.

fail_login_attempt

Persist a terminal result only while the worker still owns its exact fence.

fetch_status

Fetch the Parslee session JSON for the stored token. Returns the raw response body (the caller renders it). Ok(None) = not signed in.

fetch_status_with_access

Fetch /connect/session with an explicitly supplied access token.

force_refresh

Unconditionally refresh the Parslee bearer, for the reactive 401 path. access_token_refreshing only refreshes inside a proactive window keyed on the stored expiry — but a token can be revoked or invalidated server-side before its advertised expiry, and a token stored without an expiry never enters that window at all. When a live request is rejected with 401/403, the caller invokes this to mint a fresh bearer and retry once, instead of letting the failure poison 30-day model health (#313).

invalidate_access_token_cache

Drop any process-cached access token.

list_accounts

List every known login (active marks the current one). Migrates a pre-multi-login session (tokens in the fixed slots, no registry entry) in.

local_auth_snapshot

Local pre-browser auth state. No network request or refresh occurs. The first read may import an attributable legacy session into the authoritative V2 record; an ambiguous legacy marker reports signed-out and its orphan token is discarded, so the caller can sign in again.

logout

Publish a signed-out tombstone before best-effort legacy cleanup.

new_state

Opaque OAuth state value (CSRF guard).

pkce_challenge

PKCE S256 challenge for a verifier.

pkce_verifier

PKCE code verifier (URL-safe, no padding).

refresh_credential

Force one coordinator-owned Parslee refresh after a server auth rejection.

refresh_grant

refresh_token grant against /connect/token. Network-only — the caller persists. Mirrors the Parslee gateway contract used by the daemon’s own refresh path (car-server-core::parslee_auth): the gateway treats this as a public-client grant, so no client_id is sent. This lives in car-auth (not car-server-core) so the request-time inference path — which cannot depend on car-server-core — shares one definition of “mint a fresh Parslee bearer” (#313).

remove_account

Remove a login (deletes its stashed tokens). If it was active, switch to another remaining login, or clear the session when none remain.

reserve_login_attempt

Atomically reserve one browser login attempt during auth.start. Publishing a newer reservation advances the credential generation and permanently fences every older completion before any code can be redeemed.

reserve_login_attempt_classified

Reserve a login attempt while preserving a typed pre-operation deadline.

resolve_credential

Resolve one Parslee credential through the process-owned flight.

set_active_org

Set the account’s active organization (bearer PUT /accounts/me/active-org).

subscribe_credential_read_event_handoff

Atomically capture the last secret-free status and subscribe to later ones.

subscribe_credential_read_events

Subscribe to future secret-free credential-read events without coalescing.

subscribe_credential_read_updates

Subscribe to the latest secret-free credential-read state snapshot.

switch_account

Switch the active login by publishing the selected account credential as part of the same V2 record.

switch_org

Switch the active organization silently by minting a fresh token scoped to org_id via the refresh grant’s organization_id override (/connect/token, grant_type=refresh_token). The backend validates membership and stamps active_org=org_id on the new access token — which is what inference reads — so the switch takes effect without a browser re-authorization. Rotated tokens are persisted to the keychain. Also best-effort updates the account’s default org so a future fresh sign-in lands in the same place.