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. Opt-in RFC 8628 device sessions provide scoped bearer authentication to the same canonical owner; they do not create another account identity or revive provider connection 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.
DeviceConfig
Public clients have display names fixed by the operator, never provided by the device. The approval URL is a trusted owner hub using the browser module; registering clients requires an explicit approval integration.
EnvAccessPolicy
The policy configured from the environment: a denylist and an optional allowlist, both of agent ids in any accepted spelling.
WebhookConfig
The webhook inbox (ontola/atomic-plugins#369). Off unless WEBHOOKS_ENABLED=true: then, and only then, the proxy creates the inbox tables and runs the inbox sweeper. No webhook route is mounted yet.

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.
DEFAULT_WEBHOOK_INBOX_MAX_BYTES
The deployment inbox budget when WEBHOOK_INBOX_MAX_BYTES is unset: the plan’s 1 GiB pilot value.

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.