Skip to main content

Crate costroid_connect

Crate costroid_connect 

Source
Expand description

Costroid’s network + credential boundary — the only crate allowed to make a network call or touch a secret. Everything else in the workspace is provably local-only; this crate is the single, deliberate exception, and it is off by default (compiled in only behind a consumer’s connect Cargo feature — today apps/cli’s, off by default).

§Status: connections shipped (T8 keychain · T9a client · T9b adapters · T10a/T10c callers)

This crate carries the keychain-backed store for the user’s own usage/billing API keys (CredentialStore), a non-secret on-disk index of which vendors are linked (ConnectionRegistry), the generic authorized-host HTTPS client (AuthorizedClient): blocking ureq + rustls, OS-native trust roots, bound to one explicitly authorized host, redirects disabled, GET-only — and the per-provider usage-API adapters (AnthropicAdapter/OpenAiAdapter; Gemini = first-class unavailable). Its callers are the apps/cli connect/disconnect/connections CLI (T10a) and the reconcile display (T10c): a network call occurs only on an explicit, user-initiated connect / connections --check / reconcile action.

§What lives here

  • CredentialStore — store / retrieve / delete an API key in the OS keychain via the keyring crate. Secrets are wrapped in secrecy::SecretString in memory and are never written to disk, config, or logs — only the keychain holds them.
  • ConnectionRegistry — the non-secret answer to “what is linked?”, a small JSON index at ${XDG_STATE_HOME:-~/.local/state}/costroid/connections.json. The OS keychain is not portably enumerable, so this records the connected vendors (slugs only — zero secret material) for T10’s Connections view to read.
  • ApiVendor — the billing-vendor axis (whose usage/billing API a key calls): Anthropic / OpenAI / Gemini. This is deliberately distinct from costroid-providers::ProviderId (the tool axis: Claude Code / Codex / Cursor) — Cursor has no key, and “Anthropic” is not the Claude-Code tool — so this crate stays free of a costroid-core/costroid-focus dependency (T9a kept it that way: the generic client needs no internal type; they arrive with T9b if needed).
  • AuthorizedClient (+ AuthHeader, HttpResponse, RequestLimits) — the client described above (in src/http.rs): it can only talk to the one host it was constructed over (off-host requests are a typed error before any I/O), classifies failures (redirect / timeout / 429 / 5xx / other-4xx / transport / body-too-large) and leaves retry policy to its caller, and never lets a secret-valued header reach logs, Debug, or error text.

§The gate

costroid-connect is compiled into a binary only when that binary opts in via its connect Cargo feature. A default cargo build of the costroid binary never links it, so the shipped local-only build contains no keychain/HTTP/TLS code at all. Two tests keep that honest:

  • apps/cli/tests/offline.rs — the default build links none of the sanctioned trio (keyring/ureq/rustls); with connect on, exactly that trio is permitted (and asserted present, since T9a) while async runtimes, OpenSSL, other HTTP clients, and all telemetry stay forbidden.
  • scripts/offline_acceptance.sh — the default build runs every command under network isolation and proves no outbound IP traffic is attempted; its feature-on baseline proves a normal --features connect run attempts none either, and a network-namespace fail-closed check proves the connect action cannot reach the host (and leaves no $HOME residue) when no network exists.

§Why the sync Secret Service backend (Linux)

keyring is configured with the sync-secret-service backend (blocking C libdbus, via dbus-secret-service) plus pure-Rust crypto (crypto-rust), not the async-secret-service (zbus) path. That choice keeps no async runtime in the dependency graph — async-io/tokio stay globally forbidden even under --features connect — at the cost of the C build-deps libdbus-1-dev + libsecret-1-dev (installed in CI; ARCHITECTURE). macOS uses the Security framework (apple-native) and Windows the Credential Manager (windows-native).

§The auth source ladder (the rule the future code must obey)

Every datum is sourced by descending an explicit ladder, most-sanctioned first — only tiers 0–3 are ever built (ARCHITECTURE):

  1. Local artifacts — provider logs on disk (today’s default, not this crate).
  2. Sanctioned push/hook — e.g. Claude’s statusLine capture (also not this crate).
  3. Sanctioned OAuth (first-party; system browser + loopback redirect, PKCE) — T9+.
  4. The user’s own API key — official provider usage APIs, the user’s own key.
  5. Never reuse any credential, session, or cookie against a non-sanctioned, undocumented, or internal endpoint — that datum stays “unavailable”, never fetched.

No telemetry — ever. Network occurs only on an explicit, user-initiated connect action to a provider endpoint the user authorized (T9/T10).

Structs§

AnthropicAdapter
The Anthropic Usage & Cost adapter, bound to api.anthropic.com.
AuthHeader
One caller-supplied request header whose value is secret-class.
AuthorizedClient
A blocking HTTPS client bound to one explicitly authorized host.
ConnectionRegistry
A non-secret record of which ApiVendors are currently linked.
CredentialStore
A keychain-backed store for the user’s own usage/billing API keys.
DateRange
A requested UTC time range, [start, end) — start inclusive, end exclusive. Callers should pass UTC-day-aligned instants; adapters format this for each vendor (Anthropic RFC 3339; OpenAI Unix seconds).
HttpResponse
A successful (2xx) response: the status code plus the bounded raw body. Parsing into typed shapes is the caller’s job (T9b).
OpenAiAdapter
The OpenAI Usage + Costs adapter, bound to api.openai.com.
OrgLabel
A non-secret organization label captured at connect time (Anthropic me’s name/id), stored beside the vendor in the ConnectionRegistry so the Connections view can show it offline. Carries zero secret material — the API key itself never leaves the OS keychain.
ParseVendorError
Returned by ApiVendor::from_str for an unrecognized vendor slug.
RequestLimits
Bounds applied to every request a client makes: connect + overall timeouts and the response-body size cap. Exceeding any of them is a typed error (ConnectError::Timeout / ConnectError::BodyTooLarge), never a hang.

Enums§

ApiVendor
The billing-API vendor a stored key authenticates against — i.e. whose usage/billing API the key calls.
ConnectError
Anything that can go wrong reaching the OS keychain, the connection registry, or (since T9a) the authorized host. Library-crate errors are propagated, never unwrap/panic, and no variant ever carries secret material in its fields, Debug, or Display text (pinned by tests).
CostReportOutcome
The result of a cost-report fetch: a report, or a typed reason it is unavailable.
OrgValidation
The outcome of AnthropicAdapter::validate — the connect-time me pre-flight that proves an admin key works and captures the org label without reading any billing data. First-class data, never an error loop (mirrors CostReportOutcome).
UsageReportOutcome
The result of a usage-report fetch: a report, or a typed reason it is unavailable.
VendorReportUnavailable
Why a vendor report could not be produced — modeled as first-class data, never an error loop. (Display/message copy for the connect UX is T10’s; these carry the typed reason.)

Traits§

ExposeSecret
Expose a reference to an inner secret

Functions§

default_registry_path
Resolve the default registry path ${XDG_STATE_HOME:-$HOME/.local/state}/costroid/connections.json. None when neither $XDG_STATE_HOME nor $HOME resolves a base directory. (Mirrors the claude_rate_limits_cache_path convention in costroid-providers.)
gemini_cost_report
Gemini has no sanctioned static-key usage API, so there is no adapter: both report kinds resolve to a first-class VendorReportUnavailable::NoSanctionedStaticKeyApi carrying the pinned reason string (docs/ROADMAP.md). T10 renders it; nothing here ever performs a network call for Gemini.
gemini_usage_report
The usage-report counterpart of gemini_cost_report.

Type Aliases§

SecretString
Secret string type.