tuwunel_api_client/session/

sso.rs

mod uiaa;

use std::{borrow::Cow, collections::BTreeMap, net::IpAddr, time::Duration};

use axum::{
	extract::State,
	response::{Html, IntoResponse, Response},
};
use axum_extra::extract::cookie::{Cookie, CookieJar, SameSite};
use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD as b64};
use const_str::format as const_format;
use futures::{TryFutureExt, future::try_join};
use reqwest::header::{
	CACHE_CONTROL, CONTENT_SECURITY_POLICY, CONTENT_TYPE, HeaderValue, REFERRER_POLICY,
	SET_COOKIE,
};
use ruma::{
	Mxc, OwnedMxcUri, OwnedUserId, ServerName, UserId,
	api::{
		client::{
			session::{
				SsoRedirectAction,
				sso_callback::{self, unstable::Response as SsoCallbackResponse},
				sso_login, sso_login_with_provider,
			},
			uiaa::AuthType,
		},
		error::ErrorKind,
	},
};
use serde::{Deserialize, Serialize};
use serde_html_form::{from_str as from_form_str, to_string as to_form_string};
use serde_json::Value as JsonValue;
use tuwunel_core::{
	Err, Result, at,
	config::IdentityProvider,
	debug::INFO_SPAN_LEVEL,
	debug_info, debug_warn, err, info, is_not_equal_to,
	itertools::Itertools,
	utils,
	utils::{
		content_disposition::make_content_disposition,
		deadline_has_passed, deserialize_lenient_bool,
		hash::sha256,
		html::escape as html_escape,
		result::{FlatOk, LogErr},
		stream::ReadyExt,
		string::EMPTY,
		timepoint_from_now,
		url::redirect_allowlisted,
	},
	warn,
};
use tuwunel_service::{
	Services,
	client::read_response_capped,
	media::MXC_LENGTH,
	oauth::{
		CODE_VERIFIER_LENGTH, Provider, SESSION_ID_LENGTH, Session, TokenResponse, UserInfo,
		fallback_localpart, unique_id_sub,
	},
	threepid::canonicalize_email,
	users::{PASSWORD_SENTINEL, Register},
};
use url::Url;

pub(crate) use self::uiaa::{sso_complete_js_route, sso_css_route, sso_fallback_route};
use super::TOKEN_LENGTH;
use crate::{ClientIp, Ruma, RumaResponse, router::ACCOUNT_HEAD, utils::bind_new_account_email};

/// Grant phase query string.
#[derive(Debug, Serialize)]
struct GrantQuery<'a> {
	client_id: &'a str,
	state: &'a str,
	nonce: &'a str,
	scope: &'a str,
	response_type: &'a str,
	access_type: &'a str,
	code_challenge_method: &'a str,
	code_challenge: &'a str,
	redirect_uri: Option<&'a str>,
	#[serde(skip_serializing_if = "Option::is_none")]
	prompt: Option<&'a str>,
}

#[derive(Debug, Deserialize, Serialize)]
struct GrantCookie<'a> {
	client_id: Cow<'a, str>,
	state: Cow<'a, str>,
	nonce: Cow<'a, str>,
	redirect_uri: Cow<'a, str>,
}

static GRANT_SESSION_COOKIE: &str = "tuwunel_grant_session";

static CONFIRM_HTML: &str = const_format!(
	r#"
<!DOCTYPE html>
<html lang="en">
	<head>
		{ACCOUNT_HEAD}
		<title>Continue sign-in · Tuwunel</title>
	</head>
	<body class="auth-page">
		<main class="auth-card auth-complete" aria-labelledby="auth-title">
			<h1 id="auth-title">Continue sign-in</h1>
			<p class="auth-description">
				You are signing in as <strong>{{user}}</strong> to <strong>{{target}}</strong>.
			</p>
			<p class="auth-description">Continue only if you started this sign-in.</p>
			<a class="auth-continue-link" href="{{location}}">Continue</a>
		</main>
	</body>
</html>"#
);

fn decode_apple_userinfo_from_id_token(session: &Session) -> Result<UserInfo> {
	let id_token = session.id_token.as_deref().ok_or_else(|| {
		err!(Request(Unauthorized("Missing Apple id_token in token response.")))
	})?;

	let payload_b64 = id_token
		.split('.')
		.nth(1)
		.ok_or_else(|| err!(Request(Unauthorized("Apple id_token is malformed."))))?;

	let payload = b64
		.decode(payload_b64)
		.map_err(|_| err!(Request(Unauthorized("Apple id_token payload is invalid base64."))))?;

	let payload: JsonValue = serde_json::from_slice(&payload)
		.map_err(|_| err!(Request(Unauthorized("Apple id_token payload is not valid JSON."))))?;

	let sub = payload
		.get("sub")
		.and_then(JsonValue::as_str)
		.ok_or_else(|| {
			err!(Request(Unauthorized("Apple id_token missing required sub claim.")))
		})?;

	let email = payload
		.get("email")
		.and_then(JsonValue::as_str)
		.map(ToOwned::to_owned);

	let email_verified = payload
		.get("email_verified")
		.map(deserialize_lenient_bool)
		.flat_ok()
		.flatten();

	let preferred_username = email
		.as_deref()
		.and_then(|value| value.split_once('@'))
		.map(at!(0))
		.map(ToOwned::to_owned);

	Ok(UserInfo {
		sub: sub.to_owned(),
		preferred_username: preferred_username.clone(),
		username: preferred_username,
		nickname: None,
		name: payload
			.get("name")
			.and_then(JsonValue::as_str)
			.map(ToOwned::to_owned),
		given_name: payload
			.get("given_name")
			.and_then(JsonValue::as_str)
			.map(ToOwned::to_owned),
		family_name: payload
			.get("family_name")
			.and_then(JsonValue::as_str)
			.map(ToOwned::to_owned),
		email,
		email_verified,
		avatar_url: None,
		picture: None,
	})
}

/// # `GET /_matrix/client/v3/login/sso/redirect`
///
/// A web-based Matrix client should instruct the user’s browser to navigate to
/// this endpoint in order to log in via SSO.
#[tracing::instrument(
	name = "sso_login",
	level = "debug",
	skip_all,
	fields(%client),
)]
pub(crate) async fn sso_login_route(
	State(services): State<crate::State>,
	ClientIp(client): ClientIp,
	body: Ruma<sso_login::v3::Request>,
) -> Result<sso_login::v3::Response> {
	if services
		.config
		.authentication
		.login
		.sso_custom_providers_page
	{
		return Err!(Request(NotImplemented(
			"authentication.login.sso_custom_providers_page has been enabled but this URL has \
			 not been overridden with any custom page listing the available providers..."
		)));
	}

	let redirect_url = body.body.redirect_url;
	let action = body.body.action;
	let default_idp_id = services
		.oauth
		.providers
		.get_default_id()
		.unwrap_or_default();

	handle_sso_login(&services, &client, default_idp_id, redirect_url, None, action)
		.map_ok(|response| sso_login::v3::Response {
			location: response.location,
			cookie: response.cookie,
		})
		.await
}

/// # `GET /_matrix/client/v3/login/sso/redirect/{idpId}`
///
/// This endpoint is the same as /login/sso/redirect, though with an IdP ID from
/// the original identity_providers array to inform the server of which IdP the
/// client/user would like to continue with.
#[tracing::instrument(
	name = "sso_login_with_provider",
	level = "info",
	skip_all,
	err(level = "debug"),
	fields(
		%client,
		idp_id = body.body.idp_id,
	),
)]
pub(crate) async fn sso_login_with_provider_route(
	State(services): State<crate::State>,
	ClientIp(client): ClientIp,
	body: Ruma<sso_login_with_provider::v3::Request>,
) -> Result<sso_login_with_provider::v3::Response> {
	let idp_id = body.body.idp_id;
	let redirect_url = body.body.redirect_url;
	let action = body.body.action;

	handle_sso_login(&services, &client, idp_id, redirect_url, None, action).await
}

async fn handle_sso_login(
	services: &Services,
	_client: &IpAddr,
	idp_id: String,
	redirect_url: String,
	user_id: Option<OwnedUserId>,
	action: Option<SsoRedirectAction>,
) -> Result<sso_login_with_provider::v3::Response> {
	let redirect_url: Url = redirect_url.parse().map_err(|e| {
		err!(Request(InvalidParam(debug_warn!(
			?e,
			?redirect_url,
			"Failed to parse redirect_url.",
		))))
	})?;

	validate_redirect_url(&redirect_url)?;

	let provider = services.oauth.providers.get(&idp_id).await?;
	let sess_id = utils::random_string(SESSION_ID_LENGTH);
	let query_nonce = utils::random_string(CODE_VERIFIER_LENGTH);
	let cookie_nonce = utils::random_string(CODE_VERIFIER_LENGTH);
	let code_verifier = utils::random_string(CODE_VERIFIER_LENGTH);
	let code_challenge = b64.encode(sha256::hash(code_verifier.as_bytes()));
	let callback_uri = provider.callback_url.as_ref().map(Url::as_str);
	let scope = provider.scope.iter().join(" ");
	let prompt = action
		.filter(|_| provider.forward_action_prompt)
		.and_then(|action| matches!(action, SsoRedirectAction::Register).then_some("create"));

	let query = GrantQuery {
		client_id: &provider.client_id,
		state: &sess_id,
		nonce: &query_nonce,
		access_type: "online",
		response_type: "code",
		code_challenge_method: "S256",
		code_challenge: &code_challenge,
		redirect_uri: callback_uri,
		prompt,
		scope: scope
			.is_empty()
			.then_some("openid email profile")
			.unwrap_or(scope.as_str()),
	};

	let location = provider
		.authorization_url
		.clone()
		.map(|mut location| {
			location.set_query(to_form_string(&query).ok().as_deref());
			if !provider.extra_authorization_parameters.is_empty() {
				// Base wins on key collision so extras cannot disable CSRF/PKCE.
				let merged: BTreeMap<String, String> = provider
					.extra_authorization_parameters
					.clone()
					.into_iter()
					.chain(
						location
							.query_pairs()
							.map(|(k, v)| (k.into_owned(), v.into_owned())),
					)
					.collect();

				location.set_query(None);
				location.query_pairs_mut().extend_pairs(&merged);
			}
			location
		})
		.ok_or_else(|| {
			err!(Config("authorization_url", "Missing required IdentityProvider config"))
		})?;

	let cookie_val = GrantCookie {
		client_id: query.client_id.into(),
		state: query.state.into(),
		nonce: cookie_nonce.as_str().into(),
		redirect_uri: redirect_url.as_str().into(),
	};

	let cookie = grant_session_cookie(&cookie_val, &provider)?;

	let session = Session {
		idp_id: Some(idp_id),
		sess_id: Some(sess_id.clone()),
		redirect_url: Some(redirect_url),
		code_verifier: Some(code_verifier),
		query_nonce: Some(query_nonce),
		cookie_nonce: Some(cookie_nonce),
		authorize_expires_at: provider
			.grant_session_duration
			.map(Duration::from_secs)
			.map(timepoint_from_now)
			.transpose()?,

		user_id,
		..Default::default()
	};

	services.oauth.sessions.put(&session).await;

	Ok(sso_login_with_provider::v3::Response {
		location: location.into(),
		cookie: Some(cookie.into()),
	})
}

fn grant_session_cookie(value: &GrantCookie<'_>, provider: &Provider) -> Result<String> {
	let max_age = provider
		.grant_session_duration
		.map(Duration::from_secs)
		.expect("Defaulted to Some value during configure_idp()")
		.try_into()
		.expect("std::time::Duration to time::Duration conversion failure");

	// CookieJar percent-decodes the value on read; encode it so the form survives.
	let cookie = Cookie::build((GRANT_SESSION_COOKIE, to_form_string(value)?))
		.path(grant_session_cookie_path(provider.callback_url.as_ref()))
		.max_age(max_age)
		.same_site(SameSite::None)
		.secure(true)
		.http_only(true)
		.build()
		.encoded()
		.to_string();

	Ok(cookie)
}

/// Path attribute for the grant-session cookie. The set and removal cookies
/// must use the same value: a cookie is only replaced (and thus removed) when
/// its name, domain and path all match (RFC 6265 5.3), and a Set-Cookie
/// without an explicit path defaults to the request-URI's directory.
fn grant_session_cookie_path(callback_url: Option<&Url>) -> &str {
	callback_url.map(Url::path).unwrap_or("/")
}

#[tracing::instrument(
	name = "sso_callback"
	level = "debug",
	skip_all,
	fields(
		%client,
		idp_id = ?body.body.idp_id,
		state = ?body.body.state,
	),
)]
pub(crate) async fn sso_callback_route(
	State(services): State<crate::State>,
	ClientIp(client): ClientIp,
	body: Ruma<sso_callback::unstable::Request>,
) -> Result<Response> {
	let sess_id = body
		.body
		.state
		.as_deref()
		.ok_or_else(|| err!(Request(Forbidden("Missing sess_id in callback."))))?;

	let code = body
		.body
		.code
		.as_deref()
		.ok_or_else(|| err!(Request(Forbidden("Missing code in callback."))))?;

	let session = services
		.oauth
		.sessions
		.get(sess_id)
		.map_err(|_| err!(Request(Forbidden("Invalid state in callback"))));

	let provider = services
		.oauth
		.providers
		.get(body.body.idp_id.as_str());

	let (provider, session) = try_join(provider, session).await.log_err()?;
	let idp_id = provider.id();
	let next_idp_id = chain_next_idp_id(&services, idp_id);

	if session.sess_id.as_deref() != Some(sess_id) {
		return Err!(Request(Unauthorized("Session ID {sess_id:?} not recognized.")));
	}

	if session.idp_id.as_deref() != Some(idp_id) {
		return Err!(Request(Unauthorized(
			"Identity Provider {idp_id:?} session not recognized."
		)));
	}

	if deadline_has_passed(session.authorize_expires_at) {
		return Err!(Request(Unauthorized("Authorization grant session has expired.")));
	}

	if provider.check_cookie || session.user_id.is_some() || next_idp_id.is_some() {
		validate_session_cookie(&body.cookie, &provider, &session, sess_id)?;
	}

	let token_response = services
		.oauth
		.request_token((&provider, &session), code)
		.await?;

	let session = apply_token_response(session, token_response)?;

	let userinfo = services
		.oauth
		.request_userinfo((&provider, &session))
		.await
		.or_else(|error| {
			if provider.brand != "appleoidc" {
				return Err(error);
			}

			debug_warn!(
				?error,
				idp_id = provider.id(),
				"Failed to fetch Apple userinfo endpoint; falling back to id_token claims.",
			);

			decode_apple_userinfo_from_id_token(&session).map_err(|decode_error| {
				debug_warn!(
					?decode_error,
					idp_id = provider.id(),
					"Failed to decode Apple id_token fallback.",
				);
				error
			})
		})?;

	let unique_id = unique_id_sub((&provider, &userinfo.sub))?;

	let complete_identity = async |old_user_id: Option<OwnedUserId>| {
		let session = Session {
			user_info: Some(userinfo.clone()),
			..session
		};

		let user_id = match (session.user_id, old_user_id) {
			| (Some(user_id), ..) | (None, Some(user_id)) => user_id,
			| (None, None) => decide_user_id(&services, &provider, &userinfo, &unique_id).await?,
		};

		let session = Session {
			user_id: Some(user_id.clone()),
			..session
		};

		if !services.users.exists(&user_id).await {
			let origin = match provider.registration {
				| true => "sso",
				// Present in LDAP is an existing user to provision, not a new registration.
				| false if ldap_user_exists(&services, &user_id).await => "ldap",
				| false =>
					return Err!(Request(Forbidden(
						"Registration from this provider is disabled"
					))),
			};

			register_user(&services, &provider, &session, &userinfo, &user_id, origin).await?;
		}

		Ok((session, user_id))
	};

	let (session, user_id, old_sess_id) = services
		.oauth
		.sessions
		.commit_identity_session(&unique_id, complete_identity)
		.await?;

	if let Some(old) = old_sess_id
		.as_deref()
		.filter(is_not_equal_to!(&sess_id))
		&& let Err(error) = services.oauth.sessions.delete(old).await
		&& !error.is_missing()
	{
		warn!(%old, %error, "previous OAuth session was kept");
	}

	if !services.users.is_active_local(&user_id).await {
		return Err!(Request(UserDeactivated("This user has been deactivated.")));
	}

	services.users.locked_check(&user_id).await?;

	let cookie = Cookie::build((GRANT_SESSION_COOKIE, EMPTY))
		.path(grant_session_cookie_path(provider.callback_url.as_ref()))
		.removal()
		.build()
		.to_string()
		.into();

	if let Some(redirect_url) = session
		.redirect_url
		.as_ref()
		.filter(|url| url.scheme() == "uiaa")
	{
		return handle_uiaa(&services, &user_id, cookie, redirect_url)
			.map_ok(|response| RumaResponse(response).into_response())
			.await;
	}

	let redirect_url = session
		.redirect_url
		.ok_or_else(|| err!(Request(InvalidParam("Missing redirect URL in session data"))))?;

	validate_redirect_url(&redirect_url)?;

	if let Some(next_idp_id) = next_idp_id {
		let next = handle_sso_login(
			&services,
			&client,
			next_idp_id,
			redirect_url.into(),
			Some(user_id),
			None,
		)
		.await?;

		return Ok(RumaResponse(next).into_response());
	}

	if redirect_trusted(&services, &redirect_url) {
		let location = finalize_login_redirect(&services, redirect_url, &user_id, Some(idp_id));
		let response = SsoCallbackResponse { location, cookie: Some(cookie) };

		return Ok(RumaResponse(response).into_response());
	}

	confirm_login_redirect(&services, redirect_url, &user_id, &cookie, idp_id)
}

fn validate_session_cookie(
	cookies: &CookieJar,
	provider: &Provider,
	session: &Session,
	sess_id: &str,
) -> Result {
	let client_id = &provider.client_id;
	let cookie: GrantCookie<'_> = cookies
		.get(GRANT_SESSION_COOKIE)
		.map(Cookie::value)
		.map(from_form_str)
		.transpose()?
		.ok_or_else(|| err!(Request(Unauthorized("Missing cookie {GRANT_SESSION_COOKIE:?}"))))?;

	if cookie.client_id.as_ref() != client_id.as_str() {
		return Err!(Request(Unauthorized("Client ID {client_id:?} cookie mismatch.")));
	}

	if Some(cookie.nonce.as_ref()) != session.cookie_nonce.as_deref() {
		return Err!(Request(Unauthorized("Cookie nonce does not match session state.")));
	}

	if cookie.state.as_ref() != sess_id {
		return Err!(Request(Unauthorized("Session ID {sess_id:?} cookie mismatch.")));
	}

	Ok(())
}

fn apply_token_response(session: Session, token: TokenResponse) -> Result<Session> {
	let expires_at = token
		.expires_in
		.map(Duration::from_secs)
		.map(timepoint_from_now)
		.transpose()?;

	let refresh_token_expires_at = token
		.refresh_token_expires_in
		.map(Duration::from_secs)
		.map(timepoint_from_now)
		.transpose()?;

	Ok(Session {
		scope: token.scope,
		token_type: token.token_type,
		access_token: token.access_token,
		id_token: token.id_token,
		expires_at,
		refresh_token: token.refresh_token,
		refresh_token_expires_at,
		..session
	})
}

fn chain_next_idp_id(services: &Services, idp_id: &str) -> Option<String> {
	services
		.config
		.identity_provider
		.values()
		.filter(|idp| idp.default || services.config.authentication.login.single_sso)
		.skip_while(|idp| idp.id() != idp_id)
		.nth(1)
		.map(IdentityProvider::id)
		.map(ToOwned::to_owned)
}

fn finalize_login_redirect(
	services: &Services,
	redirect_url: Url,
	user_id: &UserId,
	provider_id: Option<&str>,
) -> String {
	let login_token = utils::random_string(TOKEN_LENGTH);
	let _login_token_expires_in =
		services
			.users
			.create_login_token_with_provider(user_id, &login_token, provider_id);

	append_login_token(redirect_url, &login_token)
}

fn append_login_token(mut redirect_url: Url, login_token: &str) -> String {
	redirect_url
		.query_pairs_mut()
		.append_pair("loginToken", login_token)
		.finish();

	redirect_url.into()
}

fn validate_redirect_url(redirect_url: &Url) -> Result {
	if !redirect_url.username().is_empty() || redirect_url.password().is_some() {
		return Err!(Request(InvalidParam("redirect_url must not contain userinfo.")));
	}

	if matches!(
		redirect_url.scheme(),
		"javascript" | "vbscript" | "data" | "blob" | "file" | "about"
	) {
		return Err!(Request(InvalidParam("Unsupported redirect_url scheme.")));
	}

	Ok(())
}

fn redirect_trusted(services: &Services, redirect_url: &Url) -> bool {
	let allowed = &services
		.config
		.authentication
		.oidc
		.registration_allowed_redirect_hosts;

	let own_origin = services
		.config
		.well_known
		.client
		.as_ref()
		.filter(|client| matches!(client.scheme(), "http" | "https"))
		.is_some_and(|client| client.origin() == redirect_url.origin());

	own_origin || redirect_allowlisted(allowed, redirect_url.as_str())
}

fn confirm_login_redirect(
	services: &Services,
	redirect_url: Url,
	user_id: &UserId,
	cookie: &str,
	provider_id: &str,
) -> Result<Response> {
	let escape = |value: &str| {
		html_escape(value)
			.replace('{', "&#123;")
			.replace('}', "&#125;")
	};

	let user = escape(user_id.as_str());
	let target = escape(&display_login_target(redirect_url.clone()));
	let location = finalize_login_redirect(services, redirect_url, user_id, Some(provider_id));
	let location = html_escape(&location);
	let html = CONFIRM_HTML
		.replace("{user}", &user)
		.replace("{target}", &target)
		.replace("{location}", &location);

	let cookie = HeaderValue::from_str(cookie)?;
	let headers = [
		(SET_COOKIE, cookie),
		(CACHE_CONTROL, HeaderValue::from_static("no-store")),
		(REFERRER_POLICY, HeaderValue::from_static("no-referrer")),
		(
			CONTENT_SECURITY_POLICY,
			HeaderValue::from_static(
				"default-src 'none'; style-src 'self'; frame-ancestors 'none'; base-uri 'none'",
			),
		),
	];

	Ok((headers, Html(html)).into_response())
}

fn display_login_target(mut target: Url) -> String {
	target.set_query(None);
	target.set_fragment(None);
	target.into()
}

async fn handle_uiaa(
	services: &Services,
	user_id: &UserId,
	cookie: Cow<'static, str>,
	redirect_url: &Url,
) -> Result<sso_callback::unstable::Response> {
	let uiaa_session_id = redirect_url.path();

	// Find the UIAA session by its ID. SECURITY: Ensure the user authenticating via
	// SSO is the owner of the UIAA session
	let (user_id, device_id, mut uiaainfo) = services
		.uiaa
		.get_uiaa_session_by_session_id(uiaa_session_id)
		.await
		.filter(|(db_user_id, ..)| user_id.eq(db_user_id))
		.ok_or_else(|| err!(Request(Forbidden("UIAA session not found."))))?;

	// MSC4312 m.oauth flow → mark OAuth.
	let has_oauth_flow = uiaainfo
		.flows
		.iter()
		.any(|f| f.stages.contains(&AuthType::OAuth));

	// Mark the completed step based on the UIAA session's flow.
	if has_oauth_flow && !uiaainfo.completed.contains(&AuthType::OAuth) {
		// Grant 10-minute bypass for cross-signing key replacement (like Synapse).
		services
			.users
			.allow_cross_signing_replacement(&user_id);

		uiaainfo.completed.push(AuthType::OAuth);
	}

	// Legacy m.login.sso flow → mark Sso.
	let has_sso_flow = uiaainfo
		.flows
		.iter()
		.any(|f| f.stages.contains(&AuthType::Sso));

	if has_sso_flow && !uiaainfo.completed.contains(&AuthType::Sso) {
		uiaainfo.completed.push(AuthType::Sso);
	}

	services
		.uiaa
		.update_uiaa_session(&user_id, &device_id, uiaa_session_id, Some(&uiaainfo));

	// Redirect back to the fallback page to render the success HTML
	let location =
		format!("/_matrix/client/v3/auth/m.login.sso/fallback/web?session={uiaa_session_id}");

	Ok(sso_callback::unstable::Response { location, cookie: Some(cookie) })
}

async fn ldap_user_exists(services: &Services, user_id: &UserId) -> bool {
	cfg!(feature = "ldap")
		&& services.config.ldap.enable
		&& services
			.users
			.search_ldap(user_id)
			.await
			.log_err()
			.is_ok_and(|dns| !dns.is_empty())
}

#[tracing::instrument(
	name = "register",
	level = INFO_SPAN_LEVEL,
	skip_all,
	fields(user_id, userinfo)
)]
async fn register_user(
	services: &Services,
	provider: &Provider,
	session: &Session,
	userinfo: &UserInfo,
	user_id: &UserId,
	origin: &str,
) -> Result {
	debug_info!(%user_id, "Creating new user account...");

	services
		.users
		.full_register(Register {
			user_id: Some(user_id),
			password: Some(PASSWORD_SENTINEL),
			origin: Some(origin),
			displayname: userinfo.name.as_deref(),
			grant_first_user_admin: true,
			..Default::default()
		})
		.await?;

	if let Some(avatar_url) = userinfo
		.avatar_url
		.as_deref()
		.or(userinfo.picture.as_deref())
	{
		set_avatar(services, provider, session, userinfo, user_id, avatar_url)
			.await
			.ok();
	}

	if let Some(email) = userinfo.verified_email(provider.trusted) {
		bind_email(services, user_id, email)
			.await
			.inspect_err(|error| warn!(%user_id, %error, "Skipping registration email binding"))
			.ok();
	}

	let idp_id = provider.id();
	let idp_name = provider
		.name
		.as_deref()
		.unwrap_or(provider.brand.as_str());

	// log in conduit admin channel if a non-guest user registered
	let notice =
		format!("New user \"{user_id}\" registered on this server via {idp_name} ({idp_id})");

	info!("{notice}");
	services.admin.notify(&notice).await;

	Ok(())
}

#[tracing::instrument(level = "debug", skip_all, fields(user_id, avatar_url))]
async fn set_avatar(
	services: &Services,
	_provider: &Provider,
	_session: &Session,
	_userinfo: &UserInfo,
	user_id: &UserId,
	avatar_url: &str,
) -> Result {
	use reqwest::Response;

	let response = services
		.client
		.default
		.get(avatar_url)
		.send()
		.await
		.and_then(Response::error_for_status)?;

	let content_type = response
		.headers()
		.get(CONTENT_TYPE)
		.map(HeaderValue::to_str)
		.flat_ok()
		.map(ToOwned::to_owned);

	let mxc = Mxc {
		server_name: services.globals.server_name(),
		media_id: &utils::random_string(MXC_LENGTH),
	};

	let content_disposition = make_content_disposition(None, content_type.as_deref(), None);
	let limit = services
		.server
		.config
		.network
		.http
		.max_response_size;

	let bytes = read_response_capped(response, limit).await?;
	services
		.media
		.create(&mxc, Some(user_id), Some(&content_disposition), content_type.as_deref(), &bytes)
		.await?;

	let mxc_uri: OwnedMxcUri = mxc.to_string().into();
	services
		.profile
		.set_avatar_url(user_id, Some(&mxc_uri), None)
		.await?;

	Ok(())
}

async fn bind_email(services: &Services, user_id: &UserId, email: &str) -> Result {
	let email = canonicalize_email(email)?;

	bind_new_account_email(services, user_id, &email).await
}

#[tracing::instrument(
	level = "debug",
	ret(level = "debug")
	skip_all,
	fields(user),
)]
async fn decide_user_id(
	services: &Services,
	provider: &Provider,
	userinfo: &UserInfo,
	unique_id: &str,
) -> Result<OwnedUserId> {
	if let Some(user_id) = services
		.oauth
		.sessions
		.find_user_association_pending(provider.id(), userinfo)
	{
		debug_info!(
			provider = ?provider.id(),
			?user_id,
			?userinfo,
			"Matched pending association"
		);

		return Ok(user_id);
	}

	let explicit = |claim: &str| provider.userid_claims.contains(claim);

	let allowed = |claim: &str| provider.userid_claims.is_empty() || explicit(claim);

	let choices = [
		explicit("sub")
			.then_some(userinfo.sub.as_str())
			.map(str::to_lowercase),
		userinfo
			.preferred_username
			.as_deref()
			.map(str::to_lowercase)
			.filter(|_| allowed("preferred_username")),
		userinfo
			.username
			.as_deref()
			.map(str::to_lowercase)
			.filter(|_| allowed("username")),
		userinfo
			.nickname
			.as_deref()
			.map(str::to_lowercase)
			.filter(|_| allowed("nickname")),
		provider
			.brand
			.eq(&"github")
			.then_some(userinfo.sub.as_str())
			.map(str::to_lowercase)
			.filter(|_| allowed("login")),
		userinfo
			.email
			.as_deref()
			.and_then(|email| email.split_once('@'))
			.map(at!(0))
			.map(str::to_lowercase)
			.filter(|_| allowed("email")),
	];

	for choice in choices.into_iter().flatten() {
		if let Some(user_id) = try_user_id(services, provider, &choice, false).await {
			return Ok(user_id);
		}
	}

	let localpart = fallback_localpart(unique_id);
	if let Some(user_id) = try_user_id(services, provider, &localpart, true).await {
		return Ok(user_id);
	}

	Err!(Request(UserInUse("User ID is not available.")))
}

#[tracing::instrument(level = "debug", skip_all, fields(username))]
async fn try_user_id(
	services: &Services,
	provider: &Provider,
	username: &str,
	unique_id: bool,
) -> Option<OwnedUserId> {
	let server_name = services.globals.server_name();
	let user_id = parse_user_id(server_name, username)
		.inspect_err(|e| warn!(?username, "Username invalid: {e}"))
		.ok()?;

	if services
		.config
		.registration
		.forbidden_usernames
		.is_match(username)
	{
		warn!(?username, "Username forbidden.");
		return None;
	}

	if services.users.exists(&user_id).await {
		if provider.trusted {
			info!(
				?username,
				provider = ?provider.brand,
				"Authorizing trusted provider access to existing account."
			);

			return Some(user_id);
		}

		if services
			.users
			.origin(&user_id)
			.await
			.ok()
			.is_none_or(|origin| origin != "sso")
		{
			debug_warn!(?username, "Existing username has non-sso origin.");
			return None;
		}

		if !unique_id {
			debug_warn!(?username, "Username exists.");
			return None;
		}

		// Only an identity without an account reaches its fallback, so an account
		// linked to any identity belongs to another one. An unreadable link counts.
		if services
			.oauth
			.sessions
			.get_sess_id_by_user(&user_id)
			.ready_any(|sess_id| match sess_id {
				| Ok(_) => true,
				| Err(e) if e.is_missing() => false,
				| Err(e) => {
					warn!(?username, error = %e, "Unreadable identity links.");
					true
				},
			})
			.await
		{
			debug_warn!(?username, "Existing username is linked to another identity.");
			return None;
		}
	} else {
		if unique_id && !provider.unique_id_fallbacks {
			debug_warn!(
				?username,
				provider = ?provider.brand,
				"Unique ID fallbacks disabled.",
			);

			return None;
		}

		// Keep the candidate on other errors because account creation retries the gate.
		if services
			.users
			.check_creation(&user_id)
			.await
			.is_err_and(|error| error.kind() == ErrorKind::UserInUse)
		{
			return None;
		}
	}

	Some(user_id)
}

fn parse_user_id(server_name: &ServerName, username: &str) -> Result<OwnedUserId> {
	match UserId::parse_with_server_name(username, server_name) {
		| Err(e) => {
			Err!(Request(InvalidUsername(debug_error!("Username {username} is not valid: {e}"))))
		},
		| Ok(user_id) => match user_id.validate_strict() {
			| Ok(()) => Ok(user_id),
			| Err(e) => Err!(Request(InvalidUsername(debug_error!(
				"Username {username} contains disallowed characters or spaces: {e}"
			)))),
		},
	}
}

#[cfg(test)]
mod tests {
	use reqwest::header::{COOKIE, HeaderMap};
	use serde_json::json;

	use super::*;

	const STATE: &str = "sess";
	const NONCE: &str = "nonce";

	fn apple_session_with_claims(claims: &serde_json::Value) -> Session {
		let payload = b64.encode(serde_json::to_vec(claims).expect("serialize claims"));

		Session {
			id_token: Some(format!("header.{payload}.signature")),
			..Default::default()
		}
	}

	#[test]
	fn decode_apple_userinfo_from_id_token_extracts_expected_claims() {
		let session = apple_session_with_claims(&json!({
			"sub": "apple-user-123",
			"email": "alice@example.com",
			"name": "Alice Example",
			"given_name": "Alice",
			"family_name": "Example"
		}));

		let userinfo =
			decode_apple_userinfo_from_id_token(&session).expect("decode Apple id_token claims");

		assert_eq!(userinfo.sub, "apple-user-123");
		assert_eq!(userinfo.email.as_deref(), Some("alice@example.com"));
		assert_eq!(userinfo.preferred_username.as_deref(), Some("alice"));
		assert_eq!(userinfo.username.as_deref(), Some("alice"));
		assert_eq!(userinfo.name.as_deref(), Some("Alice Example"));
		assert_eq!(userinfo.given_name.as_deref(), Some("Alice"));
		assert_eq!(userinfo.family_name.as_deref(), Some("Example"));
	}

	#[test]
	fn decode_apple_userinfo_from_id_token_requires_sub_claim() {
		let session = apple_session_with_claims(&json!({
			"email": "alice@example.com"
		}));

		let error = decode_apple_userinfo_from_id_token(&session)
			.expect_err("missing sub claim should fail");

		let message = format!("{error}");
		assert!(message.contains("sub claim"), "unexpected error: {message}");
	}

	#[test]
	fn decode_apple_userinfo_from_id_token_requires_id_token() {
		let session = Session::default();

		let error = decode_apple_userinfo_from_id_token(&session)
			.expect_err("missing id_token should fail");

		let message = format!("{error}");
		assert!(message.contains("Missing Apple id_token"), "unexpected error: {message}");
	}

	#[test]
	fn decode_apple_userinfo_from_id_token_rejects_invalid_payload() {
		let session = Session {
			id_token: Some("header.!.signature".to_owned()),
			..Default::default()
		};

		let error = decode_apple_userinfo_from_id_token(&session)
			.expect_err("invalid id_token payload should fail");

		let message = format!("{error}");
		assert!(message.contains("invalid base64"), "unexpected error: {message}");
	}

	#[test]
	fn grant_session_cookie_path_uses_the_callback_path() {
		let callback = Url::parse(
			"https://matrix.example/_matrix/client/unstable/login/sso/callback/tuwunel_abc",
		)
		.expect("valid URL");

		assert_eq!(
			grant_session_cookie_path(Some(&callback)),
			"/_matrix/client/unstable/login/sso/callback/tuwunel_abc"
		);
		assert_eq!(grant_session_cookie_path(None), "/");
	}

	#[test]
	fn grant_session_removal_cookie_path_matches_the_set_cookie_path() {
		let provider = authentik_provider();
		let grant = grant_cookie(&provider, "https://client.example/return");
		let set_cookie = grant_session_cookie(&grant, &provider).expect("grant session cookie");
		let set = Cookie::parse_encoded(set_cookie.as_str()).expect("valid set cookie");
		let removal = Cookie::build((GRANT_SESSION_COOKIE, EMPTY))
			.path(grant_session_cookie_path(provider.callback_url.as_ref()))
			.removal()
			.build();

		assert_eq!(set.path(), removal.path());
		assert_eq!(
			(set.secure(), set.http_only(), set.same_site()),
			(Some(true), Some(true), Some(SameSite::None))
		);

		assert!(
			removal
				.to_string()
				.contains("Path=/_matrix/client/unstable/login/sso/callback/tuwunel_abc"),
			"unexpected removal cookie: {removal}"
		);
	}

	fn authentik_provider() -> Provider {
		serde_json::from_value(json!({
			"brand": "authentik",
			"client_id": "tuwunel_abc",
			"callback_url": "https://matrix.example/_matrix/client/unstable/login/sso/callback/tuwunel_abc",
		}))
		.expect("valid provider")
	}

	fn grant_cookie<'a>(provider: &'a Provider, redirect_uri: &'a str) -> GrantCookie<'a> {
		GrantCookie {
			client_id: provider.client_id.as_str().into(),
			state: STATE.into(),
			nonce: NONCE.into(),
			redirect_uri: redirect_uri.into(),
		}
	}

	#[test]
	fn grant_session_cookie_survives_a_redirect_url_repeating_its_keys() {
		let redirect_uri = "https://client.example/return?next=%2Froom%2B1&state=abc&client_id=x&nonce=y&redirect_uri=z";
		let provider = authentik_provider();
		let grant = grant_cookie(&provider, redirect_uri);
		let session = Session {
			cookie_nonce: Some(NONCE.to_owned()),
			..Default::default()
		};

		let set_cookie = grant_session_cookie(&grant, &provider).expect("grant session cookie");
		let (pair, _) = set_cookie
			.split_once(';')
			.expect("cookie attributes");

		let header = HeaderValue::from_str(pair).expect("valid header value");
		let cookies = CookieJar::from_headers(&HeaderMap::from_iter([(COOKIE, header)]));

		let expected = to_form_string(&grant).expect("serialize");
		let echoed = cookies
			.get(GRANT_SESSION_COOKIE)
			.map(Cookie::value);

		assert_eq!(echoed, Some(expected.as_str()));

		validate_session_cookie(&cookies, &provider, &session, STATE).expect("cookie validates");
	}
}