Skip to main content

Crate atomic_integration_proxy

Crate atomic_integration_proxy 

Source
Expand description

OAuth/catalog integration proxy for Atomic Server and LocalThought clients.

Clients authenticate with their Atomic agent key (issue #54): every request that matters carries an Atomic v2 request signature, a connection is owned by the agent that redeemed it, and apps use it through owner-signed delegations. There are no accounts, logins, tenants or rotating codes.

This crate is the whole service; the integration-proxy binary in this package, and any deployment wrapper (e.g. the Heroku app that serves localthought.io), is a thin main around it. The public API is deliberately small:

  • Config — all runtime configuration, loaded with Config::from_env from the environment variables documented in the README.
  • build_app — loads the catalog, connects to PostgreSQL and returns the ready-to-serve axum::Router, for callers that bind or wrap it themselves. build_app_with_access does the same with a custom AccessPolicy (e.g. a SaaS account and tier lookup).
  • serve — build_app plus binding 0.0.0.0:{config.port} and serving until the listener fails.
  • run — what the bundled binary does: initialise tracing from RUST_LOG, load Config::from_env, serve, and turn any Error into a message on stderr and a failing exit code.

A minimal wrapper binary is therefore:

#[tokio::main]
async fn main() -> std::process::ExitCode {
    atomic_integration_proxy::run().await
}

Everything else (route handlers, catalog composition, the security store) is private and may change in any release.

Structs§

AgentId
A parsed, verifiable agent id.
AllowAll
Admits every agent. Useful for a self-hosted proxy and in tests.
Config
Runtime configuration, loaded entirely from environment variables so the server itself stays container-friendly.
EnvAccessPolicy
The policy configured from the environment: a denylist and an optional allowlist, both of agent ids in any accepted spelling.

Enums§

Access
The answer to “may this owner use the proxy now?”.
Error
A failure while starting or running the proxy. The std::fmt::Display form is the one-line message the binary prints before exiting.
TrustForwardedFor
Which client address the key-check limit counts against (TRUST_FORWARDED_FOR).

Constants§

DEFAULT_CATALOG_PATH
overlays/catalog/2026-10-02-auth-profiles.json as GitHub Pages publishes it from this repository’s main, used when CATALOG_PATH is not set. Unlike the unversioned catalog this replaced, its dated file and selected overlay revisions are immutable; the proxy reads it once, at startup. Shared with tests that need to validate the exact catalog the application would load by default (they read the checked-in copy; see Catalog::load_checked_in).
DEFAULT_KEY_CHECK_LIMIT_PER_HOUR
The key checks one client network may make per platform and hour when KEY_CHECK_LIMIT_PER_HOUR is unset. A person entering a key makes one to three.
DEFAULT_OPERATOR_NAME
The operator name when OPERATOR_NAME is unset: neutral, because the crate does not know who runs it.

Traits§

AccessPolicy
A pluggable admission check. Implementations should answer quickly (the check runs on every request) and cache lookups as they see fit.

Functions§

build_app
Builds the complete application router from config, with the default EnvAccessPolicy (REVOKED_SUBJECTS, ALLOWED_AGENTS).
build_app_with_access
Builds the complete application router from config: the cookie key, the composed catalog (fetched from config.catalog_path, which may be an HTTPS URL) and the PostgreSQL-backed store, admitting connection owners through access. The returned router already carries CORS and request tracing layers.
parse_agent_id
Parses any accepted spelling of an agent id. None for anything else: an HTTP agent URL, another identifier kind, a malformed or non-Ed25519 key.
run
The bundled binary’s entry point: installs a tracing subscriber filtered by RUST_LOG (default info; skipped if the caller already installed one), loads Config::from_env and runs serve. Any Error is printed to stderr and reported as a failing exit code.
serve
Runs build_app and serves it on 0.0.0.0:{config.port} until the server fails; under normal operation it does not return. Each request carries its peer address (ConnectInfo<SocketAddr>), which the key-check limit counts unless TRUST_FORWARDED_FOR says otherwise. A caller that serves build_app’s router itself should do the same (into_make_service_with_connect_info::<SocketAddr>()); without it, and without a trusted X-Forwarded-For, every client shares one limit.