car-auth

Shared Parslee OAuth2 PKCE + token/keychain core for Common Agent Runtime.

What it does

One implementation of Parslee sign-in, used by two surfaces:

• car-cli — car auth login parslee (loopback redirect flow).
• car-server — the auth.* JSON-RPC surface that CAR Host.app's signup/sign-in GUI drives.

Keychain contract

Parslee auth has one authoritative record in the default "car" keychain service: PARSLEE_AUTH_STATE_V2. It contains the active credentials, held accounts, revision, identity generation, and one bounded latest-attempt lifecycle (awaiting_callback, worker-owned redeeming, terminal failure, or completion). One car-secrets::SecretStore::publish call is the commit point, so readers do not observe token/account/generation/lifecycle fields from different mutations.

For isolated release proof on macOS only, CAR_KEYCHAIN_PATH selects an existing real Keychain without changing the user's default Keychain or search list. It is accepted only together with CAR_KEYCHAIN_PROOF_ROOT; both paths must be absolute and owned by the current user, the root must be an owner-private non-symlink directory, and the Keychain must be an owner-private regular non-symlink file canonically contained by that root. The validated path is appended to every /usr/bin/security read, availability/status, write, and delete operation. With no selector, normal Keychain behavior is unchanged.

car-secrets also exposes process-lifetime operation counters for get, status, availability, write, and delete attempts. They are aggregate diagnostics only: no service, key, credential identity, filesystem path, or value is retained.

Passive credential authority

After the authoritative V2 record commits, car-auth atomically writes $CAR_HOME/parslee-auth-authority.json at Unix mode 0600. It contains only state (unknown, signed_out, or configured), credential generation, and an update timestamp. It never contains a token, account or organization identity, email, API base, credential reference, or Keychain path. Missing, malformed, oversized, symlinked, or field-expanded files load as unknown.

The hint is presentation and routing metadata, not authentication evidence. Every authenticated operation must still resolve the authoritative credential and fail closed. A hint publication failure is logged and passive state is degraded to unknown; it never rolls back an already-committed credential mutation.

The older fixed slots (PARSLEE_ACCESS_TOKEN, PARSLEE_REFRESH_TOKEN, PARSLEE_ACCESS_TOKEN_EXPIRES_AT, PARSLEE_API_BASE), account registry, per-account stashes, generation, completion, and active marker are import-only. The first coordinated read migrates an attributable legacy session and then best-effort removes those slots. If legacy tokens carry an empty or __unknown__ active marker, disagree with registry.active, or name an account absent from the registry, CAR discards the fixed slot rather than relabelling it onto a guessed account: the migration keeps whatever logins the registry can account for, publishes a signed-out record, and the user signs in again. It degrades rather than failing because the import runs ahead of every read — including the one that starts a fresh sign-in — so a fatal import would make the sign-in that clears the orphan unreachable. Malformed legacy data is still a hard error. Explicit logout remains available and publishes a signed-out tombstone before cleanup.

All auth slots, including PARSLEE_AUTH_STATE_V2, are daemon-private: generic CLI/FFI/RPC secret wrappers cannot read, replace, or delete them. The explicit PARSLEE_ACCESS_TOKEN environment override remains available for test/CI injection, but it cannot masquerade as a durable completion proof.

Multiple logins, and switching org

The V2 record contains every held login and exactly one optional active credential. Every request-time Parslee consumer reads that same active value: the CLI, daemon status and refresh paths, car-parslee, and inference do not maintain separate writers.

Login completion, account switch/removal, logout, and org-switch refresh each publish one replacement record. A refresh performs network I/O before taking the credential lock, then compares the captured revision and account ID; a stale refresh cannot overwrite a newer login, logout, account switch, or org switch.

Trust boundary

The crate is deliberately headless: no browser-open, no loopback listener. Those are surface-specific — the CLI runs a localhost listener; the daemon hands the authorize URL to the in-process GUI, which carries the PKCE verifier + state between auth.start and auth.complete (same trust boundary as the keychain the token lands in). Mutations are serialized by a process-global Tokio mutex and a per-user cross-process file lock before entering the keychain; blocking keychain work runs off the async executor, the in-process coordinator queue has an enforced 30-second bound, and no network call occurs while either lock is held. Once an operation acquires the coordinator guard, its daemon-owned caller retains the guard until the blocking storage task joins; a response timeout or socket close cannot expose an overlapping mutation while keychain work continues. A successful browser completion records its random attempt ID in the same publication as the credential generation, allowing a host to reconcile a lost reply without replaying the one-time authorization code. auth.start first publishes an ownerless reservation valid beyond the 300-second browser window; any daemon instance may atomically claim it once. The daemon returns state:"accepted" only after that claim is durable and the redemption task is spawned. The claim persists a daemon/worker owner and a derived 210-second completion expiry before /connect/token. The lease is one numeric composition: 15 seconds for claim publication + 90 seconds for aggregate network work + 30 seconds for the coordinator queue + 30 seconds for the process lock + 15 seconds for the strict-expiry state read + 30 seconds of positive scheduling margin. It remains inside the host's 480-second reconciliation horizon, including one explicitly safe pre-redemption retry through both contention layers. AuthOperationError keeps coordinator/process-lock deadlines typed separately from terminal state, store, and worker failures, so the server can return retryable -32004 without treating corruption as transient. Duplicates fail before exchange, worker errors close terminally, a restart while awaiting the callback remains resumable, and a restart while redeeming fails instead of replaying a possibly-consumed code. auth_completion_status reads the already-published V2 completion, generation, and lifecycle from one lock acquisition and returns pending, complete, failed, or stale; it never imports legacy slots, and an expired or old-daemon worker is terminally closed by that same operation. Any later start, switch, or logout supersedes the older attempt. Onboarding/consent for brand-new accounts is handled entirely by Parslee's existing hosted web flow during the browser hand-off — this crate (and CAR generally) never touches consent, by design.