mpp 0.15.0

//! Tower middleware for payment gating.
//!
//! Provides a [`PaymentLayer`] that wraps the 402 challenge/verify flow
//! into a standard Tower `Layer`/`Service`, compatible with axum, tonic,
//! and any Tower-based framework.
//!
//! # Example (axum)
//!
#![cfg_attr(feature = "tempo", doc = "```no_run")]
#![cfg_attr(not(feature = "tempo"), doc = "```ignore")]
//! use axum::{routing::get, Router};
//! use mpp::server::middleware::PaymentLayer;
//! use mpp::server::{tempo, Mpp, TempoConfig};
//!
//! # fn main() -> mpp::Result<()> {
//! let mpp = Mpp::create(tempo(TempoConfig {
//!     recipient: "0x742d35Cc6634C0532925a3b844Bc9e7595f1B0F2",
//! }))?;
//!
//! let app: Router = Router::new()
//!     .route("/premium", get(|| async { "paid content" }))
//!     .route_layer(PaymentLayer::charge(&mpp, "0.10")?);
//! # Ok(())
//! # }
//! ```
//!
//! Prefer axum's `route_layer` over `layer`: `layer` also wraps the fallback,
//! so requests for unknown paths are answered with 402 instead of 404. Apply
//! CORS handling outside the payment layer so preflight requests, which never
//! carry credentials, are answered before payment is checked.

use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};

use bytes::Bytes;
use http_body_util::BodyExt;
use http_types::{header, HeaderValue, Request, Response, StatusCode};

use crate::error::{MppError, PaymentError};
use crate::protocol::core::headers::{
    extract_payment_scheme, format_receipt, format_www_authenticate_many, parse_authorization,
    with_private_cache_control, PAYMENT_RECEIPT_HEADER, WWW_AUTHENTICATE_HEADER,
};

/// Trait for payment verification in middleware context.
///
/// This abstracts over the `Mpp` type's generics so the middleware
/// can be used without propagating generic parameters.
pub trait PaymentVerifier: Send + Sync + 'static {
    /// Generate a `WWW-Authenticate: Payment ...` challenge header value.
    fn challenge(&self) -> Result<String, String>;

    /// Generate a body-bound `WWW-Authenticate: Payment ...` challenge header value.
    fn challenge_with_body(&self, body: &[u8]) -> Result<String, String> {
        let _ = body;
        self.challenge()
    }

    /// Verify a credential string and return a `Payment-Receipt` header value.
    ///
    /// The `credential` is the raw Payment credential header value
    /// (e.g., `"Payment eyJ..."` including the scheme prefix).
    fn verify(
        &self,
        credential: &str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>>;

    /// Verify a credential string against the actual request body bytes.
    fn verify_with_body(
        &self,
        credential: &str,
        body: &[u8],
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
        let _ = body;
        self.verify(credential)
    }

    /// Verify a credential string, against the request body bytes when the
    /// layer is body-bound, keeping the failure typed.
    ///
    /// The layers call this method and answer a failure by its kind: a
    /// payment problem gets a fresh challenge, a server-side failure a `500`
    /// without one. The default delegates to [`verify`](Self::verify) and
    /// [`verify_with_body`](Self::verify_with_body) and reports every failure
    /// as `verification-failed`.
    fn verify_credential(
        &self,
        credential: &str,
        body: Option<&[u8]>,
    ) -> Pin<Box<dyn Future<Output = Result<String, MppError>> + Send>> {
        let verified = match body {
            Some(body) => self.verify_with_body(credential, body),
            None => self.verify(credential),
        };
        Box::pin(async move { verified.await.map_err(MppError::verification_failed) })
    }

    /// HTTP field containing the Payment credential.
    ///
    /// Defaults to `Authorization`. Servers created with `requires_auth`
    /// return `Payment-Authorization`.
    fn credential_header(&self) -> &str {
        header::AUTHORIZATION.as_str()
    }
}

// ==================== FnVerifier ====================

/// A [`PaymentVerifier`] built from closures.
#[allow(clippy::type_complexity)]
pub struct FnVerifier {
    challenge_fn: Box<dyn Fn() -> Result<String, String> + Send + Sync>,
    challenge_with_body_fn: Option<Box<dyn Fn(&[u8]) -> Result<String, String> + Send + Sync>>,
    verify_fn: Box<
        dyn Fn(String) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>>
            + Send
            + Sync,
    >,
    verify_with_body_fn: Option<
        Box<
            dyn Fn(String, Vec<u8>) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>>
                + Send
                + Sync,
        >,
    >,
}

impl PaymentVerifier for FnVerifier {
    fn challenge(&self) -> Result<String, String> {
        (self.challenge_fn)()
    }

    fn challenge_with_body(&self, body: &[u8]) -> Result<String, String> {
        match &self.challenge_with_body_fn {
            Some(f) => f(body),
            None => self.challenge(),
        }
    }

    fn verify(
        &self,
        credential: &str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
        (self.verify_fn)(credential.to_string())
    }

    fn verify_with_body(
        &self,
        credential: &str,
        body: &[u8],
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
        match &self.verify_with_body_fn {
            Some(f) => f(credential.to_string(), body.to_vec()),
            None => self.verify(credential),
        }
    }
}

// ==================== PaymentLayer ====================

/// Tower [`Layer`](tower_layer::Layer) that gates requests behind payment verification.
///
/// Requests without a valid `Authorization: Payment ...` header receive
/// a `402 Payment Required` response with a `WWW-Authenticate` challenge.
/// Valid payments are verified and a `Payment-Receipt` header is attached
/// to the inner service's response.
///
/// A credential that cannot be verified because of a server-side failure
/// (RPC, store) is answered with `500` and no challenge, so the client does
/// not pay again. The layer is generic over the response body, so its own
/// responses have an empty body and carry no problem details.
pub struct PaymentLayer<V> {
    verifier: Arc<V>,
}

impl<V> Clone for PaymentLayer<V> {
    fn clone(&self) -> Self {
        Self {
            verifier: Arc::clone(&self.verifier),
        }
    }
}

impl<V: PaymentVerifier> PaymentLayer<V> {
    /// Create a payment layer with a custom [`PaymentVerifier`].
    pub fn new(verifier: V) -> Self {
        Self {
            verifier: Arc::new(verifier),
        }
    }
}

impl PaymentLayer<FnVerifier> {
    /// Create a payment layer from challenge/verify closures.
    pub fn from_fns(
        challenge_fn: impl Fn() -> Result<String, String> + Send + Sync + 'static,
        verify_fn: impl Fn(String) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>>
            + Send
            + Sync
            + 'static,
    ) -> Self {
        Self::new(FnVerifier {
            challenge_fn: Box::new(challenge_fn),
            challenge_with_body_fn: None,
            verify_fn: Box::new(verify_fn),
            verify_with_body_fn: None,
        })
    }
}

impl<S, V: PaymentVerifier> tower_layer::Layer<S> for PaymentLayer<V> {
    type Service = PaymentService<S, V>;

    fn layer(&self, inner: S) -> Self::Service {
        PaymentService {
            inner,
            verifier: Arc::clone(&self.verifier),
        }
    }
}

// ==================== PaymentService ====================

/// Tower [`Service`](tower_service::Service) that wraps an inner service with payment verification.
pub struct PaymentService<S, V> {
    inner: S,
    verifier: Arc<V>,
}

impl<S: Clone, V> Clone for PaymentService<S, V> {
    fn clone(&self) -> Self {
        Self {
            inner: self.inner.clone(),
            verifier: Arc::clone(&self.verifier),
        }
    }
}

impl<S, V, ReqBody, ResBody> tower_service::Service<Request<ReqBody>> for PaymentService<S, V>
where
    S: tower_service::Service<Request<ReqBody>, Response = Response<ResBody>>
        + Clone
        + Send
        + 'static,
    S::Future: Send,
    S::Error: Send,
    V: PaymentVerifier,
    ReqBody: Send + 'static,
    ResBody: Default + Send + 'static,
{
    type Response = Response<ResBody>;
    type Error = S::Error;
    type Future = Pin<Box<dyn Future<Output = Result<Response<ResBody>, S::Error>> + Send>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: Request<ReqBody>) -> Self::Future {
        let verifier = Arc::clone(&self.verifier);
        // Keep a clone in `self` for future poll_ready cycles and call the
        // currently-ready service instance moved out of `self`.
        let clone = self.inner.clone();
        let mut inner = std::mem::replace(&mut self.inner, clone);

        Box::pin(async move {
            // Extract the Payment credential from the header selected by the challenge.
            let auth_header = req
                .headers()
                .get(verifier.credential_header())
                .and_then(|v| v.to_str().ok())
                .and_then(extract_payment_scheme)
                .map(|s| s.to_string());

            let credential = match auth_header {
                Some(c) => c,
                None => {
                    // No credential — return a fresh, retryable 402 challenge.
                    return Ok(match verifier.challenge() {
                        Ok(challenge) => {
                            challenge_response(StatusCode::PAYMENT_REQUIRED, &challenge)
                        }
                        Err(e) => error_response(
                            StatusCode::INTERNAL_SERVER_ERROR,
                            &format!("Failed to generate challenge: {}", e),
                        ),
                    });
                }
            };

            // Verify the credential.
            let receipt_header = match verifier.verify_credential(&credential, None).await {
                Ok(r) => r,
                Err(error) => return Ok(rejection_response(&error, || verifier.challenge())),
            };

            // Call the inner service.
            let mut resp = inner.call(req).await?;
            attach_receipt(&mut resp, &receipt_header);

            Ok(resp)
        })
    }
}

// ==================== PaymentBodyLayer ====================

/// Default cap on the request body bytes buffered by [`PaymentBodyLayer`],
/// matching axum's `DefaultBodyLimit`.
const DEFAULT_MAX_BODY_BYTES: usize = 2 * 1024 * 1024;

/// Tower [`Layer`](tower_layer::Layer) that binds payment verification to request body bytes.
///
/// The request body is buffered, used for body-digest challenge/verification,
/// and then replayed to the inner service as `http_body_util::Full<Bytes>`.
///
/// Buffering happens before any payment is made, so bodies larger than
/// [`max_body_bytes`](Self::max_body_bytes) (2 MiB by default) are rejected
/// with `413 Payload Too Large`.
pub struct PaymentBodyLayer<V> {
    verifier: Arc<V>,
    max_body_bytes: usize,
}

impl<V> Clone for PaymentBodyLayer<V> {
    fn clone(&self) -> Self {
        Self {
            verifier: Arc::clone(&self.verifier),
            max_body_bytes: self.max_body_bytes,
        }
    }
}

impl<V: PaymentVerifier> PaymentBodyLayer<V> {
    /// Create a body-aware payment layer with a custom [`PaymentVerifier`].
    pub fn new(verifier: V) -> Self {
        Self {
            verifier: Arc::new(verifier),
            max_body_bytes: DEFAULT_MAX_BODY_BYTES,
        }
    }
}

impl<V> PaymentBodyLayer<V> {
    /// Set the maximum number of request body bytes to buffer.
    ///
    /// Defaults to 2 MiB.
    pub fn max_body_bytes(mut self, max_body_bytes: usize) -> Self {
        self.max_body_bytes = max_body_bytes;
        self
    }
}

impl<S, V: PaymentVerifier> tower_layer::Layer<S> for PaymentBodyLayer<V> {
    type Service = PaymentBodyService<S, V>;

    fn layer(&self, inner: S) -> Self::Service {
        PaymentBodyService {
            inner,
            verifier: Arc::clone(&self.verifier),
            max_body_bytes: self.max_body_bytes,
        }
    }
}

/// Tower [`Service`](tower_service::Service) for body-bound payment verification.
pub struct PaymentBodyService<S, V> {
    inner: S,
    verifier: Arc<V>,
    max_body_bytes: usize,
}

impl<S: Clone, V> Clone for PaymentBodyService<S, V> {
    fn clone(&self) -> Self {
        Self {
            inner: self.inner.clone(),
            verifier: Arc::clone(&self.verifier),
            max_body_bytes: self.max_body_bytes,
        }
    }
}

impl<S, V, ReqBody, ResBody> tower_service::Service<Request<ReqBody>> for PaymentBodyService<S, V>
where
    S: tower_service::Service<Request<http_body_util::Full<Bytes>>, Response = Response<ResBody>>
        + Clone
        + Send
        + 'static,
    S::Future: Send,
    S::Error: Send,
    V: PaymentVerifier,
    ReqBody: http_body::Body<Data = Bytes> + Send + 'static,
    ReqBody::Error: std::fmt::Display + Send + Sync + 'static,
    ResBody: Default + Send + 'static,
{
    type Response = Response<ResBody>;
    type Error = S::Error;
    type Future = Pin<Box<dyn Future<Output = Result<Response<ResBody>, S::Error>> + Send>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: Request<ReqBody>) -> Self::Future {
        let verifier = Arc::clone(&self.verifier);
        let max_body_bytes = self.max_body_bytes;
        let clone = self.inner.clone();
        let mut inner = std::mem::replace(&mut self.inner, clone);

        Box::pin(async move {
            let (parts, body) = req.into_parts();
            let body =
                http_body_util::Limited::new(body.map_err(|e| e.to_string()), max_body_bytes);
            let body = match body.collect().await {
                Ok(collected) => collected.to_bytes(),
                Err(e) if e.is::<http_body_util::LengthLimitError>() => {
                    return Ok(error_response(
                        StatusCode::PAYLOAD_TOO_LARGE,
                        "Request body too large",
                    ));
                }
                Err(e) => {
                    return Ok(error_response(
                        StatusCode::BAD_REQUEST,
                        &format!("Failed to read request body: {e}"),
                    ));
                }
            };

            // Extract the Payment credential from the header selected by the challenge.
            let auth_header = parts
                .headers
                .get(verifier.credential_header())
                .and_then(|v| v.to_str().ok())
                .and_then(extract_payment_scheme)
                .map(|s| s.to_string());

            let credential = match auth_header {
                Some(c) => c,
                None => {
                    let challenge = match verifier.challenge_with_body(&body) {
                        Ok(c) => c,
                        Err(e) => {
                            return Ok(error_response(
                                StatusCode::INTERNAL_SERVER_ERROR,
                                &format!("Failed to generate challenge: {e}"),
                            ));
                        }
                    };
                    return Ok(challenge_response(StatusCode::PAYMENT_REQUIRED, &challenge));
                }
            };

            let receipt_header = match verifier.verify_credential(&credential, Some(&body)).await {
                Ok(r) => r,
                Err(error) => {
                    return Ok(rejection_response(&error, || {
                        verifier.challenge_with_body(&body)
                    }));
                }
            };

            let req = Request::from_parts(parts, http_body_util::Full::new(body));
            let mut resp = inner.call(req).await?;
            attach_receipt(&mut resp, &receipt_header);

            Ok(resp)
        })
    }
}

/// Build a minimal error response.
fn error_response<B: Default>(status: StatusCode, _message: &str) -> Response<B> {
    let mut resp = Response::new(B::default());
    *resp.status_mut() = status;
    resp
}

/// Attach a receipt only to successful responses and prevent shared caching.
fn attach_receipt<B>(resp: &mut Response<B>, receipt_header: &str) {
    if !resp.status().is_success() {
        return;
    }

    let Ok(receipt) = HeaderValue::from_str(receipt_header) else {
        return;
    };

    let existing_cc = resp
        .headers()
        .get_all(header::CACHE_CONTROL)
        .iter()
        .filter_map(|value| value.to_str().ok())
        .collect::<Vec<_>>()
        .join(", ");
    let cache_control = with_private_cache_control(Some(existing_cc.as_str()));
    if let Ok(value) = HeaderValue::from_str(&cache_control) {
        resp.headers_mut().insert(header::CACHE_CONTROL, value);
    }
    resp.headers_mut().insert(PAYMENT_RECEIPT_HEADER, receipt);
}

/// Build a retryable response carrying a fresh `WWW-Authenticate: Payment`
/// challenge and `Cache-Control: no-store`.
///
/// A challenge that is not a valid header value cannot be offered to the
/// client, so it is answered as a server-side failure.
fn challenge_response<B: Default>(status: StatusCode, challenge: &str) -> Response<B> {
    let Ok(challenge) = HeaderValue::from_str(challenge) else {
        return internal_error_response();
    };
    let mut resp = Response::new(B::default());
    *resp.status_mut() = status;
    resp.headers_mut()
        .insert(WWW_AUTHENTICATE_HEADER, challenge);
    resp.headers_mut()
        .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
    resp
}

/// Build a `500` response without a challenge.
fn internal_error_response<B: Default>() -> Response<B> {
    let mut resp = error_response(StatusCode::INTERNAL_SERVER_ERROR, "");
    resp.headers_mut()
        .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
    resp
}

/// Build the response for a credential that failed with `error`.
///
/// A payment problem is answered with its status and the fresh challenge
/// from `challenge` so the client can retry. A server-side failure is
/// answered with `500` and no challenge, so the client does not pay again.
fn rejection_response<B: Default>(
    error: &MppError,
    challenge: impl FnOnce() -> Result<String, String>,
) -> Response<B> {
    if !error.is_payment_problem() {
        return internal_error_response();
    }
    let status = StatusCode::from_u16(error.to_problem_details(None).status)
        .unwrap_or(StatusCode::PAYMENT_REQUIRED);
    match challenge() {
        Ok(challenge) => challenge_response(status, &challenge),
        Err(_) => internal_error_response(),
    }
}

// ==================== Mpp integration ====================

/// A [`PaymentVerifier`] backed by an `Mpp` instance's charge flow.
///
/// Created via [`PaymentLayer::charge()`] and [`PaymentBodyLayer::charge()`].
#[allow(clippy::type_complexity)]
pub struct ChargeVerifier {
    /// Builds a fresh `WWW-Authenticate` header value per request.
    challenge_fn: Box<dyn Fn() -> Result<String, String> + Send + Sync>,
    /// Builds a fresh body-bound `WWW-Authenticate` header value per request.
    challenge_with_body_fn: Box<dyn Fn(&[u8]) -> Result<String, String> + Send + Sync>,
    /// HTTP field containing the Payment credential.
    credential_header: String,
    /// Shared mpp instance for verification (type-erased).
    verify_fn: Box<
        dyn Fn(String) -> Pin<Box<dyn Future<Output = Result<String, MppError>> + Send>>
            + Send
            + Sync,
    >,
    /// Shared mpp instance for body-bound verification (type-erased).
    verify_with_body_fn: Box<
        dyn Fn(String, Vec<u8>) -> Pin<Box<dyn Future<Output = Result<String, MppError>> + Send>>
            + Send
            + Sync,
    >,
}

impl PaymentVerifier for ChargeVerifier {
    fn challenge(&self) -> Result<String, String> {
        (self.challenge_fn)()
    }

    fn challenge_with_body(&self, body: &[u8]) -> Result<String, String> {
        (self.challenge_with_body_fn)(body)
    }

    fn verify(
        &self,
        credential: &str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
        let verified = self.verify_credential(credential, None);
        Box::pin(async move { verified.await.map_err(|e| e.to_string()) })
    }

    fn verify_with_body(
        &self,
        credential: &str,
        body: &[u8],
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
        let verified = self.verify_credential(credential, Some(body));
        Box::pin(async move { verified.await.map_err(|e| e.to_string()) })
    }

    fn verify_credential(
        &self,
        credential: &str,
        body: Option<&[u8]>,
    ) -> Pin<Box<dyn Future<Output = Result<String, MppError>> + Send>> {
        match body {
            Some(body) => (self.verify_with_body_fn)(credential.to_string(), body.to_vec()),
            None => (self.verify_fn)(credential.to_string()),
        }
    }

    fn credential_header(&self) -> &str {
        &self.credential_header
    }
}

impl PaymentLayer<ChargeVerifier> {
    /// Create a payment layer that charges a dollar amount per request.
    ///
    /// Generates a fresh challenge for each request and verifies each
    /// incoming credential against the provided `Mpp` instance.
    ///
    /// # Example
    ///
    /// ```ignore
    /// use mpp::server::middleware::PaymentLayer;
    ///
    /// let layer = PaymentLayer::charge(&mpp, "0.10").unwrap();
    /// ```
    #[cfg(feature = "tempo")]
    pub fn charge<M, S>(mpp: &super::Mpp<M, S>, amount: &str) -> crate::error::Result<Self>
    where
        M: crate::protocol::traits::ChargeMethod + Clone + Send + Sync + 'static,
        S: Clone + Send + Sync + 'static,
    {
        // Capture route-scoped expected request once so credential verification
        // compares against endpoint configuration, not echoed credential data.
        let expected_challenge = mpp.charge(amount).map(|mut offers| offers.remove(0))?;
        let expected_request: crate::protocol::intents::ChargeRequest =
            expected_challenge.request.decode().map_err(|e| {
                crate::error::MppError::InvalidConfig(format!(
                    "Failed to decode route charge request: {e}"
                ))
            })?;

        let mpp_for_challenge = mpp.clone();
        let charge_amount = amount.to_string();
        // One challenge per accepted currency, comma-joined into a single
        // `WWW-Authenticate` value (RFC 9110 §11.6.1).
        let challenge_fn = Box::new(move || {
            let challenges = mpp_for_challenge
                .charge(&charge_amount)
                .map_err(|e| format!("Failed to generate challenge: {e}"))?;
            format_www_authenticate_many(&challenges)
                .map(|values| values.join(", "))
                .map_err(|e| format!("Failed to format challenge: {e}"))
        });

        let mpp_for_body_challenge = mpp.clone();
        let charge_amount_for_body = amount.to_string();
        let challenge_with_body_fn = Box::new(move |body: &[u8]| {
            let challenges = mpp_for_body_challenge
                .charge_with_options_and_body(
                    &charge_amount_for_body,
                    super::ChargeOptions::default(),
                    body,
                )
                .map_err(|e| format!("Failed to generate challenge: {e}"))?;
            format_www_authenticate_many(&challenges)
                .map(|values| values.join(", "))
                .map_err(|e| format!("Failed to format challenge: {e}"))
        });

        let mpp_for_verify = mpp.clone();
        let expected_request_for_body = expected_request.clone();
        let verify_fn = Box::new(move |credential_str: String| -> Pin<Box<dyn Future<Output = Result<String, MppError>> + Send>> {
            let mpp = mpp_for_verify.clone();
            let expected_request = expected_request.clone();
            Box::pin(async move {
                let credential = parse_authorization(&credential_str)?;

                let receipt = mpp
                    .verify_credential_with_expected_request(&credential, &expected_request)
                    .await?;

                format_receipt(&receipt)
            })
        });

        let mpp_for_body_verify = mpp.clone();
        let verify_with_body_fn = Box::new(
            move |credential_str: String,
                  body: Vec<u8>|
                  -> Pin<Box<dyn Future<Output = Result<String, MppError>> + Send>> {
                let mpp = mpp_for_body_verify.clone();
                let expected_request = expected_request_for_body.clone();
                Box::pin(async move {
                    let credential = parse_authorization(&credential_str)?;

                    let receipt = mpp
                        .verify_credential_with_expected_request_and_body(
                            &credential,
                            &expected_request,
                            &body,
                        )
                        .await?;

                    format_receipt(&receipt)
                })
            },
        );

        Ok(Self::new(ChargeVerifier {
            challenge_fn,
            challenge_with_body_fn,
            credential_header: mpp.credential_header().to_string(),
            verify_fn,
            verify_with_body_fn,
        }))
    }
}

impl PaymentBodyLayer<ChargeVerifier> {
    /// Create a body-aware payment layer that charges a dollar amount per request.
    ///
    /// This buffers the request body, binds issued challenges to its digest,
    /// verifies credentials against the same bytes, and replays the body to
    /// the inner service.
    #[cfg(feature = "tempo")]
    pub fn charge<M, S>(mpp: &super::Mpp<M, S>, amount: &str) -> crate::error::Result<Self>
    where
        M: crate::protocol::traits::ChargeMethod + Clone + Send + Sync + 'static,
        S: Clone + Send + Sync + 'static,
    {
        let layer = PaymentLayer::charge(mpp, amount)?;
        Ok(Self {
            verifier: layer.verifier,
            max_body_bytes: DEFAULT_MAX_BODY_BYTES,
        })
    }
}

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

    #[derive(Clone)]
    struct MockVerifier {
        challenge_value: String,
        accept: bool,
    }

    impl PaymentVerifier for MockVerifier {
        fn challenge(&self) -> Result<String, String> {
            Ok(self.challenge_value.clone())
        }

        fn verify(
            &self,
            _credential: &str,
        ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
            let accept = self.accept;
            Box::pin(async move {
                if accept {
                    Ok("mock-receipt-token".to_string())
                } else {
                    Err("payment rejected".to_string())
                }
            })
        }
    }

    #[derive(Clone)]
    struct StatusService(StatusCode);

    impl<B: Send + 'static> tower_service::Service<Request<B>> for StatusService {
        type Response = Response<()>;
        type Error = std::convert::Infallible;
        type Future = Pin<Box<dyn Future<Output = Result<Response<()>, Self::Error>> + Send>>;

        fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
            Poll::Ready(Ok(()))
        }

        fn call(&mut self, _req: Request<B>) -> Self::Future {
            let status = self.0;
            Box::pin(async move {
                let mut resp = Response::new(());
                *resp.status_mut() = status;
                Ok(resp)
            })
        }
    }

    #[test]
    fn test_payment_verifier_challenge() {
        let v = MockVerifier {
            challenge_value: "Payment id=\"test\"".to_string(),
            accept: true,
        };
        assert_eq!(v.challenge().unwrap(), "Payment id=\"test\"");
    }

    #[tokio::test]
    async fn test_payment_verifier_verify_accept() {
        let v = MockVerifier {
            challenge_value: String::new(),
            accept: true,
        };
        let result = v.verify("Payment eyJ...").await;
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), "mock-receipt-token");
    }

    #[tokio::test]
    async fn test_payment_verifier_verify_reject() {
        let v = MockVerifier {
            challenge_value: String::new(),
            accept: false,
        };
        let result = v.verify("Payment eyJ...").await;
        assert!(result.is_err());
        assert_eq!(result.unwrap_err(), "payment rejected");
    }

    #[test]
    fn test_fn_verifier_challenge() {
        let v = FnVerifier {
            challenge_fn: Box::new(|| Ok("Payment test".to_string())),
            challenge_with_body_fn: None,
            verify_fn: Box::new(|_| Box::pin(async { Ok("receipt".to_string()) })),
            verify_with_body_fn: None,
        };
        assert_eq!(v.challenge().unwrap(), "Payment test");
    }

    #[test]
    fn test_payment_layer_clones() {
        let layer = PaymentLayer::new(MockVerifier {
            challenge_value: "test".into(),
            accept: true,
        });
        let _clone = layer.clone();
    }

    /// Test the full Tower service flow: no auth → 402.
    #[tokio::test]
    async fn test_service_no_auth_returns_402() {
        use tower_service::Service;

        let layer = PaymentLayer::new(MockVerifier {
            challenge_value: "Payment id=\"challenge\"".to_string(),
            accept: true,
        });

        // A trivial inner service that returns 200.
        #[derive(Clone)]
        struct OkService;

        impl tower_service::Service<Request<()>> for OkService {
            type Response = Response<()>;
            type Error = std::convert::Infallible;
            type Future = Pin<Box<dyn Future<Output = Result<Response<()>, Self::Error>> + Send>>;

            fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
                Poll::Ready(Ok(()))
            }

            fn call(&mut self, _req: Request<()>) -> Self::Future {
                Box::pin(async { Ok(Response::new(())) })
            }
        }

        let mut svc =
            <PaymentLayer<MockVerifier> as tower_layer::Layer<OkService>>::layer(&layer, OkService);

        let req = Request::builder().uri("/premium").body(()).unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);
        assert!(resp.headers().contains_key(WWW_AUTHENTICATE_HEADER));
        assert_eq!(
            resp.headers().get(header::CACHE_CONTROL).unwrap(),
            "no-store"
        );
    }

    /// Test: valid auth → 200 with receipt.
    #[tokio::test]
    async fn test_service_valid_auth_returns_receipt() {
        use tower_service::Service;

        let layer = PaymentLayer::new(MockVerifier {
            challenge_value: "Payment id=\"challenge\"".to_string(),
            accept: true,
        });

        #[derive(Clone)]
        struct OkService;

        impl tower_service::Service<Request<()>> for OkService {
            type Response = Response<()>;
            type Error = std::convert::Infallible;
            type Future = Pin<Box<dyn Future<Output = Result<Response<()>, Self::Error>> + Send>>;

            fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
                Poll::Ready(Ok(()))
            }

            fn call(&mut self, _req: Request<()>) -> Self::Future {
                Box::pin(async { Ok(Response::new(())) })
            }
        }

        let mut svc =
            <PaymentLayer<MockVerifier> as tower_layer::Layer<OkService>>::layer(&layer, OkService);

        let req = Request::builder()
            .uri("/premium")
            .header(header::AUTHORIZATION, "Payment eyJmYWtlIjp0cnVlfQ")
            .body(())
            .unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        assert_eq!(
            resp.headers().get(PAYMENT_RECEIPT_HEADER).unwrap(),
            "mock-receipt-token"
        );
        // Per spec, receipt responses must be Cache-Control: private.
        assert_eq!(
            resp.headers().get(header::CACHE_CONTROL).unwrap(),
            "private"
        );
    }

    #[tokio::test]
    async fn test_service_does_not_attach_receipt_to_error_response() {
        use tower_service::Service;

        for status in [
            StatusCode::FOUND,
            StatusCode::FORBIDDEN,
            StatusCode::INTERNAL_SERVER_ERROR,
        ] {
            let layer = PaymentLayer::new(MockVerifier {
                challenge_value: "Payment id=\"challenge\"".to_string(),
                accept: true,
            });
            let mut svc = layer.layer(StatusService(status));
            let req = Request::builder()
                .uri("/premium")
                .header(header::AUTHORIZATION, "Payment eyJmYWtlIjp0cnVlfQ")
                .body(())
                .unwrap();

            let resp = svc.call(req).await.unwrap();
            assert_eq!(resp.status(), status);
            assert!(!resp.headers().contains_key(PAYMENT_RECEIPT_HEADER));
            assert!(!resp.headers().contains_key(header::CACHE_CONTROL));
        }
    }

    #[test]
    fn test_attach_receipt_preserves_existing_cache_control() {
        let mut resp = Response::new(());
        resp.headers_mut()
            .append(header::CACHE_CONTROL, HeaderValue::from_static("public"));
        resp.headers_mut().append(
            header::CACHE_CONTROL,
            HeaderValue::from_static("max-age=60"),
        );

        attach_receipt(&mut resp, "mock-receipt-token");

        assert_eq!(
            resp.headers().get(header::CACHE_CONTROL).unwrap(),
            "public, max-age=60, private"
        );
        assert_eq!(
            resp.headers().get(PAYMENT_RECEIPT_HEADER).unwrap(),
            "mock-receipt-token"
        );
    }

    #[test]
    fn test_attach_receipt_rejects_invalid_header_without_changing_cache_control() {
        let mut resp = Response::new(());
        resp.headers_mut().insert(
            header::CACHE_CONTROL,
            HeaderValue::from_static("public, max-age=60"),
        );

        attach_receipt(&mut resp, "invalid\nreceipt");

        assert!(!resp.headers().contains_key(PAYMENT_RECEIPT_HEADER));
        assert_eq!(
            resp.headers().get(header::CACHE_CONTROL).unwrap(),
            "public, max-age=60"
        );
    }

    #[tokio::test]
    async fn test_service_unusable_challenge_returns_500_without_challenge() {
        use tower_service::Service;

        for authorization in [None, Some("Payment eyJmYWtlIjp0cnVlfQ")] {
            let layer = PaymentLayer::new(MockVerifier {
                challenge_value: "Payment id=\"a\nb\"".to_string(),
                accept: false,
            });
            let mut svc = layer.layer(StatusService(StatusCode::OK));
            let mut req = Request::builder().uri("/premium");
            if let Some(authorization) = authorization {
                req = req.header(header::AUTHORIZATION, authorization);
            }

            let resp = svc.call(req.body(()).unwrap()).await.unwrap();
            assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
            assert!(!resp.headers().contains_key(WWW_AUTHENTICATE_HEADER));
        }
    }

    /// Test: invalid auth → retryable 402 with a fresh challenge.
    ///
    /// A failed credential must yield a 402 that carries a new
    /// `WWW-Authenticate: Payment` challenge and `Cache-Control: no-store`,
    /// so the client can pay again. A bare 402 (no challenge) is a dead end
    /// the Payment auth scheme — and this SDK's own client — reject.
    #[tokio::test]
    async fn test_service_invalid_auth_returns_retryable_402() {
        use tower_service::Service;

        let layer = PaymentLayer::new(MockVerifier {
            challenge_value: "Payment id=\"challenge\"".to_string(),
            accept: false,
        });

        #[derive(Clone)]
        struct OkService;

        impl tower_service::Service<Request<()>> for OkService {
            type Response = Response<()>;
            type Error = std::convert::Infallible;
            type Future = Pin<Box<dyn Future<Output = Result<Response<()>, Self::Error>> + Send>>;

            fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
                Poll::Ready(Ok(()))
            }

            fn call(&mut self, _req: Request<()>) -> Self::Future {
                Box::pin(async { Ok(Response::new(())) })
            }
        }

        let mut svc =
            <PaymentLayer<MockVerifier> as tower_layer::Layer<OkService>>::layer(&layer, OkService);

        let req = Request::builder()
            .uri("/premium")
            .header(header::AUTHORIZATION, "Payment eyJmYWtlIjp0cnVlfQ")
            .body(())
            .unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);
        // Must carry a fresh challenge so the client can retry.
        assert_eq!(
            resp.headers().get(WWW_AUTHENTICATE_HEADER).unwrap(),
            "Payment id=\"challenge\""
        );
        // 402 responses must not be cached.
        assert_eq!(
            resp.headers().get(header::CACHE_CONTROL).unwrap(),
            "no-store"
        );
    }

    #[derive(Clone)]
    struct BodyAwareVerifier {
        challenge_body: Arc<std::sync::Mutex<Option<Vec<u8>>>>,
        verify_body: Arc<std::sync::Mutex<Option<Vec<u8>>>>,
    }

    impl PaymentVerifier for BodyAwareVerifier {
        fn challenge(&self) -> Result<String, String> {
            Ok("Payment id=\"legacy\"".to_string())
        }

        fn challenge_with_body(&self, body: &[u8]) -> Result<String, String> {
            *self.challenge_body.lock().unwrap() = Some(body.to_vec());
            Ok("Payment id=\"body-bound\"".to_string())
        }

        fn verify(
            &self,
            _credential: &str,
        ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
            Box::pin(async { Err("legacy verifier should not be called".to_string()) })
        }

        fn verify_with_body(
            &self,
            _credential: &str,
            body: &[u8],
        ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
            *self.verify_body.lock().unwrap() = Some(body.to_vec());
            Box::pin(async { Ok("mock-receipt-token".to_string()) })
        }
    }

    #[derive(Clone)]
    struct BodyEchoService;

    impl tower_service::Service<Request<http_body_util::Full<Bytes>>> for BodyEchoService {
        type Response = Response<Vec<u8>>;
        type Error = std::convert::Infallible;
        type Future = Pin<Box<dyn Future<Output = Result<Response<Vec<u8>>, Self::Error>> + Send>>;

        fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
            Poll::Ready(Ok(()))
        }

        fn call(&mut self, req: Request<http_body_util::Full<Bytes>>) -> Self::Future {
            Box::pin(async move {
                let body = req.into_body().collect().await.unwrap().to_bytes();
                let mut response = Response::new(body.to_vec());
                response.headers_mut().insert(
                    header::CACHE_CONTROL,
                    HeaderValue::from_static("max-age=60"),
                );
                Ok(response)
            })
        }
    }

    #[tokio::test]
    async fn test_body_service_no_auth_binds_challenge_to_body() {
        use tower_service::Service;

        let challenge_body = Arc::new(std::sync::Mutex::new(None));
        let layer = PaymentBodyLayer::new(BodyAwareVerifier {
            challenge_body: challenge_body.clone(),
            verify_body: Arc::new(std::sync::Mutex::new(None)),
        });
        let mut svc = layer.layer(BodyEchoService);

        let req = Request::builder()
            .uri("/premium")
            .body(http_body_util::Full::new(Bytes::from_static(
                br#"{"query":"paid"}"#,
            )))
            .unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);
        assert_eq!(
            resp.headers().get(WWW_AUTHENTICATE_HEADER).unwrap(),
            "Payment id=\"body-bound\""
        );
        assert_eq!(
            challenge_body.lock().unwrap().as_deref(),
            Some(br#"{"query":"paid"}"#.as_slice())
        );
    }

    #[tokio::test]
    async fn test_body_service_valid_auth_verifies_and_replays_body() {
        use tower_service::Service;

        let verify_body = Arc::new(std::sync::Mutex::new(None));
        let layer = PaymentBodyLayer::new(BodyAwareVerifier {
            challenge_body: Arc::new(std::sync::Mutex::new(None)),
            verify_body: verify_body.clone(),
        });
        let mut svc = layer.layer(BodyEchoService);

        let req = Request::builder()
            .uri("/premium")
            .header(header::AUTHORIZATION, "Payment eyJmYWtlIjp0cnVlfQ")
            .body(http_body_util::Full::new(Bytes::from_static(
                br#"{"query":"paid"}"#,
            )))
            .unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        assert_eq!(resp.body(), br#"{"query":"paid"}"#);
        assert_eq!(
            resp.headers().get(PAYMENT_RECEIPT_HEADER).unwrap(),
            "mock-receipt-token"
        );
        assert_eq!(
            resp.headers().get(header::CACHE_CONTROL).unwrap(),
            "max-age=60, private"
        );
        assert_eq!(
            verify_body.lock().unwrap().as_deref(),
            Some(br#"{"query":"paid"}"#.as_slice())
        );
    }

    fn body_aware_layer() -> PaymentBodyLayer<BodyAwareVerifier> {
        PaymentBodyLayer::new(BodyAwareVerifier {
            challenge_body: Arc::new(std::sync::Mutex::new(None)),
            verify_body: Arc::new(std::sync::Mutex::new(None)),
        })
    }

    #[tokio::test]
    async fn test_body_service_stops_reading_oversized_body() {
        use futures_util::StreamExt;
        use tower_service::Service;

        let mut svc = body_aware_layer()
            .max_body_bytes(1024)
            .layer(BodyEchoService);

        let chunks = futures_util::stream::iter(0..).map(|i| {
            assert!(i < 4, "body read past the limit");
            Ok::<_, std::convert::Infallible>(http_body::Frame::data(Bytes::from_static(&[0; 512])))
        });
        let req = Request::builder()
            .uri("/premium")
            .body(http_body_util::StreamBody::new(chunks))
            .unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::PAYLOAD_TOO_LARGE);
        assert!(!resp.headers().contains_key(WWW_AUTHENTICATE_HEADER));
    }

    #[tokio::test]
    async fn test_body_service_default_body_limit() {
        use tower_service::Service;

        for (len, status) in [
            (DEFAULT_MAX_BODY_BYTES, StatusCode::PAYMENT_REQUIRED),
            (DEFAULT_MAX_BODY_BYTES + 1, StatusCode::PAYLOAD_TOO_LARGE),
        ] {
            let mut svc = body_aware_layer().layer(BodyEchoService);
            let req = Request::builder()
                .uri("/premium")
                .body(http_body_util::Full::new(Bytes::from(vec![0; len])))
                .unwrap();

            let resp = svc.call(req).await.unwrap();
            assert_eq!(resp.status(), status);
        }
    }

    #[tokio::test]
    async fn test_body_service_body_read_error_returns_400() {
        use tower_service::Service;

        let mut svc = body_aware_layer().layer(BodyEchoService);

        let chunks = futures_util::stream::iter([Err::<http_body::Frame<Bytes>, _>(
            std::io::Error::other("reset"),
        )]);
        let req = Request::builder()
            .uri("/premium")
            .body(http_body_util::StreamBody::new(chunks))
            .unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    }

    /// A body-aware verifier that, like `Mpp::requires_auth`, advertises
    /// `Payment-Authorization` as the credential header.
    #[derive(Clone)]
    struct PaymentAuthorizationBodyVerifier(BodyAwareVerifier);

    impl PaymentVerifier for PaymentAuthorizationBodyVerifier {
        fn challenge(&self) -> Result<String, String> {
            self.0.challenge()
        }

        fn challenge_with_body(&self, body: &[u8]) -> Result<String, String> {
            self.0.challenge_with_body(body)
        }

        fn verify(
            &self,
            credential: &str,
        ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
            self.0.verify(credential)
        }

        fn verify_with_body(
            &self,
            credential: &str,
            body: &[u8],
        ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
            self.0.verify_with_body(credential, body)
        }

        fn credential_header(&self) -> &str {
            "Payment-Authorization"
        }
    }

    #[tokio::test]
    async fn test_body_service_reads_credential_from_verifier_header() {
        use tower_service::Service;

        let verify_body = Arc::new(std::sync::Mutex::new(None));
        let layer = PaymentBodyLayer::new(PaymentAuthorizationBodyVerifier(BodyAwareVerifier {
            challenge_body: Arc::new(std::sync::Mutex::new(None)),
            verify_body: verify_body.clone(),
        }));
        let mut svc = layer.layer(BodyEchoService);

        // `Authorization` carries the app's own bearer token; the Payment
        // credential travels in the header the challenge advertised.
        let req = Request::builder()
            .uri("/premium")
            .header(header::AUTHORIZATION, "Bearer app-token")
            .header("Payment-Authorization", "Payment eyJmYWtlIjp0cnVlfQ")
            .body(http_body_util::Full::new(Bytes::from_static(
                br#"{"query":"paid"}"#,
            )))
            .unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        assert_eq!(resp.body(), br#"{"query":"paid"}"#);
        assert_eq!(
            resp.headers().get(PAYMENT_RECEIPT_HEADER).unwrap(),
            "mock-receipt-token"
        );
        assert_eq!(
            verify_body.lock().unwrap().as_deref(),
            Some(br#"{"query":"paid"}"#.as_slice())
        );
    }

    #[tokio::test]
    async fn test_body_service_ignores_credential_in_unselected_header() {
        use tower_service::Service;

        let verify_body = Arc::new(std::sync::Mutex::new(None));
        let layer = PaymentBodyLayer::new(PaymentAuthorizationBodyVerifier(BodyAwareVerifier {
            challenge_body: Arc::new(std::sync::Mutex::new(None)),
            verify_body: verify_body.clone(),
        }));
        let mut svc = layer.layer(BodyEchoService);

        let req = Request::builder()
            .uri("/premium")
            .header(header::AUTHORIZATION, "Payment eyJmYWtlIjp0cnVlfQ")
            .body(http_body_util::Full::new(Bytes::from_static(
                br#"{"query":"paid"}"#,
            )))
            .unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);
        assert_eq!(
            resp.headers().get(WWW_AUTHENTICATE_HEADER).unwrap(),
            "Payment id=\"body-bound\""
        );
        assert!(verify_body.lock().unwrap().is_none());
    }

    #[tokio::test]
    async fn test_body_service_invalid_auth_returns_body_bound_challenge() {
        use tower_service::Service;

        #[derive(Clone)]
        struct RejectingBodyVerifier;

        impl PaymentVerifier for RejectingBodyVerifier {
            fn challenge(&self) -> Result<String, String> {
                unreachable!("body middleware must use challenge_with_body")
            }

            fn challenge_with_body(&self, body: &[u8]) -> Result<String, String> {
                assert_eq!(body, br#"{"query":"paid"}"#);
                Ok(concat!(
                    "Payment id=\"replacement\", realm=\"test\", method=\"tempo\", ",
                    "intent=\"charge\", request=\"e30\""
                )
                .to_string())
            }

            fn verify(
                &self,
                _credential: &str,
            ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
                unreachable!("body middleware must use verify_with_body")
            }

            fn verify_with_body(
                &self,
                _credential: &str,
                _body: &[u8],
            ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send>> {
                Box::pin(async { Err("payment rejected".to_string()) })
            }
        }

        let layer = PaymentBodyLayer::new(RejectingBodyVerifier);
        let mut svc = layer.layer(BodyEchoService);
        let req = Request::builder()
            .uri("/premium")
            .header(header::AUTHORIZATION, "Payment invalid")
            .body(http_body_util::Full::new(Bytes::from_static(
                br#"{"query":"paid"}"#,
            )))
            .unwrap();

        let resp = svc.call(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);
        let challenge = resp.headers().get(WWW_AUTHENTICATE_HEADER).unwrap();
        let parsed =
            crate::protocol::core::headers::parse_www_authenticate(challenge.to_str().unwrap())
                .unwrap();
        assert_eq!(parsed.id, "replacement");
        assert_eq!(
            resp.headers().get(header::CACHE_CONTROL).unwrap(),
            "no-store"
        );
    }

    #[tokio::test]
    async fn test_body_service_does_not_attach_receipt_to_error_response() {
        use tower_service::Service;

        for status in [
            StatusCode::FOUND,
            StatusCode::FORBIDDEN,
            StatusCode::INTERNAL_SERVER_ERROR,
        ] {
            let layer = PaymentBodyLayer::new(BodyAwareVerifier {
                challenge_body: Arc::new(std::sync::Mutex::new(None)),
                verify_body: Arc::new(std::sync::Mutex::new(None)),
            });
            let mut svc = layer.layer(StatusService(status));
            let req = Request::builder()
                .uri("/premium")
                .header(header::AUTHORIZATION, "Payment eyJmYWtlIjp0cnVlfQ")
                .body(http_body_util::Full::new(Bytes::from_static(b"paid")))
                .unwrap();

            let resp = svc.call(req).await.unwrap();
            assert_eq!(resp.status(), status);
            assert!(!resp.headers().contains_key(PAYMENT_RECEIPT_HEADER));
            assert!(!resp.headers().contains_key(header::CACHE_CONTROL));
        }
    }

    // ==================== Real ChargeVerifier tests ====================
    //
    // These tests exercise PaymentLayer with real challenge formatting,
    // HMAC-bound IDs, and the full parse_authorization → verify_credential
    // round-trip, using a mock ChargeMethod to avoid RPC calls.

    #[cfg(feature = "tempo")]
    mod real_charge_verifier {
        use super::*;
        use crate::protocol::core::challenge::{PaymentCredential, PaymentPayload, Receipt};
        use crate::protocol::core::headers::{
            format_authorization, parse_receipt, parse_www_authenticate, parse_www_authenticate_all,
        };
        use crate::protocol::core::PaymentChallenge;
        use crate::protocol::intents::ChargeRequest;
        use crate::protocol::traits::{ChargeMethod, VerificationError};
        use crate::server::Mpp;
        use tower_layer::Layer;
        use tower_service::Service;

        #[derive(Clone)]
        struct SuccessChargeMethod;

        impl ChargeMethod for SuccessChargeMethod {
            fn method(&self) -> &str {
                "tempo"
            }

            async fn verify(
                &self,
                _credential: &PaymentCredential,
                _request: &ChargeRequest,
            ) -> std::result::Result<Receipt, VerificationError> {
                Ok(Receipt::success("tempo", "0xabc123"))
            }
        }

        fn create_mpp_with_mock() -> Mpp<SuccessChargeMethod> {
            Mpp::new_with_config(
                SuccessChargeMethod,
                "test-realm",
                "test-secret-key-at-least-32-bytes",
                "0x20c0000000000000000000000000000000000000",
                "0x742d35Cc6634C0532925a3b844Bc9e7595f1B0F2",
            )
        }

        #[derive(Clone)]
        struct OkService;

        impl tower_service::Service<Request<()>> for OkService {
            type Response = Response<()>;
            type Error = std::convert::Infallible;
            type Future = Pin<Box<dyn Future<Output = Result<Response<()>, Self::Error>> + Send>>;

            fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
                Poll::Ready(Ok(()))
            }

            fn call(&mut self, _req: Request<()>) -> Self::Future {
                Box::pin(async { Ok(Response::new(())) })
            }
        }

        #[tokio::test]
        async fn test_no_auth_returns_402_with_parseable_challenge() {
            let mpp = create_mpp_with_mock();
            let layer = PaymentLayer::charge(&mpp, "0.10").unwrap();
            let mut svc = layer.layer(OkService);

            let req = Request::builder().uri("/premium").body(()).unwrap();
            let resp = svc.call(req).await.unwrap();

            assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);

            let www_auth = resp
                .headers()
                .get(WWW_AUTHENTICATE_HEADER)
                .expect("missing WWW-Authenticate header")
                .to_str()
                .unwrap();

            let challenge = parse_www_authenticate(www_auth)
                .expect("WWW-Authenticate header should be parseable");

            assert_eq!(challenge.method.as_str(), "tempo");
            assert_eq!(challenge.intent.as_str(), "charge");
            assert_eq!(challenge.realm, "test-realm");
            assert!(!challenge.id.is_empty());

            let request: ChargeRequest = challenge.request.decode().unwrap();
            assert_eq!(request.amount, "100000");
            assert_eq!(
                request.currency,
                "0x20c0000000000000000000000000000000000000"
            );
            assert_eq!(
                request.recipient,
                Some("0x742d35Cc6634C0532925a3b844Bc9e7595f1B0F2".into())
            );
        }

        #[tokio::test]
        async fn test_valid_credential_roundtrip_returns_200_with_receipt() {
            let mpp = create_mpp_with_mock();
            let layer = PaymentLayer::charge(&mpp, "0.10").unwrap();

            // First call: get the challenge from 402.
            let mut svc = layer.layer(OkService);
            let req = Request::builder().uri("/premium").body(()).unwrap();
            let resp = svc.call(req).await.unwrap();
            assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);

            let www_auth = resp
                .headers()
                .get(WWW_AUTHENTICATE_HEADER)
                .unwrap()
                .to_str()
                .unwrap();
            let challenge = parse_www_authenticate(www_auth).unwrap();

            // Build a credential from the challenge.
            let credential =
                PaymentCredential::new(challenge.to_echo(), PaymentPayload::hash("0xdeadbeef"));
            let auth_header = format_authorization(&credential).unwrap();

            // Second call: send credential, expect 200 + receipt.
            let mut svc = layer.layer(OkService);
            let req = Request::builder()
                .uri("/premium")
                .header(header::AUTHORIZATION, &auth_header)
                .body(())
                .unwrap();
            let resp = svc.call(req).await.unwrap();

            assert_eq!(resp.status(), StatusCode::OK);

            let receipt_header = resp
                .headers()
                .get(PAYMENT_RECEIPT_HEADER)
                .expect("missing Payment-Receipt header")
                .to_str()
                .unwrap();
            let receipt =
                parse_receipt(receipt_header).expect("Payment-Receipt header should be parseable");
            assert!(receipt.is_success());
            assert_eq!(receipt.method.as_str(), "tempo");
            assert_eq!(receipt.reference, "0xabc123");
        }

        #[tokio::test]
        async fn test_wrong_scheme_returns_402() {
            let mpp = create_mpp_with_mock();
            let layer = PaymentLayer::charge(&mpp, "0.10").unwrap();
            let mut svc = layer.layer(OkService);

            let req = Request::builder()
                .uri("/premium")
                .header(header::AUTHORIZATION, "Bearer some-token")
                .body(())
                .unwrap();
            let resp = svc.call(req).await.unwrap();

            assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);
            assert!(resp.headers().contains_key(WWW_AUTHENTICATE_HEADER));
        }

        fn create_multi_currency_mpp() -> Mpp<SuccessChargeMethod> {
            create_mpp_with_mock().with_currencies(vec![
                crate::protocol::methods::tempo::OUSD.to_string(),
                crate::protocol::methods::tempo::USDC.to_string(),
            ])
        }

        fn offered_challenges<B>(resp: &Response<B>) -> Vec<PaymentChallenge> {
            let values = resp
                .headers()
                .get_all(WWW_AUTHENTICATE_HEADER)
                .iter()
                .map(|v| v.to_str().unwrap())
                .collect::<Vec<_>>();
            parse_www_authenticate_all(values)
                .into_iter()
                .map(|challenge| challenge.unwrap())
                .collect()
        }

        fn currencies_of(challenges: &[PaymentChallenge]) -> Vec<String> {
            challenges
                .iter()
                .map(|c| c.request.decode::<ChargeRequest>().unwrap().currency)
                .collect()
        }

        #[tokio::test]
        async fn test_no_auth_returns_every_currency_offer_in_order() {
            use crate::protocol::methods::tempo::{OUSD, USDC};

            let layer = PaymentLayer::charge(&create_multi_currency_mpp(), "0.10").unwrap();
            let mut svc = layer.layer(OkService);
            let req = Request::builder().uri("/premium").body(()).unwrap();
            let resp = svc.call(req).await.unwrap();

            assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);
            let challenges = offered_challenges(&resp);
            assert_eq!(currencies_of(&challenges), [OUSD, USDC]);
            assert!(challenges
                .iter()
                .all(|c| c.verify("test-secret-key-at-least-32-bytes")));
        }

        #[tokio::test]
        async fn test_credential_for_each_offer_returns_200() {
            use crate::protocol::methods::tempo::{OUSD, USDC};

            let layer = PaymentLayer::charge(&create_multi_currency_mpp(), "0.10").unwrap();
            let resp = layer
                .layer(OkService)
                .call(Request::builder().uri("/premium").body(()).unwrap())
                .await
                .unwrap();
            let challenges = offered_challenges(&resp);

            for (challenge, currency) in challenges.iter().zip([OUSD, USDC]) {
                let credential =
                    PaymentCredential::new(challenge.to_echo(), PaymentPayload::hash("0xdeadbeef"));
                let auth_header = format_authorization(&credential).unwrap();
                let req = Request::builder()
                    .uri("/premium")
                    .header(header::AUTHORIZATION, &auth_header)
                    .body(())
                    .unwrap();
                let resp = layer.layer(OkService).call(req).await.unwrap();
                assert_eq!(resp.status(), StatusCode::OK, "{currency} offer rejected");
                assert!(resp.headers().contains_key(PAYMENT_RECEIPT_HEADER));
            }
        }

        #[tokio::test]
        async fn test_credential_for_non_offered_currency_returns_402() {
            use crate::protocol::methods::tempo::{OUSD, USDC};

            // pathUSD challenge signed with the same secret/realm but not offered.
            let foreign = create_mpp_with_mock().charge("0.10").unwrap().remove(0);
            let credential =
                PaymentCredential::new(foreign.to_echo(), PaymentPayload::hash("0xdeadbeef"));
            let auth_header = format_authorization(&credential).unwrap();

            let layer = PaymentLayer::charge(&create_multi_currency_mpp(), "0.10").unwrap();
            let req = Request::builder()
                .uri("/premium")
                .header(header::AUTHORIZATION, &auth_header)
                .body(())
                .unwrap();
            let resp = layer.layer(OkService).call(req).await.unwrap();
            assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);
            assert_eq!(currencies_of(&offered_challenges(&resp)), [OUSD, USDC]);
        }

        #[tokio::test]
        async fn test_body_layer_binds_every_currency_offer() {
            use crate::protocol::methods::tempo::{OUSD, USDC};

            let verifier = PaymentBodyLayer::charge(&create_multi_currency_mpp(), "0.10")
                .unwrap()
                .verifier;
            let header = verifier.challenge_with_body(b"{}").unwrap();
            let challenges = parse_www_authenticate_all([header.as_str()])
                .into_iter()
                .map(|challenge| challenge.unwrap())
                .collect::<Vec<_>>();
            assert_eq!(currencies_of(&challenges), [OUSD, USDC]);
            let digest = crate::body_digest::compute(b"{}");
            assert!(challenges
                .iter()
                .all(|c| c.digest.as_deref() == Some(digest.as_str())));
        }

        #[tokio::test]
        async fn test_garbage_authorization_returns_402() {
            let mpp = create_mpp_with_mock();
            let layer = PaymentLayer::charge(&mpp, "0.10").unwrap();
            let mut svc = layer.layer(OkService);

            let req = Request::builder()
                .uri("/premium")
                .header(header::AUTHORIZATION, "Payment not-valid-base64!!!")
                .body(())
                .unwrap();
            let resp = svc.call(req).await.unwrap();

            assert_eq!(resp.status(), StatusCode::PAYMENT_REQUIRED);
        }
    }
}