use crate::{
AuthenticatedUser, Error, MwOAuthConfig, OAuthToken, PendingOAuthFlow, SessionStore,
UserProfile,
};
use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
use reqwest::{Client, Response, header};
use serde::Deserialize;
use sha2::{Digest, Sha256};
use std::time::{Duration, SystemTime, UNIX_EPOCH};
use subtle::ConstantTimeEq;
use url::Url;
const MAX_RESPONSE_SIZE: usize = 2 * 1024 * 1024;
#[derive(Clone)]
pub struct AuthorizationRequest {
pub url: Url,
pub state: String,
}
impl std::fmt::Debug for AuthorizationRequest {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("AuthorizationRequest")
.field("url", &"[REDACTED]")
.field("state", &"[REDACTED]")
.finish()
}
}
#[derive(Clone, Debug)]
pub struct MwOAuthClient {
config: MwOAuthConfig,
http: Client,
flow_ttl: Duration,
}
impl MwOAuthClient {
pub fn new(config: MwOAuthConfig) -> Result<Self, Error> {
let config = config.validate()?;
let http = Client::builder()
.user_agent(config.user_agent.clone())
.timeout(config.request_timeout)
.build()
.map_err(Error::from_http)?;
Ok(Self {
config,
http,
flow_ttl: crate::DEFAULT_FLOW_TTL,
})
}
pub fn with_flow_ttl(mut self, flow_ttl: Duration) -> Result<Self, Error> {
if flow_ttl.is_zero() {
return Err(Error::configuration("OAuth flow lifetime must be non-zero"));
}
self.flow_ttl = flow_ttl;
Ok(self)
}
pub fn config(&self) -> &MwOAuthConfig {
&self.config
}
pub fn begin_authorization(
&self,
session: &mut impl SessionStore,
scopes: &[&str],
) -> Result<AuthorizationRequest, Error> {
self.begin_authorization_at(session, scopes, unix_timestamp()?)
}
fn begin_authorization_at(
&self,
session: &mut impl SessionStore,
scopes: &[&str],
now: u64,
) -> Result<AuthorizationRequest, Error> {
let state = random_base64url(32)?;
let verifier = random_base64url(32)?;
let challenge = pkce_challenge(&verifier)?;
let flow = PendingOAuthFlow::new(state.clone(), verifier, now, self.flow_ttl)?;
session.set_pending_flow(flow)?;
let mut url = self.config.endpoint("rest.php/oauth2/authorize")?;
{
let mut query = url.query_pairs_mut();
query
.append_pair("response_type", "code")
.append_pair("client_id", &self.config.client_id)
.append_pair("state", &state)
.append_pair("code_challenge", &challenge)
.append_pair("code_challenge_method", "S256");
if let Some(redirect_uri) = &self.config.redirect_uri {
query.append_pair("redirect_uri", redirect_uri.as_str());
}
if !scopes.is_empty() {
query.append_pair("scope", &scopes.join(" "));
}
}
Ok(AuthorizationRequest { url, state })
}
pub async fn complete_authorization(
&self,
session: &mut impl SessionStore,
code: &str,
callback_state: &str,
) -> Result<AuthenticatedUser, Error> {
self.complete_authorization_at(session, code, callback_state, unix_timestamp()?)
.await
}
async fn complete_authorization_at(
&self,
session: &mut impl SessionStore,
code: &str,
callback_state: &str,
now: u64,
) -> Result<AuthenticatedUser, Error> {
let flow = session
.take_pending_flow()?
.ok_or(Error::MissingFlowState)?;
validate_pending_flow(&flow, callback_state, now, self.flow_ttl)?;
let token = self.exchange_code(code, flow.pkce_verifier()).await?;
let profile = self.fetch_user_profile(token.access_token()).await?;
let user = AuthenticatedUser::new(profile, token, now);
session.set_authenticated_user(user.clone())?;
Ok(user)
}
pub async fn exchange_code(
&self,
authorization_code: &str,
pkce_verifier: &str,
) -> Result<OAuthToken, Error> {
if authorization_code.is_empty() || !valid_pkce_verifier(pkce_verifier) {
return Err(Error::InvalidPkce);
}
let mut form = vec![
("grant_type", "authorization_code"),
("code", authorization_code),
("client_id", self.config.client_id.as_str()),
("code_verifier", pkce_verifier),
];
if let Some(redirect_uri) = &self.config.redirect_uri {
form.push(("redirect_uri", redirect_uri.as_str()));
}
self.request_token(form).await
}
pub async fn refresh_token(&self, refresh_token: &str) -> Result<OAuthToken, Error> {
if refresh_token.is_empty() {
return Err(Error::OAuthProvider {
error: "invalid_refresh_token".to_owned(),
});
}
self.request_token(vec![
("grant_type", "refresh_token"),
("refresh_token", refresh_token),
("client_id", self.config.client_id.as_str()),
])
.await
}
pub async fn refresh_authenticated_user(
&self,
current: &AuthenticatedUser,
) -> Result<AuthenticatedUser, Error> {
let refresh_token = current
.token()
.refresh_token()
.ok_or(Error::SessionExpired)?;
let mut token = self.refresh_token(refresh_token).await?;
token.retain_refresh_token(refresh_token);
let profile = self.fetch_user_profile(token.access_token()).await?;
Ok(AuthenticatedUser::refreshed(
profile,
token,
current,
unix_timestamp()?,
))
}
async fn request_token(&self, mut form: Vec<(&str, &str)>) -> Result<OAuthToken, Error> {
if let Some(secret) = self.config.client_secret.as_deref() {
form.push(("client_secret", secret));
}
let response = self
.http
.post(self.config.endpoint("rest.php/oauth2/access_token")?)
.header(header::ACCEPT, "application/json")
.form(&form)
.send()
.await
.map_err(Error::from_http)?;
decode_token_response(response).await
}
pub async fn fetch_user_profile(&self, access_token: &str) -> Result<UserProfile, Error> {
let response = self
.http
.get(self.config.endpoint("rest.php/oauth2/resource/profile")?)
.bearer_auth(access_token)
.send()
.await
.map_err(Error::from_http)?;
decode_profile_response(response).await
}
}
fn unix_timestamp() -> Result<u64, Error> {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|duration| duration.as_secs())
.map_err(|_| Error::configuration("system clock is before the Unix epoch"))
}
fn random_base64url(size: usize) -> Result<String, Error> {
let mut bytes = vec![0_u8; size];
getrandom::fill(&mut bytes).map_err(|_| Error::Randomness)?;
Ok(URL_SAFE_NO_PAD.encode(bytes))
}
fn pkce_challenge(verifier: &str) -> Result<String, Error> {
if !valid_pkce_verifier(verifier) {
return Err(Error::InvalidPkce);
}
Ok(URL_SAFE_NO_PAD.encode(Sha256::digest(verifier.as_bytes())))
}
fn valid_pkce_verifier(verifier: &str) -> bool {
(43..=128).contains(&verifier.len())
&& verifier
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'.' | b'_' | b'~'))
}
fn valid_state(state: &str) -> bool {
state.len() == 43
&& state
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
}
fn validate_pending_flow(
flow: &PendingOAuthFlow,
callback_state: &str,
now: u64,
ttl: Duration,
) -> Result<(), Error> {
if now >= flow.expires_at() {
return Err(Error::ExpiredFlowState(ttl));
}
if !valid_state(flow.state()) || !valid_state(callback_state) {
return Err(Error::InvalidFlowState);
}
let expected = flow.state().as_bytes();
let supplied = callback_state.as_bytes();
if expected.len() != supplied.len() || expected.ct_eq(supplied).unwrap_u8() != 1 {
return Err(Error::StateMismatch);
}
if !valid_pkce_verifier(flow.pkce_verifier()) {
return Err(Error::InvalidPkce);
}
Ok(())
}
#[derive(Deserialize)]
struct ProviderError {
error: String,
}
async fn response_bytes(mut response: Response) -> Result<Vec<u8>, Error> {
if response
.content_length()
.is_some_and(|length| length > MAX_RESPONSE_SIZE as u64)
{
return Err(Error::ResponseTooLarge {
limit: MAX_RESPONSE_SIZE,
});
}
let mut body = Vec::new();
while let Some(chunk) = response.chunk().await.map_err(Error::from_http)? {
if body.len().saturating_add(chunk.len()) > MAX_RESPONSE_SIZE {
return Err(Error::ResponseTooLarge {
limit: MAX_RESPONSE_SIZE,
});
}
body.extend_from_slice(&chunk);
}
Ok(body)
}
async fn decode_token_response(response: Response) -> Result<OAuthToken, Error> {
let status = response.status();
let bytes = response_bytes(response).await?;
if !status.is_success() {
if let Ok(provider) = serde_json::from_slice::<ProviderError>(&bytes) {
return Err(Error::OAuthProvider {
error: sanitize_provider_error(&provider.error),
});
}
return Err(Error::TokenExchange {
status: status.as_u16(),
});
}
serde_json::from_slice(&bytes).map_err(Error::TokenDecode)
}
async fn decode_profile_response(response: Response) -> Result<UserProfile, Error> {
let status = response.status();
let bytes = response_bytes(response).await?;
if !status.is_success() {
return Err(Error::ProfileRequest {
status: status.as_u16(),
});
}
serde_json::from_slice(&bytes).map_err(Error::ProfileDecode)
}
fn sanitize_provider_error(value: &str) -> String {
let sanitized: String = value
.chars()
.filter(|character| character.is_ascii_alphanumeric() || matches!(character, '_' | '-'))
.take(64)
.collect();
if sanitized.is_empty() {
"unknown_error".to_owned()
} else {
sanitized
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::session::MemorySessionStore;
use reqwest::StatusCode;
use std::collections::HashMap;
use std::io;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
use tokio::time::sleep;
fn config(base: &str) -> MwOAuthConfig {
MwOAuthConfig::confidential(
Url::parse(base).unwrap(),
"client-id",
"client-secret",
Url::parse("https://app.test/oauth/callback").unwrap(),
"mwoauth-test/1.0",
)
.unwrap()
}
#[test]
fn pkce_matches_rfc_7636_vector() {
let verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";
assert_eq!(
pkce_challenge(verifier).unwrap(),
"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
);
assert!(matches!(
pkce_challenge("too-short"),
Err(Error::InvalidPkce)
));
}
#[test]
fn builds_authorization_url_and_stores_flow() {
let client = MwOAuthClient::new(config("https://wiki.test/w/api.php")).unwrap();
let mut session = MemorySessionStore::default();
let request = client
.begin_authorization_at(&mut session, &["basic", "edit"], 100)
.unwrap();
let params: HashMap<_, _> = request.url.query_pairs().into_owned().collect();
assert_eq!(request.url.path(), "/w/rest.php/oauth2/authorize");
assert_eq!(params.get("response_type").unwrap(), "code");
assert_eq!(params.get("client_id").unwrap(), "client-id");
assert_eq!(params.get("scope").unwrap(), "basic edit");
assert_eq!(params.get("code_challenge_method").unwrap(), "S256");
assert_eq!(params.get("state").unwrap(), &request.state);
assert!(valid_state(&request.state));
assert!(session.pending_flow().unwrap().is_some());
let second = client
.begin_authorization_at(&mut session, &[], 100)
.unwrap();
assert_ne!(request.state, second.state);
}
#[test]
fn rejects_mismatch_expiry_and_replay() {
let client = MwOAuthClient::new(config("https://wiki.test/w/api.php")).unwrap();
let mut session = MemorySessionStore::default();
let request = client
.begin_authorization_at(&mut session, &[], 100)
.unwrap();
let flow = session.take_pending_flow().unwrap().unwrap();
assert!(matches!(
validate_pending_flow(&flow, &"x".repeat(43), 101, client.flow_ttl),
Err(Error::StateMismatch)
));
assert!(matches!(
validate_pending_flow(&flow, "malformed", 101, client.flow_ttl),
Err(Error::InvalidFlowState)
));
assert!(session.take_pending_flow().unwrap().is_none());
session.set_pending_flow(flow.clone()).unwrap();
let consumed = session.take_pending_flow().unwrap().unwrap();
assert!(matches!(
validate_pending_flow(&consumed, &request.state, 701, client.flow_ttl),
Err(Error::ExpiredFlowState(_))
));
}
#[tokio::test]
async fn exchanges_token_and_fetches_profile() {
let (base, server) = mock_server(vec![
MockResponse::json(
StatusCode::OK,
r#"{"access_token":"access-secret","refresh_token":"refresh-secret","expires_in":3600,"token_type":"Bearer"}"#,
)
.expect("POST /w/rest.php/oauth2/access_token")
.expect("user-agent: mwoauth-test/1.0")
.expect("code=authorization-secret")
.expect("client_secret=client-secret")
.expect("code_verifier=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"),
MockResponse::json(StatusCode::OK, profile_json())
.expect("GET /w/rest.php/oauth2/resource/profile")
.expect("authorization: Bearer access-secret")
.expect("user-agent: mwoauth-test/1.0"),
])
.await;
let client = MwOAuthClient::new(config(&base)).unwrap();
let token = client
.exchange_code("authorization-secret", &"a".repeat(43))
.await
.unwrap();
assert_eq!(token.access_token(), "access-secret");
let profile = client
.fetch_user_profile(token.access_token())
.await
.unwrap();
assert_eq!(profile.username(), "Example");
server.await.unwrap().unwrap();
}
#[tokio::test]
async fn maps_provider_status_and_decode_errors_without_secrets() {
let secret = "authorization-secret";
let (base, server) = mock_server(vec![MockResponse::json(
StatusCode::BAD_REQUEST,
r#"{"error":"invalid_grant","error_description":"authorization-secret"}"#,
)])
.await;
let client = MwOAuthClient::new(config(&base)).unwrap();
let error = client
.exchange_code(secret, &"a".repeat(43))
.await
.unwrap_err();
assert!(matches!(error, Error::OAuthProvider { .. }));
assert!(!error.to_string().contains(secret));
server.await.unwrap().unwrap();
let (base, server) =
mock_server(vec![MockResponse::json(StatusCode::OK, "not json")]).await;
let client = MwOAuthClient::new(config(&base)).unwrap();
assert!(matches!(
client.exchange_code(secret, &"a".repeat(43)).await,
Err(Error::TokenDecode(_))
));
server.await.unwrap().unwrap();
}
#[tokio::test]
async fn completes_flow_stores_user_and_prevents_replay() {
let (base, server) = mock_server(vec![
MockResponse::json(
StatusCode::OK,
r#"{"access_token":"access-secret","expires_in":3600}"#,
),
MockResponse::json(StatusCode::OK, profile_json()),
])
.await;
let client = MwOAuthClient::new(config(&base)).unwrap();
let mut session = MemorySessionStore::default();
let request = client
.begin_authorization_at(&mut session, &[], 100)
.unwrap();
let user = client
.complete_authorization_at(&mut session, "code", &request.state, 101)
.await
.unwrap();
assert_eq!(user.profile().username(), "Example");
assert_eq!(
session
.authenticated_user()
.unwrap()
.unwrap()
.profile()
.username(),
"Example"
);
assert!(matches!(
client
.complete_authorization_at(&mut session, "code", &request.state, 102)
.await,
Err(Error::MissingFlowState)
));
session.clear().unwrap();
assert!(session.authenticated_user().unwrap().is_none());
server.await.unwrap().unwrap();
}
#[tokio::test]
async fn refreshes_tokens_with_client_credentials() {
let (base, server) = mock_server(vec![
MockResponse::json(
StatusCode::OK,
r#"{"access_token":"new-access","refresh_token":"new-refresh","expires_in":3600}"#,
)
.expect("grant_type=refresh_token")
.expect("refresh_token=old-refresh")
.expect("client_id=client-id")
.expect("client_secret=client-secret"),
])
.await;
let client = MwOAuthClient::new(config(&base)).unwrap();
let token = client.refresh_token("old-refresh").await.unwrap();
assert_eq!(token.access_token(), "new-access");
assert_eq!(token.refresh_token(), Some("new-refresh"));
server.await.unwrap().unwrap();
}
#[tokio::test]
async fn rejects_profile_error_status_and_malformed_json() {
let (base, server) = mock_server(vec![MockResponse::json(
StatusCode::UNAUTHORIZED,
r#"{"error":"invalid_token"}"#,
)])
.await;
let client = MwOAuthClient::new(config(&base)).unwrap();
assert!(matches!(
client.fetch_user_profile("access-secret").await,
Err(Error::ProfileRequest { status: 401 })
));
server.await.unwrap().unwrap();
let (base, server) =
mock_server(vec![MockResponse::json(StatusCode::OK, "not json")]).await;
let client = MwOAuthClient::new(config(&base)).unwrap();
assert!(matches!(
client.fetch_user_profile("access-secret").await,
Err(Error::ProfileDecode(_))
));
server.await.unwrap().unwrap();
}
#[tokio::test]
async fn maps_generic_token_status_and_timeout() {
let (base, server) = mock_server(vec![MockResponse::json(
StatusCode::INTERNAL_SERVER_ERROR,
"not json",
)])
.await;
let client = MwOAuthClient::new(config(&base)).unwrap();
assert!(matches!(
client.exchange_code("code", &"a".repeat(43)).await,
Err(Error::TokenExchange { status: 500 })
));
server.await.unwrap().unwrap();
let (base, server) = mock_server(vec![
MockResponse::json(StatusCode::OK, profile_json())
.with_delay(Duration::from_millis(100)),
])
.await;
let timeout_config = config(&base)
.with_request_timeout(Duration::from_millis(10))
.unwrap();
let client = MwOAuthClient::new(timeout_config).unwrap();
assert!(matches!(
client.fetch_user_profile("access-secret").await,
Err(Error::Timeout)
));
server.await.unwrap().unwrap();
}
#[test]
fn secret_bearing_debug_output_is_redacted() {
let config = config("https://wiki.test/w/api.php");
assert!(!format!("{config:?}").contains("client-secret"));
let token: OAuthToken = serde_json::from_str(
r#"{"access_token":"access-secret","refresh_token":"refresh-secret"}"#,
)
.unwrap();
let profile: UserProfile = serde_json::from_str(profile_json()).unwrap();
let user = AuthenticatedUser::new(profile, token, 100);
let original_expiry = user.session_expires_at();
let refreshed_token: OAuthToken =
serde_json::from_str(r#"{"access_token":"new-access","refresh_token":"new-refresh"}"#)
.unwrap();
let refreshed_profile: UserProfile = serde_json::from_str(profile_json()).unwrap();
let refreshed =
AuthenticatedUser::refreshed(refreshed_profile, refreshed_token, &user, 200);
assert_eq!(refreshed.session_expires_at(), original_expiry);
let debug = format!("{user:?}");
assert!(!debug.contains("access-secret"));
assert!(!debug.contains("refresh-secret"));
assert!(!debug.contains("Example"));
let request = AuthorizationRequest {
url: Url::parse("https://wiki.test/oauth?state=state-secret").unwrap(),
state: "state-secret".to_owned(),
};
assert!(!format!("{request:?}").contains("state-secret"));
let flow = PendingOAuthFlow::new(
"state-secret".to_owned(),
"verifier-secret".to_owned(),
100,
Duration::from_secs(10),
)
.unwrap();
let debug = format!("{flow:?}");
assert!(!debug.contains("state-secret"));
assert!(!debug.contains("verifier-secret"));
}
fn profile_json() -> &'static str {
r#"{"sub":"42","username":"Example","blocked":false,"confirmed_email":true,"editcount":10,"email_verified":true,"grants":["basic"],"groups":["user"],"registered":"2020-01-01T00:00:00Z","rights":["read"]}"#
}
struct MockResponse {
status: StatusCode,
body: &'static str,
expected_request_fragments: Vec<&'static str>,
delay: Duration,
}
impl MockResponse {
fn json(status: StatusCode, body: &'static str) -> Self {
Self {
status,
body,
expected_request_fragments: Vec::new(),
delay: Duration::ZERO,
}
}
fn expect(mut self, fragment: &'static str) -> Self {
self.expected_request_fragments.push(fragment);
self
}
fn with_delay(mut self, delay: Duration) -> Self {
self.delay = delay;
self
}
}
async fn mock_server(
responses: Vec<MockResponse>,
) -> (String, tokio::task::JoinHandle<io::Result<()>>) {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move {
for response in responses {
let (mut stream, _) = listener.accept().await?;
let mut request = vec![0_u8; 8192];
let bytes_read = stream.read(&mut request).await?;
let request = String::from_utf8_lossy(&request[..bytes_read]);
let request_lowercase = request.to_ascii_lowercase();
for expected in response.expected_request_fragments {
if !request_lowercase.contains(&expected.to_ascii_lowercase()) {
return Err(io::Error::other(format!(
"request did not contain expected fragment: {expected}"
)));
}
}
if !response.delay.is_zero() {
sleep(response.delay).await;
}
let reason = response.status.canonical_reason().unwrap_or("Unknown");
let message = format!(
"HTTP/1.1 {} {}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
response.status.as_u16(),
reason,
response.body.len(),
response.body
);
stream.write_all(message.as_bytes()).await?;
}
Ok(())
});
(format!("http://{address}/w/api.php"), server)
}
}