mpp 0.14.0

//! Server-side transport abstraction.
//!
//! Abstracts how challenges are issued and credentials are received
//! across different transport protocols (HTTP, WebSocket, MCP, etc.).
//!
//! This matches the mppx `Transport` interface from `mppx/server`.
//!
//! # Built-in transports
//!
//! - [`http()`]: HTTP transport (Authorization/WWW-Authenticate headers)
//!
//! # Custom transports
//!
//! Implement [`Transport`] for custom protocols:
//!
//! ```ignore
//! use mpp::server::transport::{Transport, ChallengeContext};
//! use mpp::protocol::core::{PaymentChallenge, PaymentCredential, Receipt};
//!
//! struct MyTransport;
//!
//! impl Transport for MyTransport {
//!     type Input = MyRequest;
//!     type ChallengeOutput = MyResponse;
//!     type ReceiptOutput = MyResponse;
//!
//!     fn name(&self) -> &str { "custom" }
//!     // ...
//! }
//! ```

use crate::error::MppError;
use crate::protocol::core::{
    with_private_cache_control, PaymentChallenge, PaymentCredential, Receipt,
};

/// Context passed to [`Transport::respond_challenge`].
pub struct ChallengeContext<'a, I> {
    /// The payment challenge to send to the client.
    pub challenge: &'a PaymentChallenge,
    /// The original transport input (e.g., HTTP request).
    pub input: &'a I,
    /// Optional error message for the client.
    pub error: Option<&'a str>,
}

/// Context passed to [`Transport::respond_receipt`].
pub struct ReceiptContext<'a, R> {
    /// The challenge ID this receipt corresponds to.
    pub challenge_id: &'a str,
    /// The payment receipt.
    pub receipt: &'a Receipt,
    /// The application response to attach the receipt to.
    pub response: R,
}

/// Server-side transport trait.
///
/// Abstracts how the server extracts credentials from incoming requests,
/// issues payment challenges, and attaches receipts to responses.
pub trait Transport: Send + Sync {
    /// The incoming request/message type (e.g., `http::Request<Body>`).
    type Input;
    /// The response type for payment challenges (e.g., `http::Response<Body>`).
    type ChallengeOutput;
    /// The response type after attaching a receipt.
    type ReceiptOutput;

    /// Transport name for identification (e.g., "http", "ws", "mcp").
    fn name(&self) -> &str;

    /// Extract a payment credential from the transport input.
    ///
    /// Returns `Ok(Some(credential))` if a valid credential is present,
    /// `Ok(None)` if no credential was provided (trigger challenge),
    /// or `Err` if the credential is malformed.
    fn get_credential(&self, input: &Self::Input) -> Result<Option<PaymentCredential>, MppError>;

    /// Create a transport response for a payment challenge.
    fn respond_challenge(&self, ctx: ChallengeContext<'_, Self::Input>) -> Self::ChallengeOutput;

    /// Attach a receipt to a successful response.
    fn respond_receipt(&self, ctx: ReceiptContext<'_, Self::ReceiptOutput>) -> Self::ReceiptOutput;
}

/// HTTP transport for server-side payment handling.
///
/// - Reads credentials from `Authorization`, or from `Payment-Authorization`
///   when constructed with [`HttpTransport::requires_auth`]
/// - Issues challenges via `WWW-Authenticate` header with 402 status
/// - Attaches receipts via `Payment-Receipt` header
///
/// This is the default transport, matching mppx's `Transport.http()`.
#[derive(Debug, Clone, Copy, Default)]
pub struct HttpTransport {
    requires_auth: bool,
}

/// Create an HTTP transport instance.
pub fn http() -> HttpTransport {
    HttpTransport {
        requires_auth: false,
    }
}

impl HttpTransport {
    /// Use `Payment-Authorization` for Payment credentials so `Authorization`
    /// remains available for application authentication.
    pub fn requires_auth(mut self, enabled: bool) -> Self {
        self.requires_auth = enabled;
        self
    }

    fn credential_header(&self) -> &'static str {
        if self.requires_auth {
            crate::protocol::core::PAYMENT_AUTHORIZATION_HEADER
        } else {
            http_types::header::AUTHORIZATION.as_str()
        }
    }
}

impl Transport for HttpTransport {
    type Input = http_types::Request<()>;
    type ChallengeOutput = http_types::Response<String>;
    type ReceiptOutput = http_types::Response<String>;

    fn name(&self) -> &str {
        "http"
    }

    fn get_credential(&self, input: &Self::Input) -> Result<Option<PaymentCredential>, MppError> {
        let Some(header) = input.headers().get(self.credential_header()) else {
            return Ok(None);
        };

        let header_str = header
            .to_str()
            .map_err(|e| MppError::MalformedCredential(Some(format!("invalid header: {e}"))))?;

        let Some(payment) = crate::protocol::core::extract_payment_scheme(header_str) else {
            return Ok(None);
        };

        // extract_payment_scheme returns the full "Payment ..." fragment
        let credential = crate::protocol::core::parse_authorization(payment).map_err(|e| {
            MppError::MalformedCredential(Some(format!("failed to parse credential: {e}")))
        })?;

        Ok(Some(credential))
    }

    fn respond_challenge(&self, ctx: ChallengeContext<'_, Self::Input>) -> Self::ChallengeOutput {
        let www_auth = crate::protocol::core::format_www_authenticate(ctx.challenge)
            .unwrap_or_else(|_| "Payment".to_string());

        let body = match ctx.error {
            Some(msg) => serde_json::json!({ "error": msg }).to_string(),
            None => serde_json::json!({ "error": "Payment Required" }).to_string(),
        };

        let mut resp = http_types::Response::builder()
            .status(http_types::StatusCode::PAYMENT_REQUIRED)
            .header(http_types::header::WWW_AUTHENTICATE, &www_auth)
            .header(http_types::header::CONTENT_TYPE, "application/json")
            .body(body)
            .expect("response builder cannot fail");

        // Add Cache-Control: no-store to prevent caching of challenges
        resp.headers_mut().insert(
            http_types::header::CACHE_CONTROL,
            http_types::HeaderValue::from_static("no-store"),
        );

        resp
    }

    fn respond_receipt(&self, ctx: ReceiptContext<'_, Self::ReceiptOutput>) -> Self::ReceiptOutput {
        let receipt_header =
            crate::protocol::core::format_receipt(ctx.receipt).unwrap_or_else(|_| String::new());

        let mut resp = ctx.response;

        // Receipt responses MUST be Cache-Control: private (spec §11.10),
        // merged across any existing directives.
        let existing_cc = resp
            .headers()
            .get_all(http_types::header::CACHE_CONTROL)
            .iter()
            .filter_map(|v| v.to_str().ok())
            .collect::<Vec<_>>()
            .join(", ");
        let cache_control = with_private_cache_control(Some(existing_cc.as_str()));
        if let Ok(value) = http_types::HeaderValue::from_str(&cache_control) {
            resp.headers_mut()
                .insert(http_types::header::CACHE_CONTROL, value);
        }

        if let Ok(value) = http_types::HeaderValue::from_str(&receipt_header) {
            resp.headers_mut()
                .insert(crate::protocol::core::PAYMENT_RECEIPT_HEADER, value);
        }
        resp
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_http_transport_name() {
        let transport = http();
        assert_eq!(transport.name(), "http");
    }

    #[test]
    fn test_http_get_credential_none() {
        let transport = http();
        let req = http_types::Request::builder()
            .uri("/test")
            .body(())
            .unwrap();
        let result = transport.get_credential(&req).unwrap();
        assert!(result.is_none());
    }

    #[test]
    fn test_http_get_credential_non_payment_auth() {
        let transport = http();
        let req = http_types::Request::builder()
            .uri("/test")
            .header("Authorization", "Bearer some-token")
            .body(())
            .unwrap();
        let result = transport.get_credential(&req).unwrap();
        assert!(result.is_none());
    }

    #[test]
    fn test_http_get_credential_valid_payment() {
        let transport = http();

        // Build a valid Payment authorization header
        let challenge = PaymentChallenge::new(
            "test-id",
            "test.example.com",
            "tempo",
            "charge",
            crate::protocol::core::Base64UrlJson::from_value(
                &serde_json::json!({"amount": "1000"}),
            )
            .unwrap(),
        );
        let credential = crate::protocol::core::PaymentCredential::new(
            challenge.to_echo(),
            crate::protocol::core::PaymentPayload::hash("0xdeadbeef"),
        );
        let auth_header = crate::protocol::core::format_authorization(&credential).unwrap();

        let req = http_types::Request::builder()
            .uri("/test")
            .header("Authorization", &auth_header)
            .body(())
            .unwrap();

        let result = transport.get_credential(&req).unwrap();
        assert!(result.is_some(), "should parse valid Payment credential");
        let parsed = result.unwrap();
        assert_eq!(parsed.challenge.id, "test-id");
    }

    #[test]
    fn test_http_get_credential_from_payment_authorization() {
        let transport = http().requires_auth(true);

        let mut challenge = PaymentChallenge::new(
            "test-id",
            "test.example.com",
            "tempo",
            "charge",
            crate::protocol::core::Base64UrlJson::from_value(
                &serde_json::json!({"amount": "1000"}),
            )
            .unwrap(),
        );
        challenge.header = Some("Payment-Authorization".to_string());
        let credential = crate::protocol::core::PaymentCredential::new(
            challenge.to_echo(),
            crate::protocol::core::PaymentPayload::hash("0xdeadbeef"),
        );
        let auth_header = crate::protocol::core::format_authorization(&credential).unwrap();

        let req = http_types::Request::builder()
            .uri("/test")
            .header("Authorization", "Bearer ordinary-authentication")
            .header("Payment-Authorization", &auth_header)
            .body(())
            .unwrap();

        let result = transport.get_credential(&req).unwrap();
        assert!(
            result.is_some(),
            "should parse Payment-Authorization credential"
        );
        let parsed = result.unwrap();
        assert_eq!(parsed.challenge.id, "test-id");
    }

    #[test]
    fn test_http_respond_challenge() {
        let transport = http();
        let challenge = PaymentChallenge::new(
            "test-id",
            "test.example.com",
            "tempo",
            "charge",
            crate::protocol::core::Base64UrlJson::from_value(
                &serde_json::json!({"amount": "1000"}),
            )
            .unwrap(),
        );
        let req = http_types::Request::builder()
            .uri("/test")
            .body(())
            .unwrap();

        let resp = transport.respond_challenge(ChallengeContext {
            challenge: &challenge,
            input: &req,
            error: None,
        });

        assert_eq!(resp.status(), http_types::StatusCode::PAYMENT_REQUIRED);
        assert!(resp
            .headers()
            .get(http_types::header::WWW_AUTHENTICATE)
            .is_some());
        assert!(resp.body().contains("Payment Required"));
    }

    #[test]
    fn test_http_respond_challenge_with_error() {
        let transport = http();
        let challenge = PaymentChallenge::new(
            "test-id",
            "test.example.com",
            "tempo",
            "charge",
            crate::protocol::core::Base64UrlJson::from_value(
                &serde_json::json!({"amount": "1000"}),
            )
            .unwrap(),
        );
        let req = http_types::Request::builder()
            .uri("/test")
            .body(())
            .unwrap();

        let resp = transport.respond_challenge(ChallengeContext {
            challenge: &challenge,
            input: &req,
            error: Some("Verification failed"),
        });

        assert_eq!(resp.status(), http_types::StatusCode::PAYMENT_REQUIRED);
        assert!(resp.body().contains("Verification failed"));
    }

    #[test]
    fn test_http_respond_receipt() {
        let transport = http();
        let receipt = Receipt::success("tempo", "0xabc123");

        let resp = http_types::Response::builder()
            .status(http_types::StatusCode::OK)
            .body("ok".to_string())
            .unwrap();

        let resp = transport.respond_receipt(ReceiptContext {
            challenge_id: "ch-1",
            receipt: &receipt,
            response: resp,
        });

        assert_eq!(resp.status(), http_types::StatusCode::OK);
        assert!(resp
            .headers()
            .get(crate::protocol::core::PAYMENT_RECEIPT_HEADER)
            .is_some());
        // Per spec, receipt responses must be Cache-Control: private.
        assert_eq!(
            resp.headers()
                .get(http_types::header::CACHE_CONTROL)
                .unwrap(),
            "private"
        );
    }

    #[test]
    fn test_http_respond_receipt_merges_existing_cache_control() {
        let transport = http();
        let receipt = Receipt::success("tempo", "0xabc123");

        let resp = http_types::Response::builder()
            .status(http_types::StatusCode::OK)
            .header(http_types::header::CACHE_CONTROL, "no-store")
            .body("ok".to_string())
            .unwrap();

        let resp = transport.respond_receipt(ReceiptContext {
            challenge_id: "ch-1",
            receipt: &receipt,
            response: resp,
        });

        // Existing directive preserved, `private` appended (not overwritten).
        assert_eq!(
            resp.headers()
                .get(http_types::header::CACHE_CONTROL)
                .unwrap(),
            "no-store, private"
        );
    }

    #[test]
    fn test_http_respond_receipt_merges_multiple_cache_control_values() {
        let transport = http();
        let receipt = Receipt::success("tempo", "0xabc123");

        // Two separate Cache-Control header lines (both valid HTTP).
        let resp = http_types::Response::builder()
            .status(http_types::StatusCode::OK)
            .header(http_types::header::CACHE_CONTROL, "no-cache")
            .header(http_types::header::CACHE_CONTROL, "max-age=60")
            .body("ok".to_string())
            .unwrap();

        let resp = transport.respond_receipt(ReceiptContext {
            challenge_id: "ch-1",
            receipt: &receipt,
            response: resp,
        });

        // Both existing directives preserved (not dropped) and `private` added,
        // collapsed into a single normalized header value.
        let values: Vec<_> = resp
            .headers()
            .get_all(http_types::header::CACHE_CONTROL)
            .iter()
            .map(|v| v.to_str().unwrap())
            .collect();
        assert_eq!(values, vec!["no-cache, max-age=60, private"]);
    }
}