fedimint_gateway_server/

iroh_server.rs

use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::panic::AssertUnwindSafe;
use std::pin::Pin;
use std::sync::Arc;

use anyhow::anyhow;
use axum::extract::{Path, Query};
use axum::{Extension, Json};
use bitcoin::hashes::sha256;
use fedimint_core::module::{FEDIMINT_GATEWAY_ALPN, IrohGatewayRequest, IrohGatewayResponse};
use fedimint_core::net::iroh::build_iroh_endpoint;
use fedimint_core::task::TaskGroup;
use fedimint_core::util::FmtCompactAnyhow as _;
use fedimint_gateway_common::STOP_ENDPOINT;
use fedimint_logging::LOG_GATEWAY;
use futures::FutureExt as _;
use iroh::endpoint::Incoming;
use reqwest::StatusCode;
use serde::de::DeserializeOwned;
use serde_json::json;
use tracing::{error, info, warn};
use url::Url;

use crate::error::{GatewayError, PublicGatewayError};
use crate::rpc_server::verify_bolt11_preimage_v2_get;
use crate::{Gateway, GatewayState};

/// Handler for a GET request, which must contain no parameters and return
/// `serde_json::Value`
type GetHandler = Box<
    dyn Fn(
            Extension<Arc<Gateway>>,
        )
            -> Pin<Box<dyn Future<Output = Result<Json<serde_json::Value>, GatewayError>> + Send>>
        + Send
        + Sync,
>;

/// Handler for a POST request, which must contain `serde_json::Value` encoded
/// parameters and return `serde_json::Value`.
type PostHandler = Box<
    dyn Fn(
            Extension<Arc<Gateway>>,
            serde_json::Value,
        )
            -> Pin<Box<dyn Future<Output = Result<Json<serde_json::Value>, GatewayError>> + Send>>
        + Send
        + Sync,
>;

/// Creates a GET handler for the Iroh endpoint by wrapping it in a closure.
fn make_get_handler<F, Fut>(f: F) -> GetHandler
where
    F: Fn(Extension<Arc<Gateway>>) -> Fut + Clone + Send + Sync + 'static,
    Fut: Future<Output = Result<Json<serde_json::Value>, GatewayError>> + Send + 'static,
{
    Box::new(move |gateway: Extension<Arc<Gateway>>| {
        let f = f.clone();
        Box::pin(async move {
            let res = f(gateway).await?;
            Ok(res)
        })
    })
}

/// Creates a POST handler for the Iroh endpoint by wrapping it in a closure.
fn make_post_handler<P, F, Fut>(f: F) -> PostHandler
where
    P: DeserializeOwned + Send + 'static,
    F: Fn(Extension<Arc<Gateway>>, Json<P>) -> Fut + Clone + Send + Sync + 'static,
    Fut: Future<Output = Result<Json<serde_json::Value>, GatewayError>> + Send + 'static,
{
    Box::new(
        move |gateway: Extension<Arc<Gateway>>, value: serde_json::Value| {
            let f = f.clone();
            Box::pin(async move {
                let payload: P = serde_json::from_value(value)
                    .map_err(|e| PublicGatewayError::Unexpected(anyhow!(e.to_string())))?;
                let res = f(gateway, Json(payload)).await?;
                Ok(res)
            })
        },
    )
}

/// Helper struct for registering handlers that are called by the Iroh
/// `Endpoint`. GET handlers and POST handlers are registered separately, since
/// they contain different function signatures. If a route is authenticated, it
/// is also stored in `authenticated_routes` which is checked when the specific
/// handler is called.
pub struct Handlers {
    get_handlers: BTreeMap<String, GetHandler>,
    post_handlers: BTreeMap<String, PostHandler>,
    authenticated_routes: BTreeSet<String>,
}

impl Handlers {
    pub fn new() -> Self {
        let mut authenticated_routes = BTreeSet::new();
        authenticated_routes.insert(STOP_ENDPOINT.to_string());
        Handlers {
            get_handlers: BTreeMap::new(),
            post_handlers: BTreeMap::new(),
            authenticated_routes,
        }
    }

    pub fn add_handler<F, Fut>(&mut self, route: &str, f: F, is_authenticated: bool)
    where
        F: Fn(Extension<Arc<Gateway>>) -> Fut + Clone + Send + Sync + 'static,
        Fut: Future<Output = Result<Json<serde_json::Value>, GatewayError>> + Send + 'static,
    {
        if is_authenticated {
            self.authenticated_routes.insert(route.to_string());
        }
        self.get_handlers
            .insert(route.to_string(), make_get_handler(f));
    }

    pub fn get_handler(&self, route: &str) -> Option<&GetHandler> {
        self.get_handlers.get(route)
    }

    pub fn add_handler_with_payload<P, F, Fut>(&mut self, route: &str, f: F, is_authenticated: bool)
    where
        P: DeserializeOwned + Send + 'static,
        F: Fn(Extension<Arc<Gateway>>, Json<P>) -> Fut + Clone + Send + Sync + 'static,
        Fut: Future<Output = Result<Json<serde_json::Value>, GatewayError>> + Send + 'static,
    {
        if is_authenticated {
            self.authenticated_routes.insert(route.to_string());
        }

        self.post_handlers
            .insert(route.to_string(), make_post_handler(f));
    }

    pub fn get_handler_with_payload(&self, route: &str) -> Option<&PostHandler> {
        self.post_handlers.get(route)
    }

    pub fn is_authenticated(&self, route: &str) -> bool {
        self.authenticated_routes.contains(route)
    }
}

/// Create the Iroh `Endpoint` and spawn a thread that starts listening for
/// requests.
pub async fn start_iroh_endpoint(
    gateway: &Arc<Gateway>,
    task_group: TaskGroup,
    handlers: Arc<Handlers>,
) -> anyhow::Result<()> {
    if let Some(iroh_listen) = gateway.iroh_listen {
        info!("Building Iroh Endpoint...");
        let iroh_endpoint = build_iroh_endpoint(
            gateway.iroh_sk.clone(),
            iroh_listen,
            gateway.iroh_dns.clone(),
            gateway.iroh_relays.clone(),
            FEDIMINT_GATEWAY_ALPN,
        )
        .await?;
        let gw_clone = gateway.clone();
        let tg_clone = task_group.clone();
        let handlers_clone = handlers.clone();
        info!("Spawning accept loop...");
        task_group.spawn("Gateway Iroh", |_| async move {
            while let Some(incoming) = iroh_endpoint.accept().await {
                info!("Accepted new connection. Spawning handler...");
                tg_clone.spawn_cancellable_silent(
                    "handle endpoint accept",
                    handle_incoming_iroh_request(
                        incoming,
                        gw_clone.clone(),
                        handlers_clone.clone(),
                        tg_clone.clone(),
                    ),
                );
            }
        });

        info!(target: LOG_GATEWAY, "Successfully started iroh endpoint");
    }

    Ok(())
}

/// Handle a specific Iroh request. The request must be deserialized, matched to
/// a handler, executed, then return a response to the caller.
async fn handle_incoming_iroh_request(
    incoming: Incoming,
    gateway: Arc<Gateway>,
    handlers: Arc<Handlers>,
    task_group: TaskGroup,
) -> anyhow::Result<()> {
    let connection = incoming.accept()?.await?;
    let remote_node_id = &connection.remote_node_id()?;
    info!(%remote_node_id, "Handler received connection");
    while let Ok((mut send, mut recv)) = connection.accept_bi().await {
        let request = recv.read_to_end(100_000).await?;
        let request = serde_json::from_slice::<IrohGatewayRequest>(&request)?;

        let (status, body) = run_handler(
            &request.route,
            handle_request(
                &request,
                gateway.clone(),
                handlers.clone(),
                task_group.clone(),
            ),
        )
        .await;

        let response = IrohGatewayResponse {
            status: status.as_u16(),
            body: body.0,
        };
        let response = serde_json::to_vec(&response)?;

        send.write_all(&response).await?;
        send.finish()?;
    }
    Ok(())
}

/// Runs a request handler, turning a panic or an error into a 500 response for
/// the caller that triggered it.
///
/// Iroh requests are spawned on the gateway's root task group, so a panic
/// escaping a handler trips the task group's panic guard and shuts the whole
/// gateway down. The HTTP path does not need this: `axum::serve` spawns its
/// connection tasks outside any task group, so a panic there only drops that
/// one connection.
///
/// A failing handler has to be answered as well: propagating the error would
/// end the connection's request loop, leaving the caller with a closed stream
/// and no response at all. Like the HTTP path, the response body carries no
/// details about the failure, since callers are unauthenticated.
async fn run_handler(
    route: &str,
    handler: impl Future<Output = anyhow::Result<(StatusCode, Json<serde_json::Value>)>>,
) -> (StatusCode, Json<serde_json::Value>) {
    // Using `AssertUnwindSafe` here is far from ideal. In theory this means we
    // could end up with an inconsistent state. In practice this is only the last
    // line of defense, and losing the gateway process entirely is strictly worse.
    let result = AssertUnwindSafe(handler)
        .catch_unwind()
        .await
        .unwrap_or_else(|_| {
            error!(
                target: LOG_GATEWAY,
                route,
                "Gateway API handler panicked, DO NOT IGNORE, FIX IT!!!"
            );

            Ok((StatusCode::INTERNAL_SERVER_ERROR, Json(json!(()))))
        });

    result.unwrap_or_else(|err| {
        warn!(
            target: LOG_GATEWAY,
            route,
            err = %err.fmt_compact_anyhow(),
            "Gateway API handler returned an error"
        );

        (StatusCode::INTERNAL_SERVER_ERROR, Json(json!(())))
    })
}

/// Checks if the requested route is authenticated and will reject the request
/// if the authentication is incorrect. Then it will lookup the specific handler
/// in `Handlers`, execute it, and return the function's JSON along with an HTTP
/// status code.
pub(crate) async fn handle_request(
    request: &IrohGatewayRequest,
    gateway: Arc<Gateway>,
    handlers: Arc<Handlers>,
    task_group: TaskGroup,
) -> anyhow::Result<(StatusCode, Json<serde_json::Value>)> {
    if matches!(
        gateway.get_state().await,
        GatewayState::NotConfigured { .. }
    ) && !crate::rpc_server::is_allowed_not_configured_api(
        &axum::http::Method::POST,
        &request.route,
    ) {
        return Ok(unknown_route(&request.route));
    }

    if handlers.is_authenticated(&request.route) && iroh_verify_password(&gateway, request).is_err()
    {
        return Ok((StatusCode::UNAUTHORIZED, Json(json!(()))));
    }

    // The STOP endpoint is handled outside of the `Handlers` struct since it has a
    // different function signature (it needs a `TaskGroup`).
    if request.route == STOP_ENDPOINT {
        let body = crate::rpc_server::stop(Extension(task_group), Extension(gateway)).await?;
        return Ok((StatusCode::OK, body));
    }

    // The handlers struct also currently does not support query parameters. The
    // LNURL-verify endpoint is the only endpoint that requires these, so we
    // handle these separately as well.
    if let Some(verify_route) = parse_verify_route(&request.route) {
        let Ok((payment_hash, query_map)) = verify_route else {
            // The route is the caller's input, so a payment hash we cannot parse is
            // their mistake, the same way the HTTP path's `Path<sha256::Hash>`
            // extractor rejects a malformed payment hash.
            return Ok((StatusCode::BAD_REQUEST, Json(json!(()))));
        };

        let body =
            verify_bolt11_preimage_v2_get(Extension(gateway), Path(payment_hash), Query(query_map))
                .await?;

        return Ok((StatusCode::OK, body));
    }

    let (status, body) = if let Some(params) = &request.params {
        let Some(handler) = handlers.get_handler_with_payload(&request.route) else {
            return Ok(unknown_route(&request.route));
        };

        (
            StatusCode::OK,
            handler(Extension(gateway), params.clone()).await?,
        )
    } else {
        let Some(handler) = handlers.get_handler(&request.route) else {
            return Ok(unknown_route(&request.route));
        };

        (StatusCode::OK, handler(Extension(gateway)).await?)
    };

    Ok((status, body))
}

/// Response for a route that no handler is registered for.
fn unknown_route(route: &str) -> (StatusCode, Json<serde_json::Value>) {
    warn!(
        target: LOG_GATEWAY,
        route,
        "Iroh handler received request with unknown route"
    );

    (StatusCode::NOT_FOUND, Json(json!(())))
}

/// Parses the LNURL-verify route `/verify/{payment_hash}` into the payment hash
/// and the query parameters (`?wait`) of the request.
///
/// Returns `None` if the route is not shaped like the verify route at all, so
/// that the caller falls through to the regular handler lookup and answers with
/// a 404. Only the exact `/verify/{payment_hash}` shape is this endpoint, the
/// same way the HTTP path registers it as an exact route: neither a route that
/// merely starts with `/verify` nor one that appends further path segments may
/// reach this unauthenticated handler.
fn parse_verify_route(
    route: &str,
) -> Option<anyhow::Result<(sha256::Hash, HashMap<String, String>)>> {
    // Check the prefix on the raw route, so that a route the URL parser below
    // normalizes into the verify route (`/../verify/{payment_hash}`) is not this
    // endpoint either.
    if !route.starts_with("/verify/") {
        return None;
    }

    // Use dummy URL for easier parsing
    let url = Url::parse(&format!("http://localhost{route}")).ok()?;

    // Extract segments: /verify/<payment_hash>. The first segment is the route
    // prefix itself, so the payment hash is the second one, and there must not be
    // a third. The prefix is re-checked here because the raw route may normalize
    // to a different path (`/verify/../stop`).
    let mut segments = url.path_segments()?;

    if segments.next() != Some("verify") {
        return None;
    }

    let hash_str = segments.next()?;

    if segments.next().is_some() {
        return None;
    }

    let payment_hash = match hash_str.parse::<sha256::Hash>() {
        Ok(payment_hash) => payment_hash,
        Err(err) => return Some(Err(anyhow!(err).context("Invalid payment hash"))),
    };

    // Parse query params (?wait etc.)
    let query_map: HashMap<String, String> = url.query_pairs().into_owned().collect();

    Some(Ok((payment_hash, query_map)))
}

/// Verifies if the supplied password in the Iroh request matches the gateway's
/// password
fn iroh_verify_password(
    gateway: &Arc<Gateway>,
    request: &IrohGatewayRequest,
) -> anyhow::Result<()> {
    if let Some(password) = request.password.as_ref()
        && bcrypt::verify(password, &gateway.bcrypt_password_hash)?
    {
        return Ok(());
    }

    Err(anyhow!("Invalid password"))
}

#[cfg(test)]
mod tests {
    use bitcoin::hashes::Hash as _;

    use super::*;

    #[tokio::test]
    async fn panicking_handler_returns_an_error_instead_of_unwinding() {
        let (status, _body) = run_handler("/pay_invoice", async { panic!("handler panic") }).await;

        assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR);
    }

    #[tokio::test]
    async fn failing_handler_is_answered_instead_of_ending_the_connection() {
        let (status, _body) = run_handler("/verify/nonsense", async {
            Err(anyhow!("Verify route does not contain a payment hash"))
        })
        .await;

        assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR);
    }

    #[test]
    fn verify_route_parses_the_payment_hash_not_the_route_prefix() {
        let payment_hash = sha256::Hash::hash(b"payment hash");

        let (parsed_hash, _query) = parse_verify_route(&format!("/verify/{payment_hash}"))
            .expect("the route is the verify route")
            .expect("the payment hash is the second path segment, not the first");

        assert_eq!(parsed_hash, payment_hash);
    }

    #[test]
    fn verify_route_parses_the_wait_query_parameter() {
        let payment_hash = sha256::Hash::hash(b"payment hash");

        let (parsed_hash, query) = parse_verify_route(&format!("/verify/{payment_hash}?wait"))
            .expect("the route is the verify route")
            .expect("query parameters do not affect path parsing");

        assert_eq!(parsed_hash, payment_hash);
        assert!(query.contains_key("wait"));
    }

    #[test]
    fn verify_route_with_a_malformed_payment_hash_is_rejected() {
        parse_verify_route("/verify/")
            .expect("the route is shaped like the verify route")
            .expect_err("a route with an empty payment hash has nothing to verify");
        parse_verify_route("/verify/not-a-payment-hash")
            .expect("the route is shaped like the verify route")
            .expect_err("a payment hash that is not a sha256 hash is rejected");
    }

    #[test]
    fn only_the_exact_verify_route_reaches_the_verify_endpoint() {
        let payment_hash = sha256::Hash::hash(b"payment hash");

        // A route that is not exactly `/verify/{payment_hash}` is not this endpoint,
        // no matter that it starts with `/verify` or contains a valid payment hash
        // somewhere. Falling through to the handler lookup answers it with a 404,
        // like the HTTP path's exact route does.
        for route in [
            "/verify".to_string(),
            format!("/verifyfoo/{payment_hash}"),
            format!("/verify_something/{payment_hash}?wait"),
            format!("/verify/{payment_hash}/extra"),
            // Routes the URL parser normalizes are not the verify route either,
            // whether they normalize into it or out of it.
            format!("/../verify/{payment_hash}"),
            format!("/verify/{payment_hash}/../../stop"),
            "/verify/../stop".to_string(),
        ] {
            assert!(
                parse_verify_route(&route).is_none(),
                "{route} must not reach the unauthenticated verify handler"
            );
        }
    }
}