autumn-web 0.9.0

//! Agent commerce: x402 payments, MPP discovery, UCP and ACP documents.
//!
//! | Protocol | What Autumn does |
//! |---|---|
//! | x402 | Priced routes answer `402` with `PAYMENT-REQUIRED`. The facilitator verifies and settles a retry that has `PAYMENT-SIGNATURE`. |
//! | MPP | Priced routes with an `mpp_method` get `x-payment-info` in `/openapi.json`. The app runs the MPP payment itself. |
//! | UCP | [`UcpProfile`] is served at `/.well-known/ucp`. |
//! | ACP | [`AcpDiscovery`] is served at `/.well-known/acp.json`. |
//!
//! ```toml
//! [aeo.x402]
//! facilitator_url = "https://x402.org/facilitator"
//! pay_to = "0x209693Bc6afc0C5328bA36FaF03C514EF312287C"
//! network = "eip155:84532"
//! asset = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
//!
//! [[aeo.paid_routes]]
//! method = "GET"
//! path = "/api"
//! amount = "10000"
//! description = "Premium data"
//! ```

use base64::Engine as _;
use base64::engine::general_purpose::STANDARD;
use serde::Deserialize;
use serde_json::{Value, json};
#[cfg(feature = "http-client")]
use sha2::Digest as _;

/// Path of the UCP profile.
pub const UCP_PATH: &str = "/.well-known/ucp";
/// Path of the ACP discovery document.
pub const ACP_PATH: &str = "/.well-known/acp.json";

/// `[aeo.x402]`: where and how to get paid.
#[derive(Debug, Clone, Default, Deserialize)]
#[non_exhaustive]
pub struct X402Config {
    /// Facilitator base URL. It verifies and settles payments.
    #[serde(default)]
    pub facilitator_url: Option<String>,
    /// Wallet address that receives payments.
    #[serde(default)]
    pub pay_to: Option<String>,
    /// CAIP-2 network, e.g. `eip155:8453` (Base).
    #[serde(default)]
    pub network: Option<String>,
    /// Token contract address, e.g. USDC.
    #[serde(default)]
    pub asset: Option<String>,
    /// Token name for the EIP-712 domain. Default: `USDC`.
    #[serde(default)]
    pub asset_name: Option<String>,
    /// Token version for the EIP-712 domain. Default: `2`.
    #[serde(default)]
    pub asset_version: Option<String>,
    /// Payment scheme. Default: `exact`.
    #[serde(default)]
    pub scheme: Option<String>,
    /// Seconds the client has to pay. Default: 300.
    #[serde(default)]
    pub max_timeout_secs: Option<u64>,
}

/// `[[aeo.paid_routes]]`: one priced route.
#[derive(Debug, Clone, Default, Deserialize)]
#[non_exhaustive]
pub struct PaidRoute {
    /// HTTP method, e.g. `GET`.
    pub method: String,
    /// Route path. `{name}` matches one segment.
    pub path: String,
    /// Price in the asset's smallest unit, as digits.
    pub amount: String,
    /// What the payment buys.
    #[serde(default)]
    pub description: Option<String>,
    /// MPP payment method (`stripe`, `tempo`, `lightning`, `card`). When set,
    /// `/openapi.json` carries `x-payment-info` for this route.
    #[serde(default)]
    pub mpp_method: Option<String>,
    /// MPP currency, e.g. `usd`.
    #[serde(default)]
    pub mpp_currency: Option<String>,
    /// MPP amount in the smallest unit. Default: `amount`.
    #[serde(default)]
    pub mpp_amount: Option<String>,
}

impl PaidRoute {
    /// A priced route. `amount` is in the asset's smallest unit.
    #[must_use]
    pub fn new(
        method: impl Into<String>,
        path: impl Into<String>,
        amount: impl Into<String>,
    ) -> Self {
        Self {
            method: method.into(),
            path: path.into(),
            amount: amount.into(),
            ..Self::default()
        }
    }

    /// `true` when `method` and `path` match this route.
    ///
    /// `HEAD` matches a `GET` route (axum runs the `GET` handler for it). One
    /// trailing `/` is ignored, as the static page layer does. `{name}`
    /// matches one segment; `{*name}` matches the rest of the path.
    #[must_use]
    pub fn matches(&self, method: &str, path: &str) -> bool {
        self.method_matches(method) && template_matches(&self.path, path)
    }

    fn method_matches(&self, method: &str) -> bool {
        self.method.eq_ignore_ascii_case(method)
            || (method.eq_ignore_ascii_case("HEAD") && self.method.eq_ignore_ascii_case("GET"))
    }

    /// `true` for a route x402 charges: an MPP route is paid through the
    /// app's own MPP flow instead.
    #[must_use]
    pub const fn is_x402(&self) -> bool {
        self.mpp_method.is_none()
    }
}

/// Strip one trailing `/` (but keep `/`).
fn normalize(path: &str) -> &str {
    if path.len() > 1 {
        path.strip_suffix('/').unwrap_or(path)
    } else {
        path
    }
}

/// Match a concrete `path` against a route `template`.
fn template_matches(template: &str, path: &str) -> bool {
    let mut want = normalize(template).split('/');
    let mut got = normalize(path).split('/');
    loop {
        match (want.next(), got.next()) {
            (None, None) => return true,
            (Some(w), Some(g)) => {
                if w.starts_with("{*") && w.ends_with('}') {
                    return !g.is_empty();
                }
                let is_param = w.starts_with('{') && w.ends_with('}');
                if (is_param && g.is_empty()) || (!is_param && w != g) {
                    return false;
                }
            }
            _ => return false,
        }
    }
}

/// `true` for an amount in the smallest unit: ASCII digits, no leading zero.
#[must_use]
pub fn valid_amount(amount: &str) -> bool {
    !amount.is_empty()
        && amount.bytes().all(|b| b.is_ascii_digit())
        && (amount == "0" || !amount.starts_with('0'))
}

/// Why `route` can never match a request, if it cannot.
///
/// That is a method that is not an HTTP method, or a path that does not
/// start with `/`. Such an x402 route would serve its handler free, so the
/// config is refused at startup.
#[must_use]
pub fn unmatchable_route(route: &PaidRoute) -> Option<String> {
    const METHODS: [&str; 7] = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
    // Matching compares the method as written, so no trimming here.
    if !METHODS
        .iter()
        .any(|m| m.eq_ignore_ascii_case(&route.method))
    {
        return Some(format!(
            "{:?} {}: method must be one of {}",
            route.method,
            route.path,
            METHODS.join(", ")
        ));
    }
    // Matching reads only the request path: a query or a fragment in the
    // template never matches.
    if !route.path.starts_with('/')
        || route
            .path
            .chars()
            .any(|c| c.is_whitespace() || c == '?' || c == '#')
    {
        return Some(format!(
            "{} {:?}: path must start with `/`, with no spaces, query, or fragment",
            route.method, route.path
        ));
    }
    if !valid_template(&route.path) {
        return Some(format!(
            "{} {:?}: a capture must be a whole `{{name}}` segment, and `{{*name}}` only last",
            route.method, route.path
        ));
    }
    None
}

/// A route priced for both x402 and MPP, if any.
///
/// x402 would answer every MPP client with its own challenge, so the config
/// is refused at startup. An x402 `GET` entry also prices `HEAD`, so it
/// clashes with an MPP `HEAD`.
#[must_use]
pub fn mixed_protocol_route(routes: &[PaidRoute]) -> Option<String> {
    routes.iter().filter(|r| r.is_x402()).find_map(|x402| {
        routes
            .iter()
            .filter(|r| !r.is_x402())
            .find(|mpp| x402.method_matches(&mpp.method) && same_template(&mpp.path, &x402.path))
            .map(|mpp| {
                format!(
                    "{} {:?} is priced for both x402 and MPP (`mpp_method` on {:?}); price it \
                     with one",
                    x402.method, x402.path, mpp.path
                )
            })
    })
}

/// `true` when two route templates name the same route: the same literal
/// segments, and a capture (any name) or a catch-all at the same places.
/// One trailing `/` does not count; [`PricedRoutes::lookup`] tells the two
/// apart when the app routes both.
fn same_template(left: &str, right: &str) -> bool {
    same_shape(normalize(left), normalize(right))
}

/// [`same_template`], with a trailing `/` counting: axum routes `/report`
/// and `/report/` apart.
fn same_shape(left: &str, right: &str) -> bool {
    let kind = |segment: &str| {
        if segment.starts_with("{*") && segment.ends_with('}') {
            "*"
        } else if segment.starts_with('{') && segment.ends_with('}') {
            "{}"
        } else {
            ""
        }
    };
    let mut lhs = left.split('/');
    let mut rhs = right.split('/');
    loop {
        match (lhs.next(), rhs.next()) {
            (None, None) => return true,
            (Some(l), Some(r)) => {
                if kind(l) != kind(r) || (kind(l).is_empty() && l != r) {
                    return false;
                }
            }
            _ => return false,
        }
    }
}

/// How specific `template` is, as axum's router ranks routes: at the first
/// segment where two matching templates differ, a literal beats a `{name}`
/// capture, which beats a `{*name}` catch-all.
fn specificity(template: &str) -> Vec<u8> {
    normalize(template)
        .split('/')
        .map(|segment| {
            if segment.starts_with("{*") {
                0
            } else if segment.starts_with('{') {
                1
            } else {
                2
            }
        })
        .collect()
}

/// `true` for a route template axum accepts and the matcher reads: a
/// segment with a brace is a whole `{name}` capture, or a `{*name}`
/// catch-all in the last place.
fn valid_template(path: &str) -> bool {
    let segments: Vec<&str> = path.split('/').collect();
    segments.iter().enumerate().all(|(i, s)| {
        if !s.contains(['{', '}']) {
            return true;
        }
        let Some(inner) = s.strip_prefix('{').and_then(|s| s.strip_suffix('}')) else {
            return false;
        };
        let (name, catch_all) = inner
            .strip_prefix('*')
            .map_or((inner, false), |n| (n, true));
        !name.is_empty()
            && !name.contains(['{', '}', '*'])
            && (!catch_all || i == segments.len() - 1)
    })
}

/// Problems in `[[aeo.paid_routes]]`, one message each. A priced x402 route
/// with a problem answers `503`.
#[must_use]
pub fn paid_route_problems(routes: &[PaidRoute]) -> Vec<String> {
    let mut problems = Vec::new();
    for r in routes {
        problems.extend(unmatchable_route(r));
        if !valid_amount(&r.amount) {
            problems.push(format!(
                "{} {}: amount {:?} is not digits",
                r.method, r.path, r.amount
            ));
        }
        if let Some(m) = &r.mpp_method {
            if m.is_empty() || m.bytes().any(|b| !(b.is_ascii_lowercase() || b == b'-')) {
                problems.push(format!(
                    "{} {}: mpp_method {m:?} must be lowercase",
                    r.method, r.path
                ));
            }
            if r.mpp_amount.as_deref().is_some_and(|a| !valid_amount(a)) {
                problems.push(format!("{} {}: mpp_amount is not digits", r.method, r.path));
            }
        }
    }
    problems
}

fn route_is_valid(r: &PaidRoute) -> bool {
    paid_route_problems(std::slice::from_ref(r)).is_empty()
}

impl X402Config {
    /// `true` when every field the 402 challenge needs is set.
    #[must_use]
    pub fn is_complete(&self) -> bool {
        [
            &self.facilitator_url,
            &self.pay_to,
            &self.network,
            &self.asset,
        ]
        .iter()
        .all(|v| v.as_deref().is_some_and(|v| !v.trim().is_empty()))
    }

    /// The x402 v2 `PaymentRequirements` for `route`.
    #[must_use]
    pub fn requirements(&self, route: &PaidRoute) -> Value {
        json!({
            "scheme": self.scheme.as_deref().unwrap_or("exact"),
            "network": self.network.as_deref().unwrap_or_default(),
            "amount": route.amount,
            "asset": self.asset.as_deref().unwrap_or_default(),
            "payTo": self.pay_to.as_deref().unwrap_or_default(),
            "maxTimeoutSeconds": self.max_timeout_secs.unwrap_or(300),
            "extra": {
                "name": self.asset_name.as_deref().unwrap_or("USDC"),
                "version": self.asset_version.as_deref().unwrap_or("2"),
            },
        })
    }

    /// The x402 v2 `PaymentRequired` object for `route` at `resource_url`.
    #[must_use]
    pub fn payment_required(&self, route: &PaidRoute, resource_url: &str, error: &str) -> Value {
        json!({
            "x402Version": 2,
            "error": error,
            // No `mimeType`: it is optional, and a priced route may answer
            // HTML, JSON or a file.
            "resource": {
                "url": resource_url,
                "description": route.description.as_deref().unwrap_or_default(),
            },
            "accepts": [self.requirements(route)],
        })
    }
}

/// Encode a JSON value for an x402 header: standard padded base64.
#[must_use]
pub fn encode_header(value: &Value) -> String {
    STANDARD.encode(value.to_string())
}

/// Decode an x402 header into JSON. `None` for bad base64 or JSON.
#[must_use]
pub fn decode_header(header: &str) -> Option<Value> {
    let bytes = STANDARD.decode(header.trim()).ok()?;
    serde_json::from_slice(&bytes).ok()
}

/// `true` when the client's `accepted` requirements are the ones offered.
#[must_use]
#[cfg_attr(not(feature = "http-client"), allow(dead_code))]
pub(crate) fn accepted_matches(accepted: &Value, offered: &Value) -> bool {
    ["scheme", "network", "amount", "asset", "payTo"]
        .iter()
        .all(|k| accepted.get(k).is_some() && accepted.get(k) == offered.get(k))
}

/// Add MPP `x-payment-info` and a `402` response to each priced operation
/// in an `OpenAPI` document.
pub(crate) fn apply_mpp(spec: &mut Value, routes: &[PaidRoute]) {
    for route in routes.iter().filter(|r| route_is_valid(r)) {
        let Some(method) = route.mpp_method.as_deref() else {
            continue;
        };
        // Match the operation as `PricedRoutes` matches a route: capture
        // names do not count, and one trailing `/` counts only when the spec
        // has both forms (the exact one wins).
        let Some(op) = spec
            .get_mut("paths")
            .and_then(Value::as_object_mut)
            .and_then(|paths| {
                let key = paths
                    .keys()
                    .find(|k| same_shape(k, &route.path))
                    .or_else(|| paths.keys().find(|k| same_template(k, &route.path)))?
                    .clone();
                paths.get_mut(&key)
            })
            .and_then(|p| p.get_mut(route.method.to_ascii_lowercase()))
            .and_then(Value::as_object_mut)
        else {
            continue;
        };
        let mut info = json!({
            "intent": "charge",
            "method": method,
            "amount": route.mpp_amount.as_deref().unwrap_or(&route.amount),
        });
        if let Some(currency) = &route.mpp_currency {
            info["currency"] = json!(currency);
        }
        if let Some(d) = &route.description {
            info["description"] = json!(d);
        }
        op.insert("x-payment-info".to_owned(), info);
        // A `402` the app documents already is kept as it is.
        let responses = op.entry("responses").or_insert_with(|| json!({}));
        if let Some(responses) = responses.as_object_mut() {
            responses
                .entry("402")
                .or_insert_with(|| json!({ "description": "Payment Required" }));
        }
    }
}

/// The `OpenAPI` JSON for `spec`, with MPP `x-payment-info` when a priced
/// route has an `mpp_method`. A spec with no MPP route keeps its key order
/// (`serde_json` sorts the keys of a `Value` map).
///
/// # Errors
///
/// A `serde_json` error when the spec does not serialize.
pub fn spec_json_with_mpp(
    spec: &impl serde::Serialize,
    config: &crate::config::AutumnConfig,
) -> serde_json::Result<String> {
    if !has_mpp(config) {
        return serde_json::to_string_pretty(spec);
    }
    let mut value = serde_json::to_value(spec)?;
    apply_mpp(&mut value, &config.aeo.paid_routes);
    serde_json::to_string_pretty(&value)
}

/// Rewrite `dist/openapi.json` and `dist/openapi.yaml` with MPP
/// `x-payment-info`, when a priced route has an `mpp_method`.
///
/// # Errors
///
/// An I/O error when a file cannot be written.
#[cfg(feature = "openapi")]
pub fn write_mpp_spec(
    spec: &crate::openapi::OpenApiSpec,
    config: &crate::config::AutumnConfig,
    dist_dir: &std::path::Path,
) -> std::io::Result<()> {
    if !has_mpp(config) {
        return Ok(());
    }
    let mut value = serde_json::to_value(spec).map_err(std::io::Error::other)?;
    apply_mpp(&mut value, &config.aeo.paid_routes);
    let json = serde_json::to_string_pretty(&value).map_err(std::io::Error::other)?;
    std::fs::write(dist_dir.join("openapi.json"), json)?;
    let yaml = serde_saphyr::to_string(&value).map_err(std::io::Error::other)?;
    std::fs::write(dist_dir.join("openapi.yaml"), yaml)
}

fn has_mpp(config: &crate::config::AutumnConfig) -> bool {
    config.aeo.enabled
        && config
            .aeo
            .paid_routes
            .iter()
            .any(|r| r.mpp_method.is_some())
}

/// An invalid commerce document.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum CommerceError {
    /// A required field is missing, empty, or has a wrong value.
    #[error("{doc}: `{field}` is missing or not valid")]
    Invalid {
        /// Document name.
        doc: &'static str,
        /// Field path.
        field: &'static str,
    },
}

/// A UCP business profile, served at `/.well-known/ucp`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UcpProfile(Value);

impl UcpProfile {
    /// Check the required UCP fields: `ucp.version`, `ucp.services`,
    /// `ucp.payment_handlers`.
    ///
    /// # Errors
    ///
    /// [`CommerceError::Invalid`] for the first missing field.
    pub fn new(profile: Value) -> Result<Self, CommerceError> {
        let missing = |field| CommerceError::Invalid {
            doc: "UCP profile",
            field,
        };
        let ucp = profile.get("ucp").ok_or_else(|| missing("ucp"))?;
        if ucp
            .get("version")
            .and_then(Value::as_str)
            .is_none_or(str::is_empty)
        {
            return Err(missing("ucp.version"));
        }
        if !ucp.get("services").is_some_and(Value::is_object) {
            return Err(missing("ucp.services"));
        }
        if !ucp.get("payment_handlers").is_some_and(Value::is_object) {
            return Err(missing("ucp.payment_handlers"));
        }
        Ok(Self(profile))
    }

    /// The profile JSON.
    #[must_use]
    pub const fn as_json(&self) -> &Value {
        &self.0
    }
}

/// An ACP discovery document, served at `/.well-known/acp.json`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AcpDiscovery(Value);

impl AcpDiscovery {
    /// Check the required ACP fields: `protocol.name = "acp"`,
    /// `protocol.version`, `protocol.supported_versions`, an absolute
    /// `api_base_url`, `transports`, and `capabilities.services`.
    ///
    /// # Errors
    ///
    /// [`CommerceError::Invalid`] for the first missing field.
    pub fn new(document: Value) -> Result<Self, CommerceError> {
        let missing = |field| CommerceError::Invalid {
            doc: "ACP discovery",
            field,
        };
        let non_empty_str =
            |v: Option<&Value>| v.and_then(Value::as_str).is_some_and(|s| !s.is_empty());
        let non_empty_arr =
            |v: Option<&Value>| v.and_then(Value::as_array).is_some_and(|a| !a.is_empty());
        let protocol = document.get("protocol");
        if protocol.and_then(|p| p.get("name")).and_then(Value::as_str) != Some("acp") {
            return Err(missing("protocol.name"));
        }
        if !non_empty_str(protocol.and_then(|p| p.get("version"))) {
            return Err(missing("protocol.version"));
        }
        if !non_empty_arr(protocol.and_then(|p| p.get("supported_versions"))) {
            return Err(missing("protocol.supported_versions"));
        }
        let absolute = document
            .get("api_base_url")
            .and_then(Value::as_str)
            .and_then(|u| url::Url::parse(u).ok())
            .is_some_and(|u| matches!(u.scheme(), "http" | "https"));
        if !absolute {
            return Err(missing("api_base_url"));
        }
        if !non_empty_arr(document.get("transports")) {
            return Err(missing("transports"));
        }
        if !non_empty_arr(document.get("capabilities").and_then(|c| c.get("services"))) {
            return Err(missing("capabilities.services"));
        }
        Ok(Self(document))
    }

    /// The document JSON.
    #[must_use]
    pub const fn as_json(&self) -> &Value {
        &self.0
    }
}

// ── x402 layer ──────────────────────────────────────────────────────────────

/// Tower layer that charges for [`PaidRoute`]s with x402.
///
/// 1. A request without `PAYMENT-SIGNATURE` gets `402` and `PAYMENT-REQUIRED`.
/// 2. The facilitator verifies a request that has it (`POST /verify`).
/// 3. `GET` and `HEAD`: the handler runs, then the facilitator settles a
///    `2xx` answer. Other methods: the facilitator settles first, then the
///    handler runs.
/// 4. The response carries `PAYMENT-RESPONSE` and `Cache-Control: private,
///    no-store`. If settlement fails, Autumn sends `402` and no handler body.
///
/// One payment header works once per process: a second use gets `402`.
#[cfg(feature = "http-client")]
#[derive(Clone)]
pub(crate) struct X402Layer {
    state: std::sync::Arc<X402State>,
    static_paths: StaticPaths,
}

#[cfg(feature = "http-client")]
struct X402State {
    config: X402Config,
    priced: PricedRoutes,
    /// `false` when `[aeo.x402]` cannot work as written: priced routes then
    /// answer `503`, never free.
    available: bool,
    client: crate::http_client::Client,
    base_url: Option<String>,
    /// SHA-256 of each payment header already used.
    used: std::sync::Mutex<UsedPayments>,
}

/// Payment headers already used, each kept until its payment expires.
///
/// A live record is never evicted: with every slot taken by an unexpired
/// payment, a new one is refused (`503`) rather than reopening a replay.
#[cfg(feature = "http-client")]
#[derive(Debug)]
struct UsedPayments {
    /// Header hash to the Unix second its payment expires.
    until: std::collections::HashMap<[u8; 32], u64>,
    capacity: usize,
}

#[cfg(feature = "http-client")]
#[derive(Debug, PartialEq, Eq)]
enum ClaimError {
    /// This header was already used.
    Used,
    /// Every slot holds an unexpired payment.
    Full,
}

#[cfg(feature = "http-client")]
impl UsedPayments {
    fn new(capacity: usize) -> Self {
        Self {
            until: std::collections::HashMap::new(),
            capacity,
        }
    }

    /// Claim `key` until `expires` (Unix seconds).
    fn claim(&mut self, key: [u8; 32], expires: u64, now: u64) -> Result<(), ClaimError> {
        if self.until.contains_key(&key) {
            return Err(ClaimError::Used);
        }
        if self.until.len() >= self.capacity {
            self.until.retain(|_, until| *until > now);
            if self.until.len() >= self.capacity {
                return Err(ClaimError::Full);
            }
        }
        self.until.insert(key, expires);
        Ok(())
    }

    /// Give back a claim for a payment that was not used.
    fn release(&mut self, key: &[u8; 32]) {
        self.until.remove(key);
    }
}

/// The identity of a payment proof, for the replay record. The same proof
/// written another way (key order, whitespace, base64 form, hex case, a
/// padded nonce) gets the same key. An EIP-3009 authorization is its
/// network, asset, payer and nonce, which the chain itself spends once;
/// another proof is its signature, or else its signed payload with sorted
/// keys.
#[cfg(feature = "http-client")]
fn payment_key(payload: &Value) -> [u8; 32] {
    // Hex as a value: case, a `0x` prefix and leading zeros do not count.
    fn hex_value(v: &Value) -> String {
        let s = match v {
            Value::String(s) => s.to_ascii_lowercase(),
            other => other.to_string(),
        };
        let s = s.strip_prefix("0x").unwrap_or(&s);
        s.trim_start_matches('0').to_owned()
    }
    let proof = &payload["payload"];
    let auth = &proof["authorization"];
    let mut hasher = sha2::Sha256::new();
    if auth["from"].is_string() && !auth["nonce"].is_null() {
        hasher.update(b"eip3009");
        for part in [
            &payload["accepted"]["network"],
            &payload["accepted"]["asset"],
            &auth["from"],
            &auth["nonce"],
        ] {
            hasher.update(b"\0");
            hasher.update(hex_value(part).as_bytes());
        }
    } else if let Some(signature) = proof["signature"].as_str() {
        hasher.update(b"signature\0");
        hasher.update(signature.to_ascii_lowercase().as_bytes());
    } else {
        hasher.update(b"payload\0");
        hasher.update(canonical_json(proof).as_bytes());
    }
    hasher.finalize().into()
}

/// JSON with object keys sorted, whatever order they arrived in.
#[cfg(feature = "http-client")]
fn canonical_json(value: &Value) -> String {
    match value {
        Value::Object(map) => {
            let mut keys: Vec<&String> = map.keys().collect();
            keys.sort();
            let fields: Vec<String> = keys
                .into_iter()
                .map(|k| format!("{}:{}", Value::from(k.as_str()), canonical_json(&map[k])))
                .collect();
            format!("{{{}}}", fields.join(","))
        }
        Value::Array(items) => {
            let items: Vec<String> = items.iter().map(canonical_json).collect();
            format!("[{}]", items.join(","))
        }
        other => other.to_string(),
    }
}

/// When a payment stops being valid: its EIP-3009 `validBefore`, else the
/// offered `maxTimeoutSeconds` from now.
#[cfg(feature = "http-client")]
fn payment_expiry(payload: &Value, max_timeout_secs: u64, now: u64) -> u64 {
    let valid_before = &payload["payload"]["authorization"]["validBefore"];
    valid_before
        .as_u64()
        .or_else(|| valid_before.as_str().and_then(|s| s.parse().ok()))
        .unwrap_or_else(|| now.saturating_add(max_timeout_secs))
}

/// Marks a request that one x402 layer already handled, so the second copy
/// (SSG path: one outside the static layer, one inside) does not charge
/// again.
#[cfg(feature = "http-client")]
#[derive(Debug, Clone, Copy)]
struct X402Handled;

/// The priced routes, and the locale prefixes to strip.
#[derive(Debug, Clone)]
struct PricedRoutes {
    routes: Vec<PaidRoute>,
    /// Supported locales when locale-prefixed routing is on: `/en/x` is the
    /// route `/x`.
    locales: Vec<String>,
    /// Priced paths `locale_prefix_exclude` keeps out of the locale nests:
    /// `/en/x` is never one of them, but may be another route of its own.
    unprefixed: Vec<String>,
    /// Every template the app mounts (see [`RoutedTemplates`]).
    mounted: Vec<String>,
    /// The top-level routes the router nests under each locale.
    nested: Vec<String>,
}

/// What the router mounted, recorded at build time.
#[derive(Debug, Clone, Default)]
pub(crate) struct RoutedTemplates {
    /// Every route template, as `MatchedPath` names it. With it, a priced
    /// `/report` does not price the app's own free `/report/`.
    pub(crate) mounted: Vec<String>,
    /// The paths of the top-level routes nested under each locale. A priced
    /// route with one of these templates is priced under the locales too,
    /// whatever `locale_prefix_exclude` says of its own spelling.
    pub(crate) nested: Vec<String>,
}

impl PricedRoutes {
    /// The priced routes, or `None` when AEO is off or no route is priced.
    fn from_config(
        config: &crate::config::AutumnConfig,
        state: &crate::state::AppState,
    ) -> Option<Self> {
        let aeo = &config.aeo;
        // An invalid x402 route stays matched, so it answers 503 and never
        // runs free. MPP routes are kept so a static file picks the same
        // route its handler would, and x402 steps aside when that is MPP's.
        let routes = aeo.paid_routes.clone();
        if !aeo.enabled || !routes.iter().any(PaidRoute::is_x402) {
            return None;
        }
        #[cfg(feature = "i18n")]
        let locales = if config.i18n.locale_prefix_enabled {
            crate::router::validated_locale_prefix_locales(&config.i18n)
        } else {
            Vec::new()
        };
        #[cfg(feature = "i18n")]
        let unprefixed = routes
            .iter()
            // As the router decides it: an exact exclusion is slash-exact.
            .filter(|r| {
                config.i18n.locale_prefix_exclude_exact.contains(&r.path)
                    || crate::router::matches_locale_exclude_prefix(
                        &r.path,
                        &config.i18n.locale_prefix_exclude,
                    )
            })
            .map(|r| r.path.clone())
            .collect();
        #[cfg(not(feature = "i18n"))]
        let (locales, unprefixed) = (Vec::new(), Vec::new());
        let RoutedTemplates { mounted, nested } = state
            .extension::<RoutedTemplates>()
            .map(|r| (*r).clone())
            .unwrap_or_default();
        Some(Self {
            routes,
            locales,
            unprefixed,
            mounted,
            nested,
        })
    }

    /// The priced route for `req`, if any. Uses the route template axum
    /// matched when it is known. An entry for the request's own method wins
    /// over a `GET` entry that also prices `HEAD`. `None` when the route is
    /// MPP's: the app runs that payment.
    fn route_for(&self, req: &axum::http::Request<axum::body::Body>) -> Option<&PaidRoute> {
        let method = req.method().as_str();
        self.lookup(req, |r| r.method.eq_ignore_ascii_case(method))
            .or_else(|| self.lookup(req, |r| r.method_matches(method)))
            .filter(|r| r.is_x402())
    }

    fn lookup(
        &self,
        req: &axum::http::Request<axum::body::Body>,
        accepts: impl Fn(&PaidRoute) -> bool,
    ) -> Option<&PaidRoute> {
        let template = req
            .extensions()
            .get::<axum::extract::MatchedPath>()
            .map(axum::extract::MatchedPath::as_str)
            .or_else(|| req.extensions().get::<StaticRoute>().map(|r| r.0.as_str()));
        // A route outside the locale nests (a scoped group, an excluded
        // path) can itself start with a locale segment, so a path is matched
        // as it is and with the locale stripped. Both cannot name two
        // different routes: a localized `/x` is mounted at `/{locale}/x`.
        let routes = self.routes.iter().filter(|r| accepts(r));
        if let Some(t) = template {
            // The bare path of a route nested under each locale is the
            // router's 308 to `/{locale}/...`: the operation runs there, so
            // the redirect is never priced (an unsafe request would settle
            // before it, and the proof would be spent on the 308).
            if self.nested.iter().any(|n| same_shape(n, t)) {
                return None;
            }
            // axum picked the route: price exactly that one, so a wildcard
            // listed first never prices a more specific static route. A route
            // the router nested is not at its own path but at
            // `/{locale}{path}`: a priced `/en/report` is mounted at
            // `/en/en/report`, and `/en/report` is the free `/report`.
            // The exact spelling first: a merged router's routes are not in
            // `mounted`, so `another_route` cannot tell `/report` from
            // `/report/` there, but an entry for each still prices each.
            let unnested = |r: &&PaidRoute| !self.nested.iter().any(|n| same_template(n, &r.path));
            return routes
                .clone()
                .find(|r| same_shape(&r.path, t) && unnested(r))
                .or_else(|| {
                    routes.clone().find(|r| {
                        same_template(&r.path, t)
                            && !self.another_route(&r.path, t, t)
                            && unnested(r)
                    })
                })
                .or_else(|| {
                    let bare = self.strip_locale(t);
                    routes.clone().find(|r| {
                        self.localized(r)
                            && same_template(&r.path, bare)
                            && !self.another_route(&r.path, bare, t)
                    })
                });
        }
        // No matched route: only a `GET` or `HEAD` can be a static file. An
        // unsafe request that matched nothing is a 404, and must not be paid
        // for (x402 settles an unsafe request before the handler runs).
        if !matches!(
            *req.method(),
            axum::http::Method::GET | axum::http::Method::HEAD
        ) {
            return None;
        }
        // A static file: the most specific match wins. Of two the same
        // shape, the first listed, as `find` picks for a matched route:
        // `max_by_key` keeps the last of equals, so it reads them reversed.
        let path = req.uri().path();
        routes
            .filter(|r| {
                template_matches(&r.path, path)
                    || (self.localized(r) && template_matches(&r.path, self.strip_locale(path)))
            })
            .rev()
            .max_by_key(|r| specificity(&r.path))
    }

    /// `true` when the priced `path` differs from the matched template only
    /// by a trailing `/` (`compared` is `matched`, maybe without its locale)
    /// and the app mounts a route at the other form too: axum picked
    /// `matched` over that route, so the price is not this route's.
    fn another_route(&self, path: &str, compared: &str, matched: &str) -> bool {
        if path.ends_with('/') == compared.ends_with('/') {
            return false;
        }
        let other = match matched.strip_suffix('/') {
            Some(bare) if !bare.is_empty() => bare.to_owned(),
            _ => format!("{matched}/"),
        };
        self.mounted.iter().any(|r| same_shape(r, &other))
    }

    /// `true` when `route` is mounted in the locale nests too.
    /// An exclusion in config can name the priced path but miss the route
    /// (`/report/` against a route `/report`): what the router nested wins,
    /// so `/en/report` is never served free.
    fn localized(&self, route: &PaidRoute) -> bool {
        !self.unprefixed.contains(&route.path)
            || self.nested.iter().any(|n| same_template(n, &route.path))
    }

    fn strip_locale<'a>(&self, path: &'a str) -> &'a str {
        for locale in &self.locales {
            if let Some(rest) = path
                .strip_prefix('/')
                .and_then(|p| p.strip_prefix(locale.as_str()))
            {
                if rest.is_empty() {
                    return "/";
                }
                if rest.starts_with('/') {
                    return rest;
                }
            }
        }
        path
    }
}

/// The pre-rendered pages of an SSG/ISR build, each with the route template
/// that renders it, for the x402 copy that runs outside the static-first
/// middleware. That copy sees no matched route, so it prices only a request
/// the middleware will answer from the manifest, and prices the route that
/// rendered the page, as the copy inside the router prices the route axum
/// matched. A miss falls through to that inner copy.
pub(crate) type StaticPages = std::collections::HashMap<String, Option<String>>;

/// [`StaticPages`] as the layers hold it: `None` outside a static build.
pub(crate) type StaticPaths = Option<std::sync::Arc<StaticPages>>;

/// `true` when x402 prices `method template`, an MCP tool's route. A task
/// has no HTTP response to carry the x402 challenge or receipt, so `/mcp`
/// runs a priced tool as a blocking call even when the client asked for a
/// task.
#[cfg(feature = "mcp")]
#[must_use]
pub(crate) fn prices_route(state: &crate::state::AppState, method: &str, template: &str) -> bool {
    #[cfg(feature = "http-client")]
    {
        let Some(layer) = state.extension::<SharedX402>().and_then(|s| s.0.clone()) else {
            return false;
        };
        let Ok(method) = axum::http::Method::from_bytes(method.as_bytes()) else {
            return false;
        };
        let Ok(mut req) = axum::http::Request::builder()
            .method(method)
            .uri("/")
            .body(axum::body::Body::empty())
        else {
            return false;
        };
        req.extensions_mut()
            .insert(StaticRoute(template.to_owned()));
        layer.state.priced.route_for(&req).is_some()
    }
    #[cfg(not(feature = "http-client"))]
    {
        // Without a facilitator a priced route answers `503`, which a task
        // result carries as well as a blocking call.
        let _ = (state, method, template);
        false
    }
}

/// The pre-rendered pages x402 prices, split by whether a route renders
/// them. A routed page is left to the router by the static-first
/// middleware, so the ingress limits (load shedding, bot protection, rate
/// limiting, CORS) run before any facilitator call, as for every priced
/// route. A page with no route (a hand-written manifest entry) can only be
/// served from the manifest, so the x402 copy outside that middleware
/// prices it there.
pub(crate) fn priced_static_pages(
    config: &crate::config::AutumnConfig,
    state: &crate::state::AppState,
    pages: &StaticPages,
) -> (std::collections::HashSet<String>, StaticPages) {
    let mut routed = std::collections::HashSet::new();
    let mut unrouted = StaticPages::new();
    let Some(priced) = PricedRoutes::from_config(config, state) else {
        return (routed, unrouted);
    };
    for (page, template) in pages {
        let charged = [axum::http::Method::GET, axum::http::Method::HEAD]
            .into_iter()
            .any(|method| {
                // A page that is no valid URI can never be requested.
                let Ok(mut req) = axum::http::Request::builder()
                    .method(method)
                    .uri(page.as_str())
                    .body(axum::body::Body::empty())
                else {
                    return false;
                };
                if let Some(t) = template {
                    req.extensions_mut().insert(StaticRoute(t.clone()));
                }
                priced.route_for(&req).is_some()
            });
        match template {
            Some(_) if charged => {
                routed.insert(page.clone());
            }
            None if charged => {
                unrouted.insert(page.clone(), None);
            }
            _ => {}
        }
    }
    (routed, unrouted)
}

/// The route template that rendered a pre-rendered page, for a request the
/// router has not matched.
#[derive(Clone)]
struct StaticRoute(String);

/// `true` when `static_paths` is set and `req` is not one of those pages.
/// On a hit, marks `req` with the route that rendered the page.
fn static_miss(
    static_paths: Option<&std::sync::Arc<StaticPages>>,
    req: &mut axum::http::Request<axum::body::Body>,
) -> bool {
    let Some(pages) = static_paths else {
        return false;
    };
    let Some(template) = pages.get(normalize(req.uri().path())) else {
        return true;
    };
    if let Some(t) = template {
        req.extensions_mut().insert(StaticRoute(t.clone()));
    }
    false
}

#[cfg(feature = "http-client")]
impl X402Layer {
    /// This layer for the pages of a static build only (see
    /// [`StaticPaths`]). It shares the used-payment cache.
    #[must_use]
    pub(crate) fn for_static_pages(mut self, paths: std::sync::Arc<StaticPages>) -> Self {
        self.static_paths = Some(paths);
        self
    }
}

#[cfg(not(feature = "http-client"))]
impl X402Unavailable {
    /// This layer for the pages of a static build only (see
    /// [`StaticPaths`]).
    #[must_use]
    pub(crate) fn for_static_pages(mut self, paths: std::sync::Arc<StaticPages>) -> Self {
        self.static_paths = Some(paths);
        self
    }
}

/// Lets a payment client's request to an x402-priced route past CSRF.
///
/// It sits outside the CSRF layer and marks a request to a priced x402
/// route that either carries no `Cookie` (no ambient credential to forge;
/// x402 answers it `402`) or carries a `PAYMENT-SIGNATURE` header (a custom
/// header a cross-site page cannot send without passing CORS). Without the
/// mark, CSRF answers every priced `POST` from a payment client `403` before
/// x402 can challenge or verify it. A browser request with cookies and no
/// payment header still needs its CSRF token.
#[derive(Clone)]
pub(crate) struct X402CsrfLayer {
    priced: std::sync::Arc<PricedRoutes>,
}

impl X402CsrfLayer {
    /// The layer, or `None` when no x402 route is priced.
    #[must_use]
    pub(crate) fn from_config(
        config: &crate::config::AutumnConfig,
        state: &crate::state::AppState,
    ) -> Option<Self> {
        Some(Self {
            priced: std::sync::Arc::new(PricedRoutes::from_config(config, state)?),
        })
    }
}

impl<S> tower::Layer<S> for X402CsrfLayer {
    type Service = X402CsrfService<S>;

    fn layer(&self, inner: S) -> Self::Service {
        X402CsrfService {
            inner,
            priced: std::sync::Arc::clone(&self.priced),
        }
    }
}

/// Service of [`X402CsrfLayer`].
#[derive(Clone)]
pub(crate) struct X402CsrfService<S> {
    inner: S,
    priced: std::sync::Arc<PricedRoutes>,
}

impl<S> tower::Service<axum::http::Request<axum::body::Body>> for X402CsrfService<S>
where
    S: tower::Service<axum::http::Request<axum::body::Body>>,
{
    type Response = S::Response;
    type Error = S::Error;
    type Future = S::Future;

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

    fn call(&mut self, mut req: axum::http::Request<axum::body::Body>) -> Self::Future {
        let headers = req.headers();
        let not_forgeable = !headers.contains_key(axum::http::header::COOKIE)
            || headers.contains_key("payment-signature");
        if not_forgeable && self.priced.route_for(&req).is_some() {
            req.extensions_mut()
                .insert(crate::security::csrf::CsrfNotApplicable);
        }
        self.inner.call(req)
    }
}

#[cfg(feature = "http-client")]
impl X402Layer {
    /// The layer for `[aeo.x402]` and `[[aeo.paid_routes]]`, or `None` when
    /// no route is priced. With incomplete or unsafe x402 settings, priced
    /// routes answer `503`.
    #[must_use]
    pub(crate) fn from_config(
        config: &crate::config::AutumnConfig,
        state: &crate::state::AppState,
    ) -> Option<Self> {
        let aeo = &config.aeo;
        let priced = PricedRoutes::from_config(config, state)?;
        let complete = aeo.x402.is_complete();
        let safe = facilitator_url_is_safe(aeo.x402.facilitator_url.as_deref().unwrap_or_default());
        if !complete {
            tracing::error!(
                "aeo: [[aeo.paid_routes]] has x402 routes but [aeo.x402] needs \
                 facilitator_url, pay_to, network, and asset; those routes answer 503"
            );
        } else if !safe {
            tracing::error!(
                "aeo: [aeo.x402] facilitator_url must be https (http only for localhost), \
                 with no query or fragment; priced routes answer 503"
            );
        }
        Some(Self {
            static_paths: None,
            state: std::sync::Arc::new(X402State {
                config: aeo.x402.clone(),
                priced,
                available: complete && safe,
                client: crate::http_client::Client::from_state(state).named("x402"),
                base_url: config.seo.base_url.clone(),
                used: std::sync::Mutex::new(UsedPayments::new(10_000)),
            }),
        })
    }
}

#[cfg(feature = "http-client")]
impl X402Layer {
    /// [`X402Layer::from_config`], built once per app state. Every copy of
    /// the layer then shares one used-payment cache.
    #[must_use]
    pub(crate) fn shared(
        config: &crate::config::AutumnConfig,
        state: &crate::state::AppState,
    ) -> Option<Self> {
        if let Some(shared) = state.extension::<SharedX402>() {
            return shared.0.clone();
        }
        let layer = Self::from_config(config, state);
        state.insert_extension(SharedX402(layer.clone()));
        layer
    }
}

/// Without the `http-client` feature Autumn cannot reach a facilitator, so
/// a priced route fails closed: it answers `503` and is never served free.
#[cfg(not(feature = "http-client"))]
#[derive(Clone)]
pub(crate) struct X402Unavailable {
    priced: std::sync::Arc<PricedRoutes>,
    static_paths: StaticPaths,
}

#[cfg(not(feature = "http-client"))]
impl X402Unavailable {
    /// The layer, or `None` when no route is priced.
    #[must_use]
    pub(crate) fn from_config(
        config: &crate::config::AutumnConfig,
        state: &crate::state::AppState,
    ) -> Option<Self> {
        let priced = PricedRoutes::from_config(config, state)?;
        tracing::error!(
            "aeo: [[aeo.paid_routes]] has x402 routes, but x402 needs the `http-client` \
             feature; those routes answer 503"
        );
        Some(Self {
            priced: std::sync::Arc::new(priced),
            static_paths: None,
        })
    }
}

#[cfg(not(feature = "http-client"))]
impl<S> tower::Layer<S> for X402Unavailable {
    type Service = X402UnavailableService<S>;

    fn layer(&self, inner: S) -> Self::Service {
        X402UnavailableService {
            inner,
            priced: std::sync::Arc::clone(&self.priced),
            static_paths: self.static_paths.clone(),
        }
    }
}

/// Service made by [`X402Unavailable`].
#[cfg(not(feature = "http-client"))]
#[derive(Clone)]
pub(crate) struct X402UnavailableService<S> {
    inner: S,
    priced: std::sync::Arc<PricedRoutes>,
    static_paths: StaticPaths,
}

#[cfg(not(feature = "http-client"))]
impl<S> tower::Service<axum::http::Request<axum::body::Body>> for X402UnavailableService<S>
where
    S: tower::Service<axum::http::Request<axum::body::Body>, Response = axum::response::Response>,
{
    type Response = axum::response::Response;
    type Error = S::Error;
    type Future = futures::future::Either<
        std::future::Ready<Result<axum::response::Response, S::Error>>,
        S::Future,
    >;

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

    fn call(&mut self, mut req: axum::http::Request<axum::body::Body>) -> Self::Future {
        use axum::response::IntoResponse as _;

        if !is_internal_render(&req)
            && !static_miss(self.static_paths.as_ref(), &mut req)
            && self.priced.route_for(&req).is_some()
        {
            let res = (
                axum::http::StatusCode::SERVICE_UNAVAILABLE,
                "payments are not available",
            )
                .into_response();
            return futures::future::Either::Left(std::future::ready(Ok(res)));
        }
        futures::future::Either::Right(self.inner.call(req))
    }
}

/// `true` for a build or ISR render: Autumn makes it, no client does.
fn is_internal_render(req: &axum::http::Request<axum::body::Body>) -> bool {
    req.extensions()
        .get::<crate::static_gen::RenderDeadlineExempt>()
        .is_some()
}

/// The app's one [`X402Layer`] (an `AppState` extension).
#[cfg(feature = "http-client")]
struct SharedX402(Option<X402Layer>);

#[cfg(feature = "http-client")]
impl<S> tower::Layer<S> for X402Layer {
    type Service = X402Service<S>;

    fn layer(&self, inner: S) -> Self::Service {
        X402Service {
            inner,
            state: std::sync::Arc::clone(&self.state),
            static_paths: self.static_paths.clone(),
        }
    }
}

/// Service made by [`X402Layer`].
#[cfg(feature = "http-client")]
#[derive(Clone)]
pub(crate) struct X402Service<S> {
    inner: S,
    state: std::sync::Arc<X402State>,
    static_paths: StaticPaths,
}

#[cfg(feature = "http-client")]
impl<S> tower::Service<axum::http::Request<axum::body::Body>> for X402Service<S>
where
    S: tower::Service<axum::http::Request<axum::body::Body>, Response = axum::response::Response>
        + Clone
        + Send
        + 'static,
    S::Future: Send + 'static,
    S::Error: Send + 'static,
{
    type Response = axum::response::Response;
    type Error = S::Error;
    type Future = futures::future::Either<
        S::Future,
        std::pin::Pin<
            Box<
                dyn std::future::Future<Output = Result<axum::response::Response, S::Error>> + Send,
            >,
        >,
    >;

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

    #[allow(clippy::too_many_lines)]
    fn call(&mut self, mut req: axum::http::Request<axum::body::Body>) -> Self::Future {
        // An unpriced request costs no clone and no box. A build or ISR
        // render is internal: the outer copy of this layer charges the live
        // request that reads the page.
        let route = if req.extensions().get::<X402Handled>().is_some()
            || is_internal_render(&req)
            || static_miss(self.static_paths.as_ref(), &mut req)
        {
            None
        } else {
            self.state.priced.route_for(&req).cloned()
        };
        let Some(route) = route else {
            return futures::future::Either::Left(self.inner.call(req));
        };
        req.extensions_mut().insert(X402Handled);
        let clone = self.inner.clone();
        let mut inner = std::mem::replace(&mut self.inner, clone);
        let state = std::sync::Arc::clone(&self.state);
        futures::future::Either::Right(Box::pin(async move {
            if !state.available || !route_is_valid(&route) {
                return Ok(plain(
                    axum::http::StatusCode::SERVICE_UNAVAILABLE,
                    "payments are not available",
                ));
            }
            let resource = resource_url(&state, &req);
            let offered = state.config.requirements(&route);
            let Some(header) = req
                .headers()
                .get("payment-signature")
                .and_then(|v| v.to_str().ok())
            else {
                return Ok(payment_required(
                    &state,
                    &route,
                    &resource,
                    "Payment required",
                ));
            };
            let Some(payload) = decode_header(header) else {
                return Ok(plain(
                    axum::http::StatusCode::BAD_REQUEST,
                    "malformed PAYMENT-SIGNATURE",
                ));
            };
            if !payload
                .get("accepted")
                .is_some_and(|a| accepted_matches(a, &offered))
            {
                return Ok(payment_required(
                    &state,
                    &route,
                    &resource,
                    "payment does not match the requirements",
                ));
            }
            let body = json!({
                "x402Version": 2,
                "paymentPayload": payload,
                "paymentRequirements": offered,
            });
            // One payment works once, however its header is written. Claim it
            // before any call, until the payment itself expires.
            let key = payment_key(&payload);
            let now = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map_or(0, |d| d.as_secs());
            let expires =
                payment_expiry(&payload, state.config.max_timeout_secs.unwrap_or(300), now);
            let claim = state
                .used
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner)
                .claim(key, expires, now);
            let mut claim = match claim {
                Ok(()) => PaymentClaim::new(std::sync::Arc::clone(&state), key),
                Err(ClaimError::Used) => {
                    return Ok(payment_required(
                        &state,
                        &route,
                        &resource,
                        "payment already used",
                    ));
                }
                Err(ClaimError::Full) => {
                    tracing::error!(
                        "aeo: x402 used-payment record is full of unexpired payments; \
                         refusing new payments until some expire"
                    );
                    return Ok(plain(
                        axum::http::StatusCode::SERVICE_UNAVAILABLE,
                        "payment capacity reached",
                    ));
                }
            };
            // From here, every return before settlement drops `claim`, which
            // frees the payment: not verified, rejected (so junk headers
            // cannot fill the record), never settled, or the request was
            // cancelled (a timeout, a client gone) while it ran.
            let verify = match facilitator(&state, "verify", &body).await {
                Ok(v) => v,
                Err(status) => return Ok(plain(status, "payment facilitator unavailable")),
            };
            if verify.get("isValid").and_then(Value::as_bool) != Some(true) {
                let reason = verify
                    .get("invalidReason")
                    .and_then(Value::as_str)
                    .unwrap_or("invalid payment")
                    .to_owned();
                return Ok(payment_required(&state, &route, &resource, &reason));
            }

            // A safe method settles after a successful answer. Any other
            // method settles first, so its side effects are always paid.
            let safe = matches!(
                *req.method(),
                axum::http::Method::GET | axum::http::Method::HEAD
            );
            let early = if safe {
                None
            } else {
                // A settlement cut short may have gone through: keep it.
                claim.disarm();
                match settle(&state, &route, &resource, &body).await {
                    Ok(receipt) => Some(receipt),
                    Err((failed, rejected)) => {
                        if rejected {
                            release_payment(&state, &key);
                        }
                        return Ok(*failed);
                    }
                }
            };
            let mut res = inner.call(req).await?;
            let receipt = match early {
                Some(receipt) => receipt,
                None if res.status().is_success() => {
                    claim.disarm();
                    match settle(&state, &route, &resource, &body).await {
                        Ok(receipt) => receipt,
                        Err((failed, rejected)) => {
                            if rejected {
                                release_payment(&state, &key);
                            }
                            return Ok(*failed);
                        }
                    }
                }
                // Never settled, so not spent: `claim` frees it.
                None => return Ok(res),
            };
            let headers = res.headers_mut();
            if let Some(h) = receipt {
                headers.insert("payment-response", h);
            }
            headers.insert(
                axum::http::header::CACHE_CONTROL,
                axum::http::HeaderValue::from_static("private, no-store"),
            );
            expose_payment_headers(headers);
            Ok(res)
        }))
    }
}

/// A claimed payment, freed when dropped unless [`Self::disarm`] ran first:
/// a request cancelled before settlement spent nothing, so the client may
/// retry the same proof.
#[cfg(feature = "http-client")]
struct PaymentClaim {
    state: std::sync::Arc<X402State>,
    key: [u8; 32],
    armed: bool,
}

#[cfg(feature = "http-client")]
impl PaymentClaim {
    const fn new(state: std::sync::Arc<X402State>, key: [u8; 32]) -> Self {
        Self {
            state,
            key,
            armed: true,
        }
    }

    /// Keep the claim: settlement starts, and may go through.
    const fn disarm(&mut self) {
        self.armed = false;
    }
}

#[cfg(feature = "http-client")]
impl Drop for PaymentClaim {
    fn drop(&mut self) {
        if self.armed {
            release_payment(&self.state, &self.key);
        }
    }
}

/// Free a claimed payment: it was never spent, so the client may retry it.
#[cfg(feature = "http-client")]
fn release_payment(state: &X402State, key: &[u8; 32]) {
    state
        .used
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
        .release(key);
}

/// Settle a verified payment. `Ok` carries the `PAYMENT-RESPONSE` value;
/// `Err` is the response to send instead (boxed: the error path is rare),
/// and whether the facilitator rejected the payment outright. A rejected
/// payment was not spent; one the facilitator did not answer for may have
/// been.
#[cfg(feature = "http-client")]
async fn settle(
    state: &X402State,
    route: &PaidRoute,
    resource: &str,
    body: &Value,
) -> Result<Option<axum::http::HeaderValue>, (Box<axum::response::Response>, bool)> {
    let settled = facilitator(state, "settle", body).await.map_err(|status| {
        (
            Box::new(plain(status, "payment facilitator unavailable")),
            false,
        )
    })?;
    let header = axum::http::HeaderValue::from_str(&encode_header(&settled)).ok();
    if settled.get("success").and_then(Value::as_bool) == Some(true) {
        return Ok(header);
    }
    let mut failed = payment_required(state, route, resource, "settlement failed");
    if let Some(h) = header {
        failed.headers_mut().insert("payment-response", h);
    }
    Err((Box::new(failed), true))
}

/// `true` for an `https` facilitator, or `http` on a loopback host, with no
/// query or fragment: `/verify` and `/settle` are appended to it.
#[cfg(feature = "http-client")]
fn facilitator_url_is_safe(raw: &str) -> bool {
    url::Url::parse(raw).is_ok_and(|u| {
        u.query().is_none()
            && u.fragment().is_none()
            && match u.scheme() {
                "https" => true,
                "http" => matches!(u.host_str(), Some("localhost" | "127.0.0.1" | "[::1]")),
                _ => false,
            }
    })
}

#[cfg(feature = "http-client")]
fn resource_url(state: &X402State, req: &axum::http::Request<axum::body::Body>) -> String {
    let (origin, _) = super::documents::Origin::for_request(state.base_url.as_deref(), req);
    let path = req
        .uri()
        .path_and_query()
        .map_or("/", axum::http::uri::PathAndQuery::as_str);
    format!("{}{path}", origin.base)
}

#[cfg(feature = "http-client")]
fn payment_required(
    state: &X402State,
    route: &PaidRoute,
    resource: &str,
    error: &str,
) -> axum::response::Response {
    use axum::response::IntoResponse as _;
    let required = state.config.payment_required(route, resource, error);
    let mut res = (
        axum::http::StatusCode::PAYMENT_REQUIRED,
        axum::Json(required.clone()),
    )
        .into_response();
    let headers = res.headers_mut();
    if let Ok(v) = axum::http::HeaderValue::from_str(&encode_header(&required)) {
        headers.insert("payment-required", v);
    }
    headers.insert(
        axum::http::header::CACHE_CONTROL,
        axum::http::HeaderValue::from_static("no-store"),
    );
    expose_payment_headers(headers);
    res
}

/// Let a cross-origin browser client read the x402 challenge and receipt:
/// CORS hides any response header it does not expose. Added to what the
/// response already exposes. Without an allowed origin a browser reads none
/// of the response, so this grants nothing on its own. A `*` already there
/// does not count: for a credentialed request it names no header (Fetch
/// §3.3.4).
#[cfg_attr(not(any(feature = "http-client", feature = "mcp")), allow(dead_code))]
pub(crate) fn expose_payment_headers(headers: &mut axum::http::HeaderMap) {
    const EXPOSE: &str = "PAYMENT-REQUIRED, PAYMENT-RESPONSE";
    let name = axum::http::header::ACCESS_CONTROL_EXPOSE_HEADERS;
    let covered = headers.get_all(&name).iter().any(|v| {
        v.to_str().is_ok_and(|v| {
            v.split(',')
                .any(|h| h.trim().eq_ignore_ascii_case("payment-response"))
        })
    });
    if !covered {
        headers.append(name, axum::http::HeaderValue::from_static(EXPOSE));
    }
}

#[cfg(feature = "http-client")]
fn plain(status: axum::http::StatusCode, msg: &'static str) -> axum::response::Response {
    use axum::response::IntoResponse as _;
    (status, msg).into_response()
}

/// POST `body` to `<facilitator>/<op>`. A transport error or a non-JSON
/// answer is a `502`.
#[cfg(feature = "http-client")]
async fn facilitator(
    state: &X402State,
    op: &str,
    body: &Value,
) -> Result<Value, axum::http::StatusCode> {
    let base = state
        .config
        .facilitator_url
        .as_deref()
        .unwrap_or_default()
        .trim_end_matches('/');
    let res = state
        .client
        .post(format!("{base}/{op}"))
        .json(body)
        .send()
        .await
        .map_err(|err| {
            tracing::warn!(error = %err, op, "aeo: x402 facilitator call failed");
            axum::http::StatusCode::BAD_GATEWAY
        })?;
    // An error answer is an unavailable facilitator, whatever its body says.
    if !res.is_success() {
        tracing::warn!(
            status = res.status().as_u16(),
            op,
            "aeo: x402 facilitator answered an error"
        );
        return Err(axum::http::StatusCode::BAD_GATEWAY);
    }
    res.json::<Value>().map_err(|err| {
        tracing::warn!(error = %err, op, "aeo: x402 facilitator sent no JSON");
        axum::http::StatusCode::BAD_GATEWAY
    })
}

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

    /// Codex review (P2): a `*` the handler exposes names no header for a
    /// credentialed request, so the payment headers are named too.
    #[test]
    fn payment_headers_are_named_past_a_wildcard() {
        let mut headers = axum::http::HeaderMap::new();
        headers.insert(
            axum::http::header::ACCESS_CONTROL_EXPOSE_HEADERS,
            axum::http::HeaderValue::from_static("*"),
        );
        expose_payment_headers(&mut headers);
        let exposed: Vec<&str> = headers
            .get_all(axum::http::header::ACCESS_CONTROL_EXPOSE_HEADERS)
            .iter()
            .filter_map(|v| v.to_str().ok())
            .collect();
        assert_eq!(exposed, ["*", "PAYMENT-REQUIRED, PAYMENT-RESPONSE"]);
        // Named already: not repeated.
        expose_payment_headers(&mut headers);
        assert_eq!(
            headers
                .get_all(axum::http::header::ACCESS_CONTROL_EXPOSE_HEADERS)
                .iter()
                .count(),
            2
        );
    }

    fn x402() -> X402Config {
        X402Config {
            facilitator_url: Some("https://facilitator.example".to_owned()),
            pay_to: Some("0xabc".to_owned()),
            network: Some("eip155:84532".to_owned()),
            asset: Some("0xusdc".to_owned()),
            ..X402Config::default()
        }
    }

    fn route() -> PaidRoute {
        PaidRoute {
            method: "GET".to_owned(),
            path: "/api/reports/{id}".to_owned(),
            amount: "10000".to_owned(),
            description: Some("A report".to_owned()),
            mpp_method: Some("stripe".to_owned()),
            mpp_currency: Some("usd".to_owned()),
            ..PaidRoute::default()
        }
    }

    #[cfg(not(feature = "http-client"))]
    #[tokio::test]
    async fn without_the_http_client_priced_routes_fail_closed() {
        use tower::{Layer as _, ServiceExt as _};

        let mut config = crate::config::AutumnConfig::default();
        config.aeo.x402 = x402();
        config.aeo.paid_routes.push(route());
        let layer = X402Unavailable::from_config(&config, &crate::state::AppState::for_test())
            .expect("a route is priced");
        let inner = tower::service_fn(|_req: axum::http::Request<axum::body::Body>| async {
            Ok::<_, std::convert::Infallible>(axum::response::Response::new(
                axum::body::Body::empty(),
            ))
        });
        let call = |path: &str| {
            let req = axum::http::Request::get(path)
                .body(axum::body::Body::empty())
                .unwrap();
            layer.layer(inner).oneshot(req)
        };
        assert_eq!(call("/api/reports/7").await.unwrap().status(), 503);
        assert_eq!(call("/free").await.unwrap().status(), 200);
    }

    #[test]
    fn a_route_outside_the_locale_nests_keeps_its_locale_segment() {
        let priced = PricedRoutes {
            routes: vec![
                PaidRoute::new("GET", "/en/admin", "1"),
                PaidRoute::new("GET", "/api", "2"),
            ],
            locales: vec!["en".to_owned()],
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: Vec::new(),
        };
        let get = |path: &str| {
            axum::http::Request::get(path)
                .body(axum::body::Body::empty())
                .unwrap()
        };
        let amount = |path: &str| priced.route_for(&get(path)).map(|r| r.amount.clone());
        assert_eq!(amount("/en/admin").as_deref(), Some("1"), "unlocalized");
        assert_eq!(amount("/en/api").as_deref(), Some("2"), "localized");
        assert_eq!(amount("/api").as_deref(), Some("2"));
        assert_eq!(amount("/admin"), None);
    }

    #[test]
    fn a_trailing_slash_route_of_its_own_keeps_its_price() {
        // Codex review (P1): axum routes `/report` and `/report/` apart.
        let priced = |paths: &[&str], mounted: &[&str]| PricedRoutes {
            routes: paths
                .iter()
                .map(|&p| PaidRoute::new("GET", p, "1"))
                .collect(),
            locales: vec!["en".to_owned()],
            unprefixed: Vec::new(),
            mounted: mounted.iter().map(|&r| r.to_owned()).collect(),
            nested: Vec::new(),
        };
        let matched = |template: &str| {
            let mut req = axum::http::Request::get(template)
                .body(axum::body::Body::empty())
                .unwrap();
            req.extensions_mut()
                .insert(StaticRoute(template.to_owned()));
            req
        };
        let charged = |p: &PricedRoutes, template: &str| p.route_for(&matched(template)).is_some();

        // The app routes both forms: each is its own route.
        let both = priced(&["/report"], &["/report", "/report/"]);
        assert!(charged(&both, "/report"));
        assert!(!charged(&both, "/report/"), "a free /report/ stays free");
        let both = priced(&["/report/"], &["/report", "/report/"]);
        assert!(!charged(&both, "/report"));
        assert!(charged(&both, "/report/"));
        // Under a locale nest, against the nested templates.
        let nested = priced(&["/report"], &["/en/report", "/en/report/"]);
        assert!(charged(&nested, "/en/report"));
        assert!(!charged(&nested, "/en/report/"));

        // One form only: the config's slash does not matter.
        assert!(charged(&priced(&["/report/"], &["/report"]), "/report"));
        assert!(charged(&priced(&["/report"], &["/report/"]), "/report/"));
        // Nothing recorded (a router built without the extension): as before.
        assert!(charged(&priced(&["/report"], &[]), "/report/"));
    }

    #[test]
    fn a_route_the_router_nested_is_priced_under_a_locale() {
        // Codex review (P1): `locale_prefix_exclude_exact = ["/report/"]`
        // names the priced path but not the route `/report`, which the
        // router (slash-exact) still nests at `/en/report`.
        let matched = |template: &str| {
            let mut req = axum::http::Request::get(template)
                .body(axum::body::Body::empty())
                .unwrap();
            req.extensions_mut()
                .insert(StaticRoute(template.to_owned()));
            req
        };
        let priced = |nested: &[&str]| PricedRoutes {
            routes: vec![PaidRoute::new("GET", "/report/", "1")],
            locales: vec!["en".to_owned()],
            unprefixed: vec!["/report/".to_owned()],
            mounted: Vec::new(),
            nested: nested.iter().map(|&n| n.to_owned()).collect(),
        };
        assert!(
            priced(&["/report"])
                .route_for(&matched("/en/report"))
                .is_some()
        );
        // Not nested: `/en/report` can only be a route of its own.
        assert!(priced(&[]).route_for(&matched("/en/report")).is_none());
    }

    #[test]
    fn a_locale_redirect_is_never_priced() {
        // Codex review (P1): the router answers a nested route's bare path
        // with a 308 to `/{locale}/...`; only the nested route is charged.
        let priced = PricedRoutes {
            routes: vec![PaidRoute::new("POST", "/submit", "1")],
            locales: vec!["en".to_owned()],
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: vec!["/submit".to_owned()],
        };
        let matched = |template: &str| {
            let mut req = axum::http::Request::post(template)
                .body(axum::body::Body::empty())
                .unwrap();
            req.extensions_mut()
                .insert(StaticRoute(template.to_owned()));
            req
        };
        assert!(priced.route_for(&matched("/submit")).is_none());
        assert!(priced.route_for(&matched("/en/submit")).is_some());
    }

    #[test]
    fn a_nested_route_is_priced_at_its_mounted_path() {
        // Codex review (P1): a free `/report` is mounted at `/en/report`, a
        // priced top-level `/en/report` at `/en/en/report`.
        let priced = PricedRoutes {
            routes: vec![PaidRoute::new("GET", "/en/report", "1")],
            locales: vec!["en".to_owned()],
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: vec!["/report".to_owned(), "/en/report".to_owned()],
        };
        let matched = |template: &str| {
            let mut req = axum::http::Request::get(template)
                .body(axum::body::Body::empty())
                .unwrap();
            req.extensions_mut()
                .insert(StaticRoute(template.to_owned()));
            req
        };
        assert!(priced.route_for(&matched("/en/report")).is_none());
        assert!(priced.route_for(&matched("/en/en/report")).is_some());
    }

    #[test]
    fn an_exact_entry_wins_without_a_route_inventory() {
        // Codex review: a merged router's `/report` and `/report/` are not in
        // `mounted`; an entry for each still prices its own route.
        let priced = PricedRoutes {
            routes: vec![
                PaidRoute::new("GET", "/report", "1"),
                PaidRoute::new("GET", "/report/", "2"),
            ],
            locales: Vec::new(),
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: Vec::new(),
        };
        let amount = |template: &str| {
            let mut req = axum::http::Request::get(template)
                .body(axum::body::Body::empty())
                .unwrap();
            req.extensions_mut()
                .insert(StaticRoute(template.to_owned()));
            priced.route_for(&req).map(|r| r.amount.clone())
        };
        assert_eq!(amount("/report").as_deref(), Some("1"));
        assert_eq!(amount("/report/").as_deref(), Some("2"));
    }

    #[test]
    fn an_excluded_route_is_not_priced_under_a_locale() {
        let priced = PricedRoutes {
            routes: vec![PaidRoute::new("GET", "/api", "1")],
            locales: vec!["en".to_owned()],
            unprefixed: vec!["/api".to_owned()],
            mounted: Vec::new(),
            nested: Vec::new(),
        };
        let get = |path: &str| {
            axum::http::Request::get(path)
                .body(axum::body::Body::empty())
                .unwrap()
        };
        let amount = |path: &str| priced.route_for(&get(path)).map(|r| r.amount.clone());
        assert_eq!(amount("/api").as_deref(), Some("1"));
        // `/en/api` is not the excluded `/api`: it can only be another route.
        assert_eq!(amount("/en/api"), None);
    }

    #[test]
    fn the_route_axum_matched_sets_the_price() {
        let priced = PricedRoutes {
            routes: vec![
                PaidRoute::new("GET", "/reports/{id}", "1"),
                PaidRoute::new("GET", "/reports/admin", "100"),
            ],
            locales: Vec::new(),
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: Vec::new(),
        };
        let req = |path: &str| {
            axum::http::Request::get(path)
                .body(axum::body::Body::empty())
                .unwrap()
        };
        // Structural template comparison: names do not matter, kinds do.
        // (A matched route is covered by the integration test.)
        assert!(same_template("/reports/{id}", "/reports/{rid}"));
        // A trailing `/` counts only for the exact shape.
        assert!(same_template("/report/", "/report"));
        assert!(!same_shape("/report/", "/report"));
        assert!(same_shape("/report/", "/report/"));
        assert!(!same_template("/reports/{id}", "/reports/admin"));
        assert!(!same_template("/files/{*p}", "/files/{p}"));
        // Without a matched route, the most specific match wins.
        let amount = |path: &str| priced.route_for(&req(path)).map(|r| r.amount.clone());
        assert_eq!(amount("/reports/admin").as_deref(), Some("100"));
        assert_eq!(amount("/reports/7").as_deref(), Some("1"));
    }

    #[test]
    fn one_route_cannot_take_both_payment_protocols() {
        let mut x402 = route();
        x402.mpp_method = None;
        let mut mpp = route();
        mpp.path = "/api/reports/{rid}/".to_owned();
        let problem = mixed_protocol_route(&[x402.clone(), mpp.clone()]).unwrap();
        assert!(problem.contains("both x402 and MPP"), "{problem}");
        let config = super::super::AeoConfig {
            paid_routes: vec![x402.clone(), mpp],
            ..Default::default()
        };
        assert!(config.validate().is_err());

        let mut head = route();
        head.method = "HEAD".to_owned();
        assert!(
            mixed_protocol_route(&[x402.clone(), head]).is_some(),
            "an x402 GET prices HEAD too"
        );
        let mut other = route();
        other.method = "POST".to_owned();
        assert!(
            mixed_protocol_route(&[x402, other]).is_none(),
            "another method"
        );
    }

    #[test]
    fn an_unmatched_unsafe_request_is_never_priced() {
        let priced = PricedRoutes {
            routes: vec![
                PaidRoute::new("POST", "/api", "1"),
                PaidRoute::new("GET", "/files/{name}", "2"),
            ],
            locales: Vec::new(),
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: Vec::new(),
        };
        let req = |method: &str, path: &str| {
            axum::http::Request::builder()
                .method(method)
                .uri(path)
                .body(axum::body::Body::empty())
                .unwrap()
        };
        // No `MatchedPath`: the router found no route, so a POST is a 404.
        assert!(priced.route_for(&req("POST", "/api")).is_none());
        assert!(priced.route_for(&req("POST", "/api/")).is_none());
        // A GET without a matched route is a static file, and is priced.
        assert_eq!(
            priced
                .route_for(&req("GET", "/files/a.pdf"))
                .map(|r| r.amount.as_str()),
            Some("2")
        );
    }

    #[test]
    fn a_static_file_priced_for_mpp_is_not_charged_by_x402() {
        let mut mpp = PaidRoute::new("GET", "/downloads/report.pdf", "5");
        mpp.mpp_method = Some("tempo".to_owned());
        let priced = PricedRoutes {
            routes: vec![PaidRoute::new("GET", "/downloads/{*path}", "1"), mpp],
            locales: Vec::new(),
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: Vec::new(),
        };
        let amount = |method: &str, path: &str| {
            let req = axum::http::Request::builder()
                .method(method)
                .uri(path)
                .body(axum::body::Body::empty())
                .unwrap();
            priced.route_for(&req).map(|r| r.amount.clone())
        };
        // The MPP route is the more specific one, as it is for the handler.
        assert_eq!(amount("GET", "/downloads/report.pdf"), None);
        assert_eq!(amount("HEAD", "/downloads/report.pdf"), None);
        assert_eq!(amount("GET", "/downloads/other.pdf").as_deref(), Some("1"));
    }

    #[test]
    fn a_static_file_takes_the_route_axum_would() {
        let mut mpp = PaidRoute::new("GET", "/downloads/{file}", "5");
        mpp.mpp_method = Some("tempo".to_owned());
        // Listed either way round, the capture beats the catch-all.
        for routes in [
            vec![
                mpp.clone(),
                PaidRoute::new("GET", "/downloads/{*path}", "1"),
            ],
            vec![PaidRoute::new("GET", "/downloads/{*path}", "1"), mpp],
        ] {
            let priced = PricedRoutes {
                routes,
                locales: Vec::new(),
                unprefixed: Vec::new(),
                mounted: Vec::new(),
                nested: Vec::new(),
            };
            let amount = |path: &str| {
                let req = axum::http::Request::get(path)
                    .body(axum::body::Body::empty())
                    .unwrap();
                priced.route_for(&req).map(|r| r.amount.clone())
            };
            assert_eq!(amount("/downloads/report.pdf"), None, "MPP's");
            assert_eq!(amount("/downloads/a/b.pdf").as_deref(), Some("1"));
        }
        // Two of the same shape: the first listed wins, as for a matched
        // route.
        let priced = PricedRoutes {
            routes: vec![
                PaidRoute::new("GET", "/downloads/{file}", "1"),
                PaidRoute::new("GET", "/downloads/{name}", "2"),
            ],
            locales: Vec::new(),
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: Vec::new(),
        };
        let req = axum::http::Request::get("/downloads/a.pdf")
            .body(axum::body::Body::empty())
            .unwrap();
        assert_eq!(priced.route_for(&req).map(|r| r.amount.as_str()), Some("1"));
        // An earlier literal outranks a later one.
        assert!(specificity("/a/b/{*p}") > specificity("/a/{x}/c"));
    }

    #[test]
    fn an_explicit_head_price_beats_the_get_fallback() {
        let priced = PricedRoutes {
            routes: vec![
                PaidRoute::new("GET", "/report", "1"),
                PaidRoute::new("HEAD", "/report", "5"),
            ],
            locales: Vec::new(),
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: Vec::new(),
        };
        let amount = |method: &str| {
            let req = axum::http::Request::builder()
                .method(method)
                .uri("/report")
                .body(axum::body::Body::empty())
                .unwrap();
            priced.route_for(&req).map(|r| r.amount.clone())
        };
        assert_eq!(amount("HEAD").as_deref(), Some("5"));
        assert_eq!(amount("GET").as_deref(), Some("1"));
        let get_only = PricedRoutes {
            routes: vec![PaidRoute::new("GET", "/report", "1")],
            locales: Vec::new(),
            unprefixed: Vec::new(),
            mounted: Vec::new(),
            nested: Vec::new(),
        };
        let head = axum::http::Request::head("/report")
            .body(axum::body::Body::empty())
            .unwrap();
        assert_eq!(
            get_only.route_for(&head).map(|r| r.amount.as_str()),
            Some("1")
        );
    }

    #[test]
    fn route_matching_normalizes_head_slash_and_wildcards() {
        let r = route();
        assert!(r.matches("HEAD", "/api/reports/7"));
        assert!(r.matches("GET", "/api/reports/7/"));
        let files = PaidRoute::new("GET", "/files/{*path}", "1");
        assert!(files.matches("GET", "/files/a/b"));
        assert!(!files.matches("GET", "/files/"));
        assert!(!PaidRoute::new("POST", "/x", "1").matches("HEAD", "/x"));
    }

    #[test]
    fn paid_route_problems_flag_bad_amounts_and_methods() {
        assert!(valid_amount("10000") && valid_amount("0"));
        assert!(!valid_amount("010") && !valid_amount("1.5") && !valid_amount(""));
        let mut r = PaidRoute::new("GET", "/x", "01");
        r.mpp_method = Some("Stripe".to_owned());
        assert_eq!(paid_route_problems(&[r]).len(), 2);
    }

    #[test]
    fn a_route_that_can_never_match_is_a_problem() {
        assert!(unmatchable_route(&PaidRoute::new("get", "/x", "1")).is_none());
        for r in [
            PaidRoute::new("", "/x", "1"),
            PaidRoute::new("FETCH", "/x", "1"),
            PaidRoute::new(" GET ", "/x", "1"),
            PaidRoute::new("GET", "/x ", "1"),
            PaidRoute::new("GET", "/api?plan=pro", "1"),
            PaidRoute::new("GET", "/api#top", "1"),
            PaidRoute::new("GET", "/api/{id", "1"),
            PaidRoute::new("GET", "/api/{}", "1"),
            PaidRoute::new("GET", "/files/{*rest}/x", "1"),
            PaidRoute::new("GET", "/img/{name}.png", "1"),
            PaidRoute::new("GET", "api", "1"),
            PaidRoute::new("GET", "", "1"),
        ] {
            assert!(unmatchable_route(&r).is_some(), "{r:?}");
        }
    }

    #[cfg(feature = "http-client")]
    #[test]
    fn a_live_payment_record_is_never_evicted() {
        let mut used = UsedPayments::new(2);
        assert_eq!(used.claim([1; 32], 100, 10), Ok(()));
        assert_eq!(used.claim([1; 32], 100, 10), Err(ClaimError::Used));
        assert_eq!(used.claim([2; 32], 50, 10), Ok(()));
        // Full of live payments: refuse, never evict.
        assert_eq!(used.claim([3; 32], 100, 10), Err(ClaimError::Full));
        assert_eq!(used.claim([1; 32], 100, 10), Err(ClaimError::Used));
        // Once one expires, its slot is reused.
        assert_eq!(used.claim([3; 32], 100, 60), Ok(()));
        assert_eq!(used.claim([1; 32], 100, 60), Err(ClaimError::Used));
        // A released claim can be made again.
        used.release(&[3; 32]);
        assert_eq!(used.claim([3; 32], 100, 60), Ok(()));
    }

    #[cfg(feature = "http-client")]
    #[test]
    fn a_payment_has_one_key_however_it_is_written() {
        let parse = |s: &str| serde_json::from_str::<Value>(s).unwrap();
        let a = parse(
            r#"{"accepted":{"network":"eip155:8453","asset":"0xUSDC"},
               "payload":{"signature":"0xAB","authorization":{"from":"0xAbC","nonce":"0x01"}}}"#,
        );
        let b = parse(
            r#"{ "payload" : { "authorization" : { "nonce" : "0x0000001", "from" : "0xabc" },
                 "signature" : "0xab" }, "accepted" : { "asset" : "0xusdc", "network" : "eip155:8453" } }"#,
        );
        assert_eq!(payment_key(&a), payment_key(&b));
        let other_nonce = parse(
            r#"{"accepted":{"network":"eip155:8453","asset":"0xUSDC"},
               "payload":{"signature":"0xAB","authorization":{"from":"0xAbC","nonce":"0x02"}}}"#,
        );
        assert_ne!(payment_key(&a), payment_key(&other_nonce));
        let other_chain = parse(
            r#"{"accepted":{"network":"eip155:1","asset":"0xUSDC"},
               "payload":{"signature":"0xAB","authorization":{"from":"0xAbC","nonce":"0x01"}}}"#,
        );
        assert_ne!(payment_key(&a), payment_key(&other_chain));

        // No authorization: the signature, then the payload with sorted keys.
        assert_eq!(
            payment_key(&parse(r#"{"payload":{"signature":"0xSIG"}}"#)),
            payment_key(&parse(r#"{"payload":{"signature":"0xsig"}}"#))
        );
        assert_eq!(
            payment_key(&parse(
                r#"{"payload":{"transaction":"t","extra":[1,{"b":2,"a":1}]}}"#
            )),
            payment_key(&parse(
                r#"{"payload":{"extra":[1,{"a":1,"b":2}],"transaction":"t"}}"#
            ))
        );
    }

    #[cfg(feature = "http-client")]
    #[test]
    fn payment_expiry_reads_valid_before() {
        let payload = json!({"payload": {"authorization": {"validBefore": "1700"}}});
        assert_eq!(payment_expiry(&payload, 300, 1000), 1700);
        let payload = json!({"payload": {"authorization": {"validBefore": 1800}}});
        assert_eq!(payment_expiry(&payload, 300, 1000), 1800);
        assert_eq!(payment_expiry(&json!({}), 300, 1000), 1300);
    }

    #[cfg(feature = "http-client")]
    #[test]
    fn facilitator_must_be_https_or_loopback() {
        assert!(facilitator_url_is_safe("https://x402.org/facilitator"));
        assert!(facilitator_url_is_safe("http://localhost:8080"));
        assert!(facilitator_url_is_safe("http://[::1]:8080"));
        assert!(facilitator_url_is_safe("http://127.0.0.1:8080"));
        assert!(!facilitator_url_is_safe("http://facilitator.example"));
        assert!(!facilitator_url_is_safe("not a url"));
        assert!(!facilitator_url_is_safe("https://pay.example/api?key=x"));
        assert!(!facilitator_url_is_safe("https://pay.example/api#v1"));
    }

    #[test]
    fn route_matching() {
        let r = route();
        assert!(r.matches("GET", "/api/reports/7"));
        assert!(r.matches("get", "/api/reports/7"));
        assert!(!r.matches("POST", "/api/reports/7"));
        assert!(!r.matches("GET", "/api/reports"));
        assert!(!r.matches("GET", "/api/reports/7/x"));
        assert!(!r.matches("GET", "/api/reports/"));
    }

    #[test]
    fn config_completeness() {
        assert!(x402().is_complete());
        assert!(!X402Config::default().is_complete());
    }

    #[test]
    fn payment_required_is_x402_v2() {
        let pr = x402().payment_required(
            &route(),
            "https://shop.example/api/reports/7",
            "Payment required",
        );
        assert_eq!(pr["x402Version"], 2);
        assert_eq!(pr["error"], "Payment required");
        assert_eq!(pr["resource"]["url"], "https://shop.example/api/reports/7");
        assert_eq!(pr["resource"]["description"], "A report");
        let req = &pr["accepts"][0];
        assert_eq!(req["scheme"], "exact");
        assert_eq!(req["network"], "eip155:84532");
        assert_eq!(req["amount"], "10000");
        assert_eq!(req["asset"], "0xusdc");
        assert_eq!(req["payTo"], "0xabc");
        assert_eq!(req["maxTimeoutSeconds"], 300);
        assert_eq!(req["extra"], json!({"name": "USDC", "version": "2"}));
    }

    #[test]
    fn header_round_trip_uses_padded_standard_base64() {
        let v = json!({"a": "?>"});
        let h = encode_header(&v);
        assert!(
            h.bytes()
                .all(|b| b.is_ascii_alphanumeric() || b"+/=".contains(&b)),
            "{h}"
        );
        assert_eq!(decode_header(&h), Some(v));
        assert_eq!(decode_header("not base64!"), None);
        assert_eq!(decode_header(&STANDARD.encode("not json")), None);
    }

    #[test]
    fn accepted_must_match_the_offer() {
        let offered = x402().requirements(&route());
        assert!(accepted_matches(&offered.clone(), &offered));
        let mut cheaper = offered.clone();
        cheaper["amount"] = json!("1");
        assert!(!accepted_matches(&cheaper, &offered));
        let mut other_wallet = offered.clone();
        other_wallet["payTo"] = json!("0xevil");
        assert!(!accepted_matches(&other_wallet, &offered));
        assert!(!accepted_matches(&Value::Null, &offered));
    }

    /// Codex review (P2): an operation's own `402` is the app's
    /// documentation, so MPP leaves it as it is.
    #[test]
    fn mpp_keeps_a_documented_402() {
        let documented = json!({
            "description": "Pay first",
            "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } },
            "content": { "application/json": { "schema": { "type": "object" } } }
        });
        let mut spec = json!({
            "paths": {
                "/api/reports/{id}": { "get": { "responses": { "402": documented } } }
            }
        });
        apply_mpp(&mut spec, &[route()]);
        let op = &spec["paths"]["/api/reports/{id}"]["get"];
        assert!(op.get("x-payment-info").is_some());
        assert_eq!(op["responses"]["402"], documented);
    }

    #[test]
    fn mpp_extends_matching_operations() {
        let mut spec = json!({
            "openapi": "3.1.0",
            "paths": {
                "/api/reports/{id}": { "get": { "responses": { "200": { "description": "OK" } } } },
                "/api/free": { "get": { "responses": {} } }
            }
        });
        let mut no_mpp = route();
        no_mpp.path = "/api/free".to_owned();
        no_mpp.mpp_method = None;
        apply_mpp(&mut spec, &[route(), no_mpp]);
        let op = &spec["paths"]["/api/reports/{id}"]["get"];
        assert_eq!(
            op["x-payment-info"],
            json!({"intent": "charge", "method": "stripe", "amount": "10000", "currency": "usd", "description": "A report"})
        );
        assert_eq!(op["responses"]["402"]["description"], "Payment Required");
        assert_eq!(op["responses"]["200"]["description"], "OK");
        assert!(
            spec["paths"]["/api/free"]["get"]
                .get("x-payment-info")
                .is_none()
        );

        // With both forms in the spec, the exact one is priced (Codex review).
        let mut both = json!({
            "paths": {
                "/report": { "get": { "responses": {} } },
                "/report/": { "get": { "responses": {} } }
            }
        });
        let mut slashed = route();
        slashed.path = "/report/".to_owned();
        apply_mpp(&mut both, &[slashed]);
        assert!(
            both["paths"]["/report"]["get"]
                .get("x-payment-info")
                .is_none()
        );
        assert!(
            both["paths"]["/report/"]["get"]
                .get("x-payment-info")
                .is_some()
        );

        // A trailing `/` in the config still finds the operation.
        let mut slashed = route();
        slashed.path = "/api/free/".to_owned();
        apply_mpp(&mut spec, &[slashed]);
        assert!(
            spec["paths"]["/api/free"]["get"]
                .get("x-payment-info")
                .is_some()
        );

        // Capture names do not count, as at request time.
        let mut spec = json!({"paths": {"/api/reports/{id}": {"get": {}}}});
        let mut renamed = route();
        renamed.path = "/api/reports/{rid}".to_owned();
        apply_mpp(&mut spec, &[renamed]);
        assert!(
            spec["paths"]["/api/reports/{id}"]["get"]
                .get("x-payment-info")
                .is_some()
        );
    }

    #[test]
    fn ucp_requires_core_fields() {
        let ok = json!({"ucp": {"version": "2026-08-25", "services": {}, "payment_handlers": {}}});
        assert!(UcpProfile::new(ok).is_ok());
        let err =
            UcpProfile::new(json!({"ucp": {"version": "2026-08-25", "services": {}}})).unwrap_err();
        assert_eq!(
            err,
            CommerceError::Invalid {
                doc: "UCP profile",
                field: "ucp.payment_handlers"
            }
        );
        assert!(UcpProfile::new(json!({})).is_err());
    }

    #[test]
    fn acp_requires_core_fields() {
        let ok = json!({
            "protocol": {"name": "acp", "version": "2025-09-29", "supported_versions": ["2025-09-29"]},
            "api_base_url": "https://shop.example/api",
            "transports": ["rest"],
            "capabilities": {"services": ["checkout"]}
        });
        assert!(AcpDiscovery::new(ok.clone()).is_ok());
        for (field, patch) in [
            (
                "protocol.name",
                json!({"protocol": {"name": "x", "version": "1", "supported_versions": ["1"]}}),
            ),
            ("api_base_url", json!({"api_base_url": "/relative"})),
            ("transports", json!({"transports": []})),
            (
                "capabilities.services",
                json!({"capabilities": {"services": []}}),
            ),
        ] {
            let mut doc = ok.clone();
            for (k, v) in patch.as_object().unwrap() {
                doc[k] = v.clone();
            }
            assert!(
                matches!(AcpDiscovery::new(doc), Err(CommerceError::Invalid { field: f, .. }) if f == field),
                "{field}"
            );
        }
    }
}