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 withConfig::from_envfrom the environment variables documented in the README.build_app— loads the catalog, connects to PostgreSQL and returns the ready-to-serveaxum::Router, for callers that bind or wrap it themselves.build_app_with_accessdoes the same with a customAccessPolicy(e.g. a SaaS account and tier lookup).serve—build_appplus binding0.0.0.0:{config.port}and serving until the listener fails.run— what the bundled binary does: initialisetracingfromRUST_LOG, loadConfig::from_env,serve, and turn anyErrorinto 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.
- Allow
All - 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.
- EnvAccess
Policy - 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::Displayform is the one-line message the binary prints before exiting. - Trust
Forwarded For - Which client address the key-check limit counts against
(
TRUST_FORWARDED_FOR).
Constants§
- DEFAULT_
CATALOG_ PATH overlays/catalog/2026-10-02-auth-profiles.jsonas GitHub Pages publishes it from this repository’smain, used whenCATALOG_PATHis 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; seeCatalog::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_HOURis unset. A person entering a key makes one to three. - DEFAULT_
OPERATOR_ NAME - The operator name when
OPERATOR_NAMEis unset: neutral, because the crate does not know who runs it.
Traits§
- Access
Policy - 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 defaultEnvAccessPolicy(REVOKED_SUBJECTS,ALLOWED_AGENTS). - build_
app_ with_ access - Builds the complete application router from
config: the cookie key, the composed catalog (fetched fromconfig.catalog_path, which may be an HTTPS URL) and the PostgreSQL-backed store, admitting connection owners throughaccess. The returned router already carries CORS and request tracing layers. - parse_
agent_ id - Parses any accepted spelling of an agent id.
Nonefor anything else: an HTTP agent URL, another identifier kind, a malformed or non-Ed25519 key. - run
- The bundled binary’s entry point: installs a
tracingsubscriber filtered byRUST_LOG(defaultinfo; skipped if the caller already installed one), loadsConfig::from_envand runsserve. AnyErroris printed to stderr and reported as a failing exit code. - serve
- Runs
build_appand serves it on0.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 unlessTRUST_FORWARDED_FORsays otherwise. A caller that servesbuild_app’s router itself should do the same (into_make_service_with_connect_info::<SocketAddr>()); without it, and without a trustedX-Forwarded-For, every client shares one limit.