Skip to main content

atomic_integration_proxy/
lib.rs

1//! OAuth/catalog integration proxy for Atomic Server and LocalThought
2//! clients.
3//!
4//! Clients authenticate with their Atomic agent key (issue #54): every
5//! request that matters carries an Atomic v2 request signature, a connection
6//! is owned by the agent that redeemed it, and apps use it through
7//! owner-signed delegations. Opt-in RFC 8628 device sessions provide scoped
8//! bearer authentication to the same canonical owner; they do not create
9//! another account identity or revive provider connection codes.
10//!
11//! This crate is the whole service; the `integration-proxy` binary in this
12//! package, and any deployment wrapper (e.g. the Heroku app that serves
13//! localthought.io), is a thin `main` around it. The public API is
14//! deliberately small:
15//!
16//! - [`Config`] — all runtime configuration, loaded with
17//!   [`Config::from_env`] from the environment variables documented in the
18//!   README.
19//! - [`build_app`] — loads the catalog, connects to PostgreSQL and returns the
20//!   ready-to-serve [`axum::Router`], for callers that bind or wrap it
21//!   themselves. [`build_app_with_access`] does the same with a custom
22//!   [`AccessPolicy`] (e.g. a SaaS account and tier lookup).
23//! - [`serve`] — [`build_app`] plus binding `0.0.0.0:{config.port}` and
24//!   serving until the listener fails.
25//! - [`run`] — what the bundled binary does: initialise `tracing` from
26//!   `RUST_LOG`, load [`Config::from_env`], [`serve`], and turn any
27//!   [`Error`] into a message on stderr and a failing exit code.
28//!
29//! A minimal wrapper binary is therefore:
30//!
31//! ```no_run
32//! #[tokio::main]
33//! async fn main() -> std::process::ExitCode {
34//!     atomic_integration_proxy::run().await
35//! }
36//! ```
37//!
38//! Everything else (route handlers, catalog composition, the security
39//! store) is private and may change in any release.
40
41mod access;
42mod agent_id;
43mod api_error;
44mod capability;
45mod catalog;
46mod client_addr;
47mod config;
48mod connect;
49mod connections;
50mod device;
51#[cfg(test)]
52mod identity_catalog_tests;
53mod oauth;
54mod pacing;
55mod providers;
56mod proxy;
57mod security;
58mod signature;
59mod templates;
60#[cfg(test)]
61mod test_support;
62mod webhooks;
63
64use std::sync::Arc;
65
66use axum::{
67    extract::{FromRef, State},
68    response::Html,
69    routing::{delete, get, post},
70    Router,
71};
72use axum_extra::extract::cookie::Key;
73use sha2::{Digest, Sha512};
74use tower_http::trace::TraceLayer;
75use tracing_subscriber::EnvFilter;
76
77pub use access::{Access, AccessPolicy, AllowAll, EnvAccessPolicy};
78pub use agent_id::{parse as parse_agent_id, AgentId};
79pub use config::{
80    Config, TrustForwardedFor, WebhookConfig, DEFAULT_CATALOG_PATH,
81    DEFAULT_KEY_CHECK_LIMIT_PER_HOUR, DEFAULT_OPERATOR_NAME, DEFAULT_WEBHOOK_INBOX_MAX_BYTES,
82};
83pub use device::DeviceConfig;
84
85#[derive(Clone)]
86struct AppState {
87    http_client: reqwest::Client,
88    key: Key,
89    /// `Config::base_url`, trailing `/` trimmed: the signed URL's prefix.
90    base_url: String,
91    /// `Config::public_origin`: a capability's `aud`, and the only `Origin`
92    /// accepted on the consent form.
93    public_origin: String,
94    catalog: catalog::Catalog,
95    device: DeviceConfig,
96    security: Option<security::Security>,
97    access: Arc<dyn AccessPolicy>,
98    /// `OPERATOR_NAME`, `OPERATOR_URL` and the `BASE_URL` host, for the pages.
99    operator: templates::Operator,
100    /// `KEY_CHECK_LIMIT_PER_HOUR` (0: off) and the window it counts over
101    /// (an hour; shorter only in tests).
102    key_check_limit: u32,
103    key_check_window: std::time::Duration,
104    /// `TRUST_FORWARDED_FOR`: where that limit finds the client address.
105    trust_forwarded_for: config::TrustForwardedFor,
106    /// The webhook inbox and its routes, only with `WEBHOOKS_ENABLED=true`.
107    webhooks: Option<Arc<webhooks::Webhooks>>,
108    /// The sliding logs pacing this instance's requests under providers'
109    /// `x-throttling` quotas on the proxy's own address (pieces.md P4).
110    pacer: Arc<pacing::Pacer>,
111    #[cfg(test)]
112    test_upstream: Option<String>,
113}
114
115/// The window [`AppState::key_check_limit`] counts over.
116const KEY_CHECK_WINDOW: std::time::Duration = std::time::Duration::from_secs(3600);
117
118impl FromRef<AppState> for Key {
119    fn from_ref(state: &AppState) -> Self {
120        state.key.clone()
121    }
122}
123
124pub(crate) fn now_secs() -> u64 {
125    std::time::SystemTime::now()
126        .duration_since(std::time::UNIX_EPOCH)
127        .expect("clock before epoch")
128        .as_secs()
129}
130
131pub(crate) fn now_ms() -> u64 {
132    std::time::SystemTime::now()
133        .duration_since(std::time::UNIX_EPOCH)
134        .expect("clock before epoch")
135        .as_millis() as u64
136}
137
138/// Asks the access policy about `owner`.
139pub(crate) async fn check_access(
140    state: &AppState,
141    owner: &AgentId,
142) -> Result<(), api_error::ApiError> {
143    match state.access.check(owner).await {
144        Access::Allowed => Ok(()),
145        Access::Denied(reason) => Err(api_error::ApiError::AccessDenied(reason)),
146    }
147}
148
149fn build_http_client() -> reqwest::Client {
150    // GitHub's REST API requires a User-Agent on every request. Redirects are
151    // disabled because only the initial target is validated against the
152    // catalog allowlist; a followed redirect would escape that validation.
153    // A bounded timeout keeps a stalled or slow upstream from holding the
154    // connection (and the caller's request) open indefinitely.
155    reqwest::Client::builder()
156        .user_agent("LocalThought-integration-proxy")
157        .redirect(reqwest::redirect::Policy::none())
158        .connect_timeout(std::time::Duration::from_secs(10))
159        .timeout(std::time::Duration::from_secs(30))
160        .build()
161        .expect("failed to build HTTP client")
162}
163
164/// A failure while starting or running the proxy. The [`std::fmt::Display`]
165/// form is the one-line message the binary prints before exiting.
166#[derive(Debug)]
167#[non_exhaustive]
168pub enum Error {
169    /// Missing or invalid environment configuration.
170    Config(String),
171    /// The catalog at `CATALOG_PATH` could not be loaded or composed.
172    Catalog(String),
173    /// The PostgreSQL connection or `ENCRYPTION_KEY` was rejected.
174    Security(String),
175    /// Binding the listening socket failed.
176    Bind {
177        /// The address that could not be bound.
178        addr: String,
179        /// The underlying I/O error.
180        source: std::io::Error,
181    },
182    /// The HTTP server stopped with an I/O error.
183    Serve(std::io::Error),
184}
185
186impl std::fmt::Display for Error {
187    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
188        match self {
189            Error::Config(err) => write!(f, "configuration error: {err}"),
190            Error::Catalog(err) => write!(f, "catalog configuration error: {err}"),
191            Error::Security(err) => write!(f, "security configuration error: {err}"),
192            Error::Bind { addr, source } => write!(f, "failed to bind {addr}: {source}"),
193            Error::Serve(err) => write!(f, "server error: {err}"),
194        }
195    }
196}
197
198impl std::error::Error for Error {
199    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
200        match self {
201            Error::Bind { source, .. } | Error::Serve(source) => Some(source),
202            _ => None,
203        }
204    }
205}
206
207/// Builds the complete application router from `config`, with the default
208/// [`EnvAccessPolicy`] (`REVOKED_SUBJECTS`, `ALLOWED_AGENTS`).
209pub async fn build_app(config: &Config) -> Result<Router, Error> {
210    let access = EnvAccessPolicy::new(
211        config.allowed_agents.clone(),
212        config.revoked_subjects.clone(),
213    );
214    build_app_with_access(config, Arc::new(access)).await
215}
216
217/// Builds the complete application router from `config`: the cookie key, the
218/// composed catalog (fetched from `config.catalog_path`, which may be an
219/// HTTPS URL) and the PostgreSQL-backed store, admitting connection owners
220/// through `access`. The returned router already carries CORS and request
221/// tracing layers.
222pub async fn build_app_with_access(
223    config: &Config,
224    access: Arc<dyn AccessPolicy>,
225) -> Result<Router, Error> {
226    let base_url = config::validate_base_url(&config.base_url).map_err(Error::Config)?;
227    config.device.validate().map_err(Error::Config)?;
228    let key = match &config.session_secret {
229        Some(secret) => Key::from(&Sha512::digest(secret.as_bytes())),
230        None => {
231            tracing::warn!(
232                "SESSION_SECRET is not set; using a random key. A consent screen open during a restart must be started again."
233            );
234            Key::generate()
235        }
236    };
237
238    let http_client = build_http_client();
239    let catalog = catalog::Catalog::load(&config.catalog_path, &http_client)
240        .await
241        .map_err(Error::Catalog)?;
242    let security = security::Security::connect(&config.database_url, &config.encryption_key)
243        .await
244        .map_err(Error::Security)?;
245    // Off by default: with WEBHOOKS_ENABLED unset there are no inbox tables,
246    // no sweeper and no webhook route.
247    let webhooks = webhooks::start(&config.webhooks, &config.database_url, &security, &catalog)
248        .await
249        .map_err(Error::Security)?;
250    if config.key_check_limit_per_hour > 0
251        && config.trust_forwarded_for == config::TrustForwardedFor::None
252        && std::env::var_os("DYNO").is_some()
253    {
254        // Heroku sets `DYNO`. There every peer address is the router's, so
255        // without `TRUST_FORWARDED_FOR=heroku` all clients share one limit.
256        tracing::warn!(
257            "running on Heroku without TRUST_FORWARDED_FOR=heroku: the key-check limit counts the router's address, so all clients share it"
258        );
259    }
260
261    let state = AppState {
262        http_client,
263        key,
264        base_url,
265        public_origin: config.public_origin(),
266        catalog,
267        device: config.device.clone(),
268        security: Some(security),
269        access,
270        operator: templates::Operator::from_config(config),
271        key_check_limit: config.key_check_limit_per_hour,
272        key_check_window: KEY_CHECK_WINDOW,
273        trust_forwarded_for: config.trust_forwarded_for,
274        webhooks,
275        pacer: Arc::default(),
276        #[cfg(test)]
277        test_upstream: None,
278    };
279    if let Some(webhooks) = &state.webhooks {
280        webhooks::sweeper::spawn(
281            webhooks.store.clone(),
282            webhooks::provider::ProviderHookDeleter {
283                state: state.clone(),
284            },
285        );
286    }
287
288    Ok(router(state))
289}
290
291/// Runs [`build_app`] and serves it on `0.0.0.0:{config.port}` until the
292/// server fails; under normal operation it does not return. Each request
293/// carries its peer address (`ConnectInfo<SocketAddr>`), which the key-check
294/// limit counts unless `TRUST_FORWARDED_FOR` says otherwise. A caller that
295/// serves [`build_app`]'s router itself should do the same
296/// (`into_make_service_with_connect_info::<SocketAddr>()`); without it, and
297/// without a trusted `X-Forwarded-For`, every client shares one limit.
298pub async fn serve(config: Config) -> Result<(), Error> {
299    let app = build_app(&config).await?;
300
301    let addr = format!("0.0.0.0:{}", config.port);
302    tracing::info!("integration-proxy listening on http://{addr}");
303
304    let listener = tokio::net::TcpListener::bind(&addr)
305        .await
306        .map_err(|source| Error::Bind {
307            addr: addr.clone(),
308            source,
309        })?;
310    axum::serve(
311        listener,
312        app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
313    )
314    .await
315    .map_err(Error::Serve)
316}
317
318/// The bundled binary's entry point: installs a `tracing` subscriber
319/// filtered by `RUST_LOG` (default `info`; skipped if the caller already
320/// installed one), loads [`Config::from_env`] and runs [`serve`]. Any
321/// [`Error`] is printed to stderr and reported as a failing exit code.
322pub async fn run() -> std::process::ExitCode {
323    let _ = tracing_subscriber::fmt()
324        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
325        .try_init();
326
327    let result = match Config::from_env() {
328        Ok(config) => serve(config).await,
329        Err(err) => Err(Error::Config(err)),
330    };
331    match result {
332        Ok(()) => std::process::ExitCode::SUCCESS,
333        Err(err) => {
334            eprintln!("{err}");
335            std::process::ExitCode::FAILURE
336        }
337    }
338}
339
340// Signatures and capabilities are supplied explicitly by the caller, never
341// as cookies, so any origin may call, including a plugin's null-origin
342// frame. Never enable cookie credentials: consent remains a top-level
343// navigation.
344fn browser_cors() -> tower_http::cors::CorsLayer {
345    use axum::http::{header, HeaderName, Method};
346    use tower_http::cors::{Any, CorsLayer};
347    CorsLayer::new()
348        .allow_origin(Any)
349        .allow_methods([
350            Method::GET,
351            Method::POST,
352            Method::PUT,
353            Method::PATCH,
354            Method::DELETE,
355            Method::OPTIONS,
356        ])
357        .allow_headers(
358            [
359                header::AUTHORIZATION,
360                HeaderName::from_static(proxy::IDEMPOTENCY_KEY),
361                HeaderName::from_static(signature::AGENT_HEADER),
362                HeaderName::from_static(signature::PUBLIC_KEY_HEADER),
363                HeaderName::from_static(signature::TIMESTAMP_HEADER),
364                HeaderName::from_static(signature::SIGNATURE_HEADER),
365                HeaderName::from_static(signature::VERSION_HEADER),
366            ]
367            .into_iter()
368            .chain(proxy::CALLER_HEADERS)
369            .collect::<Vec<_>>(),
370        )
371        // The same list the proxy forwards from, so they cannot drift.
372        .expose_headers(proxy::forwarded_response_headers().collect::<Vec<_>>())
373}
374
375fn router(state: AppState) -> Router {
376    // The webhook routes exist only while the inbox is on.
377    let webhook_routes = match &state.webhooks {
378        Some(_) => webhooks::routes::router(),
379        None => Router::new(),
380    };
381    Router::new()
382        .merge(webhook_routes)
383        .merge(device::router())
384        .route("/", get(home))
385        .route("/healthz", get(healthz))
386        .route("/logo.png", get(logo))
387        .route("/connect", get(connect::page))
388        .route("/connect/authorize", post(connect::authorize))
389        .route("/connect/redeem", post(connect::redeem))
390        .route("/connections", get(connections::list))
391        .route("/connections/:connection_id", delete(connections::delete))
392        .route(
393            "/connections/:connection_id/agents",
394            post(connections::add_agent),
395        )
396        .route(
397            "/connections/:connection_id/agents/:agent",
398            delete(connections::remove_agent),
399        )
400        .route("/runtimes", post(connections::add_runtime))
401        .route("/runtimes/:agent", delete(connections::remove_runtime))
402        .route(
403            "/proxy/:connection_id/:platform/*path",
404            axum::routing::any(proxy::forward),
405        )
406        .route("/oauth/:provider/callback", get(oauth::callback))
407        .route("/catalog", get(catalog::list))
408        .route("/catalog/:file", get(catalog::document))
409        .layer(browser_cors())
410        .layer(TraceLayer::new_for_http().make_span_with(|request: &axum::http::Request<_>| {
411            tracing::info_span!("http_request", method = %request.method(), path = request.uri().path())
412        }))
413        .with_state(state)
414}
415
416/// Reports whether the database is currently reachable, so an operator or
417/// load balancer can detect a still-recovering connection instead of only
418/// finding out from a failed request.
419async fn healthz(State(state): State<AppState>) -> impl axum::response::IntoResponse {
420    match &state.security {
421        Some(security) if security.is_ready().await => (axum::http::StatusCode::OK, "ok"),
422        _ => (
423            axum::http::StatusCode::SERVICE_UNAVAILABLE,
424            "database unavailable",
425        ),
426    }
427}
428
429async fn logo() -> impl axum::response::IntoResponse {
430    (
431        [
432            (axum::http::header::CONTENT_TYPE, "image/png"),
433            (axum::http::header::CACHE_CONTROL, "public, max-age=3600"),
434        ],
435        include_bytes!("../static/logo.png").as_slice(),
436    )
437}
438
439async fn home(State(state): State<AppState>) -> Html<String> {
440    Html(templates::render_home(&state.operator))
441}
442
443#[cfg(test)]
444mod browser_tests {
445    use super::*;
446    use axum::{
447        body::Body,
448        http::{Request, StatusCode},
449    };
450    use tower::ServiceExt;
451
452    #[tokio::test]
453    async fn a_null_origin_frame_may_preflight_signed_proxy_requests() {
454        let app = test_support::router_without_database();
455        let response = app
456            .clone()
457            .oneshot(
458                Request::builder()
459                    .method("OPTIONS")
460                    .uri("/proxy/conn/pets/pets")
461                    .header("origin", "null")
462                    .header("access-control-request-method", "PATCH")
463                    .header(
464                        "access-control-request-headers",
465                        "authorization,content-type,if-match,if-none-match,if-modified-since,idempotency-key,x-atomic-agent,x-atomic-public-key,x-atomic-timestamp,x-atomic-signature,x-atomic-signature-version",
466                    )
467                    .body(Body::empty())
468                    .unwrap(),
469            )
470            .await
471            .unwrap();
472        assert_eq!(response.status(), StatusCode::OK);
473        assert_eq!(response.headers()["access-control-allow-origin"], "*");
474        let allowed = response.headers()["access-control-allow-headers"]
475            .to_str()
476            .unwrap()
477            .to_owned();
478        for name in [
479            "authorization",
480            "content-type",
481            "if-match",
482            "if-none-match",
483            "if-modified-since",
484            "idempotency-key",
485            "x-atomic-agent",
486            "x-atomic-public-key",
487            "x-atomic-timestamp",
488            "x-atomic-signature",
489            "x-atomic-signature-version",
490        ] {
491            assert!(allowed.contains(name), "{name} not in {allowed}");
492        }
493        assert!(!response
494            .headers()
495            .contains_key("access-control-allow-credentials"));
496        let response = app
497            .oneshot(
498                Request::builder()
499                    .uri("/catalog")
500                    .header("origin", "null")
501                    .body(Body::empty())
502                    .unwrap(),
503            )
504            .await
505            .unwrap();
506        let exposed = response.headers()["access-control-expose-headers"]
507            .to_str()
508            .unwrap();
509        let exposed: Vec<&str> = exposed.split(',').map(str::trim).collect();
510        for name in [
511            "link",
512            "retry-after",
513            "etag",
514            "content-type",
515            "last-modified",
516            "x-total-count",
517            "x-next-page",
518        ]
519        .into_iter()
520        .chain(proxy::RATE_LIMIT_HEADERS)
521        {
522            assert!(exposed.contains(&name), "{name} not in {exposed:?}");
523        }
524        assert!(!exposed.contains(&"x-connection-code"));
525        assert!(!exposed.contains(&"set-cookie"));
526    }
527}