mwoauth 0.1.0-rc.1

MediaWiki OAuth 2.0 client with optional Rocket, Axum, and Actix Web adapters
Documentation
// SPDX-License-Identifier: GPL-3.0-or-later

use crate::Error;
use reqwest::header::HeaderValue;
use serde::{Deserialize, Serialize};
use std::time::Duration;
use url::Url;

const DEFAULT_TIMEOUT: Duration = Duration::from_secs(15);

/// Framework-independent configuration for MediaWiki OAuth 2.0.
#[derive(Clone, Deserialize, Serialize)]
pub struct MwOAuthConfig {
    /// OAuth 2.0 client identifier.
    pub client_id: String,
    /// OAuth 2.0 client secret. Public clients may omit this and use PKCE only.
    #[serde(default)]
    pub client_secret: Option<String>,
    /// MediaWiki API URL, REST base URL, or wiki base URL.
    #[serde(alias = "base_url")]
    pub wiki_url: Url,
    /// Exact callback URI registered for the OAuth client.
    ///
    /// When omitted, MediaWiki uses the callback registered for the client.
    #[serde(default)]
    pub redirect_uri: Option<Url>,
    /// User-Agent sent with every request to MediaWiki.
    pub user_agent: String,
    /// Timeout applied to each outbound HTTP request.
    #[serde(default = "default_timeout", with = "duration_seconds")]
    pub request_timeout: Duration,
}

fn default_timeout() -> Duration {
    DEFAULT_TIMEOUT
}

mod duration_seconds {
    use serde::{Deserialize, Deserializer, Serializer};
    use std::time::Duration;

    pub fn serialize<S>(value: &Duration, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_u64(value.as_secs())
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<Duration, D::Error>
    where
        D: Deserializer<'de>,
    {
        u64::deserialize(deserializer).map(Duration::from_secs)
    }
}

impl std::fmt::Debug for MwOAuthConfig {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("MwOAuthConfig")
            .field("client_id", &self.client_id)
            .field(
                "client_secret",
                &self.client_secret.as_ref().map(|_| "[REDACTED]"),
            )
            .field("wiki_url", &self.wiki_url)
            .field("redirect_uri", &self.redirect_uri)
            .field("user_agent", &self.user_agent)
            .field("request_timeout", &self.request_timeout)
            .finish()
    }
}

impl MwOAuthConfig {
    /// Construct configuration for a confidential OAuth client.
    pub fn confidential(
        wiki_url: Url,
        client_id: impl Into<String>,
        client_secret: impl Into<String>,
        redirect_uri: Url,
        user_agent: impl Into<String>,
    ) -> Result<Self, Error> {
        Self {
            client_id: client_id.into(),
            client_secret: Some(client_secret.into()),
            wiki_url,
            redirect_uri: Some(redirect_uri),
            user_agent: user_agent.into(),
            request_timeout: DEFAULT_TIMEOUT,
        }
        .validate()
    }

    /// Construct configuration for a public OAuth client using PKCE.
    pub fn public(
        wiki_url: Url,
        client_id: impl Into<String>,
        redirect_uri: Url,
        user_agent: impl Into<String>,
    ) -> Result<Self, Error> {
        Self {
            client_id: client_id.into(),
            client_secret: None,
            wiki_url,
            redirect_uri: Some(redirect_uri),
            user_agent: user_agent.into(),
            request_timeout: DEFAULT_TIMEOUT,
        }
        .validate()
    }

    /// Use the callback URI registered at MediaWiki without sending an explicit
    /// `redirect_uri` parameter.
    pub fn with_registered_redirect(mut self) -> Self {
        self.redirect_uri = None;
        self
    }

    /// Set the per-request timeout.
    pub fn with_request_timeout(mut self, timeout: Duration) -> Result<Self, Error> {
        self.request_timeout = timeout;
        self.validate()
    }

    /// Validate and normalize this configuration.
    pub fn validate(mut self) -> Result<Self, Error> {
        validate_http_url("wiki_url", &self.wiki_url)?;
        if let Some(redirect_uri) = &self.redirect_uri {
            validate_http_url("redirect_uri", redirect_uri)?;
            if redirect_uri.fragment().is_some() {
                return Err(Error::configuration(
                    "redirect_uri must not contain a fragment",
                ));
            }
        }

        if self.wiki_url.query().is_some() || self.wiki_url.fragment().is_some() {
            return Err(Error::configuration(
                "wiki_url must not contain a query string or fragment",
            ));
        }
        if self.client_id.trim().is_empty() {
            return Err(Error::configuration("client_id must not be empty"));
        }
        if self
            .client_secret
            .as_ref()
            .is_some_and(|secret| secret.trim().is_empty())
        {
            return Err(Error::configuration(
                "client_secret must be omitted or non-empty",
            ));
        }
        if self.user_agent.trim().is_empty() || HeaderValue::from_str(&self.user_agent).is_err() {
            return Err(Error::configuration(
                "user_agent must be a non-empty valid HTTP header value",
            ));
        }
        if self.request_timeout.is_zero() {
            return Err(Error::configuration("request_timeout must be non-zero"));
        }

        self.wiki_url = normalize_wiki_url(self.wiki_url)?;
        Ok(self)
    }

    /// Base URL ending in `/`, immediately before `rest.php`.
    pub fn base_url(&self) -> &Url {
        &self.wiki_url
    }

    pub(crate) fn endpoint(&self, path: &str) -> Result<Url, Error> {
        self.wiki_url.join(path).map_err(|_| Error::UrlConstruction)
    }
}

fn validate_http_url(name: &str, url: &Url) -> Result<(), Error> {
    if !matches!(url.scheme(), "http" | "https") || url.host_str().is_none() {
        return Err(Error::configuration(format!(
            "{name} must be an absolute HTTP(S) URL"
        )));
    }
    Ok(())
}

fn normalize_wiki_url(mut url: Url) -> Result<Url, Error> {
    let path = url.path().trim_end_matches('/');
    let base_path = if let Some(prefix) = path.strip_suffix("/api.php") {
        prefix
    } else if let Some(prefix) = path.strip_suffix("/rest.php") {
        prefix
    } else {
        path
    };
    let normalized = if base_path.is_empty() {
        "/".to_owned()
    } else {
        format!("{base_path}/")
    };
    url.set_path(&normalized);
    url.set_query(None);
    url.set_fragment(None);
    Ok(url)
}

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

    fn url(value: &str) -> Url {
        Url::parse(value).unwrap()
    }

    #[test]
    fn normalizes_api_and_rest_urls() {
        for input in [
            "https://example.test/w/api.php",
            "https://example.test/w/rest.php/",
            "https://example.test/w/",
        ] {
            let config = MwOAuthConfig::public(
                url(input),
                "client",
                url("https://app.test/oauth/callback"),
                "test/1.0",
            )
            .unwrap();
            assert_eq!(config.base_url().as_str(), "https://example.test/w/");
        }
    }

    #[test]
    fn rejects_invalid_configuration_without_exposing_secret() {
        let secret = "super-secret";
        let error = MwOAuthConfig::confidential(
            url("ftp://example.test/w/api.php"),
            "client",
            secret,
            url("https://app.test/callback"),
            "test/1.0",
        )
        .unwrap_err();
        assert!(matches!(error, Error::Configuration(_)));
        assert!(!error.to_string().contains(secret));
    }

    #[test]
    fn rejects_empty_credentials_and_unsafe_redirect() {
        assert!(
            MwOAuthConfig::public(
                url("https://example.test/w/api.php"),
                "",
                url("https://app.test/callback"),
                "test/1.0",
            )
            .is_err()
        );
        assert!(
            MwOAuthConfig::public(
                url("https://example.test/w/api.php"),
                "client",
                url("https://app.test/callback#fragment"),
                "test/1.0",
            )
            .is_err()
        );
    }
}