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/deletean API key in the OS keychain via thekeyringcrate. Secrets are wrapped insecrecy::SecretStringin 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 fromcostroid-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 acostroid-core/costroid-focusdependency (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 (insrc/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); withconnecton, 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 connectrun attempts none either, and a network-namespace fail-closed check proves theconnectaction cannot reach the host (and leaves no$HOMEresidue) 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):
- Local artifacts — provider logs on disk (today’s default, not this crate).
- Sanctioned push/hook — e.g. Claude’s
statusLinecapture (also not this crate). - Sanctioned OAuth (first-party; system browser + loopback redirect, PKCE) — T9+.
- The user’s own API key — official provider usage APIs, the user’s own key.
- 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§
- Anthropic
Adapter - The Anthropic Usage & Cost adapter, bound to
api.anthropic.com. - Auth
Header - One caller-supplied request header whose value is secret-class.
- Authorized
Client - A blocking HTTPS client bound to one explicitly authorized host.
- Connection
Registry - A non-secret record of which
ApiVendors are currently linked. - Credential
Store - A keychain-backed store for the user’s own usage/billing API keys.
- Date
Range - A requested UTC time range,
[start, end)—startinclusive,endexclusive. Callers should pass UTC-day-aligned instants; adapters format this for each vendor (Anthropic RFC 3339; OpenAI Unix seconds). - Http
Response - A successful (2xx) response: the status code plus the bounded raw body. Parsing into typed shapes is the caller’s job (T9b).
- Open
AiAdapter - The OpenAI Usage + Costs adapter, bound to
api.openai.com. - OrgLabel
- A non-secret organization label captured at connect time (Anthropic
me’sname/id), stored beside the vendor in theConnectionRegistryso the Connections view can show it offline. Carries zero secret material — the API key itself never leaves the OS keychain. - Parse
Vendor Error - Returned by
ApiVendor::from_strfor an unrecognized vendor slug. - Request
Limits - 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.
- Connect
Error - 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, orDisplaytext (pinned by tests). - Cost
Report Outcome - The result of a cost-report fetch: a report, or a typed reason it is unavailable.
- OrgValidation
- The outcome of
AnthropicAdapter::validate— the connect-timemepre-flight that proves an admin key works and captures the org label without reading any billing data. First-class data, never an error loop (mirrorsCostReportOutcome). - Usage
Report Outcome - The result of a usage-report fetch: a report, or a typed reason it is unavailable.
- Vendor
Report Unavailable - 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§
- Expose
Secret - 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.Nonewhen neither$XDG_STATE_HOMEnor$HOMEresolves a base directory. (Mirrors theclaude_rate_limits_cache_pathconvention incostroid-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::NoSanctionedStaticKeyApicarrying 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§
- Secret
String - Secret string type.