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