sqlload 0.63.0

SQL data loading tooling.
//! Snowflake OAuth with PKCE: the authorization URL, the redirect it comes back to, the token endpoint, and keeping an access token fresh.

use base64::Engine;
use base64::engine::general_purpose::URL_SAFE_NO_PAD;
use sha2::{Digest, Sha256};

use crate::auth::_helpers::sign_in::{SignInIo, sign_in};
use crate::auth::_helpers::token_cache::{read_cached, write_cached};
use crate::auth::constants::{DEFAULT_ACCESS_LIFETIME_SECS, OAUTH_REFRESH_MARGIN_SECS};
use crate::auth::errors::TokenError;
use crate::auth::models::{OauthClient, OauthState, OauthTokens, Secret};
use crate::http::errors::ApiError;
use crate::time_text::main::now_ms::now_ms;

/// One sign-in's PKCE verifier, the challenge sent for it, and the `state` that ties the redirect to it.
pub(crate) struct Pkce {
    pub(crate) verifier: String,
    pub(crate) challenge: String,
    pub(crate) state: String,
}

/// The S256 challenge of `verifier` (RFC 7636).
pub(crate) fn challenge(verifier: &str) -> String {
    URL_SAFE_NO_PAD.encode(Sha256::digest(verifier.as_bytes()))
}

/// A fresh verifier (64 URL-safe characters) and state.
pub(crate) fn new_pkce() -> Result<Pkce, ApiError> {
    let mut verifier = [0_u8; 48];
    let mut state = [0_u8; 16];
    getrandom::fill(&mut verifier)
        .and_then(|()| getrandom::fill(&mut state))
        .map_err(|error| ApiError::Auth(format!("no randomness for the sign-in: {error}")))?;
    let verifier = URL_SAFE_NO_PAD.encode(verifier);
    Ok(Pkce {
        challenge: challenge(&verifier),
        verifier,
        state: URL_SAFE_NO_PAD.encode(state),
    })
}

/// The scope a sign-in asks for: a refresh token, and the configured role (a plain name in upper case, as Snowflake stores it; any other name URL-encoded).
pub(crate) fn scope(role: Option<&str>) -> String {
    let Some(role) = role else {
        return "refresh_token".to_owned();
    };
    let plain = role
        .chars()
        .all(|character| character.is_ascii_alphanumeric() || character == '_' || character == '$');
    match plain {
        true => format!("refresh_token session:role:{}", role.to_ascii_uppercase()),
        false => {
            let encoded: String = role
                .bytes()
                .map(
                    |byte| match byte.is_ascii_alphanumeric() || b"-._~".contains(&byte) {
                        true => char::from(byte).to_string(),
                        false => format!("%{byte:02X}"),
                    },
                )
                .collect();
            format!("refresh_token session:role-encoded:{encoded}")
        }
    }
}

/// The authorization endpoint's address for one sign-in.
pub(crate) fn authorize_url(
    client: &OauthClient,
    redirect_uri: &str,
    pkce: &Pkce,
) -> Result<String, ApiError> {
    let mut url = reqwest::Url::parse(&format!("{}/oauth/authorize", client.account_url))
        .map_err(|error| ApiError::Auth(format!("bad account URL: {error}")))?;
    url.query_pairs_mut()
        .append_pair("client_id", &client.client_id)
        .append_pair("response_type", "code")
        .append_pair("redirect_uri", redirect_uri)
        .append_pair("code_challenge", &pkce.challenge)
        .append_pair("code_challenge_method", "S256")
        .append_pair("state", &pkce.state)
        .append_pair("scope", &scope(client.role.as_deref()));
    Ok(url.into())
}

/// The address the sign-in ended on, as a URL: a full URL, or its path and query.
fn redirect_url(redirected: &str) -> Result<reqwest::Url, ApiError> {
    let trimmed = redirected.trim();
    let absolute = match trimmed.starts_with("http://") || trimmed.starts_with("https://") {
        true => trimmed.to_owned(),
        false => format!("http://127.0.0.1/{}", trimmed.trim_start_matches('/')),
    };
    reqwest::Url::parse(&absolute).map_err(|error| {
        ApiError::Auth(format!(
            "that is not the address the sign-in ended on: {error}"
        ))
    })
}

/// `name`'s value in `url`'s query.
fn query_value(url: &reqwest::Url, name: &str) -> Option<String> {
    url.query_pairs()
        .find(|(key, _)| key == name)
        .map(|(_, value)| value.into_owned())
}

/// The `state` the address a sign-in ended on carries, if any.
pub(crate) fn redirect_state(redirected: &str) -> Option<String> {
    match redirect_url(redirected) {
        Ok(url) => query_value(&url, "state"),
        Err(_) => None,
    }
}

/// The authorization code in the address the sign-in redirected to, checked against `state`; `provider`'s own error when it sent one, with control characters dropped so it cannot drive the terminal.
pub(crate) fn redirect_code(
    redirected: &str,
    (state, provider): (&str, &str),
) -> Result<String, ApiError> {
    let url = redirect_url(redirected)?;
    let printable = |text: String| -> String {
        text.chars()
            .filter(|character| !character.is_control())
            .collect()
    };
    if let Some(error) = query_value(&url, "error") {
        let description = query_value(&url, "error_description").unwrap_or_default();
        return Err(ApiError::Auth(format!(
            "{provider} refused the sign-in: {} {}",
            printable(error),
            printable(description)
        )));
    }
    if query_value(&url, "state").as_deref() != Some(state) {
        return Err(ApiError::Auth(
            "the sign-in came back for another request (state does not match); sign in again"
                .to_owned(),
        ));
    }
    query_value(&url, "code").ok_or_else(|| {
        ApiError::Auth("the address the sign-in ended on has no code= in it".to_owned())
    })
}

/// Send one grant to the token endpoint (the client's ID and any secret in the body); the tokens, checked to belong to the configured user.
pub(crate) async fn token_request(
    client: &OauthClient,
    grant: &[(&str, &str)],
) -> Result<OauthTokens, TokenError> {
    let mut form: Vec<(&str, &str)> = grant.to_vec();
    form.push(("client_id", &client.client_id));
    if let Some(secret) = &client.client_secret {
        form.push(("client_secret", secret.expose()));
    }
    let response = client
        .http
        .post(format!("{}/oauth/token-request", client.account_url))
        .form(&form)
        .send()
        .await
        .map_err(|error| TokenError::Failed(error.into()))?;
    let status = response.status();
    let text = response
        .text()
        .await
        .map_err(|error| TokenError::Failed(error.into()))?;
    let body: serde_json::Value = match serde_json::from_str(&text) {
        Ok(body) => body,
        Err(_) => serde_json::Value::Null,
    };
    if !status.is_success() {
        let reason = format!(
            "{} {}",
            body["error"].as_str().unwrap_or(status.as_str()),
            body["message"].as_str().unwrap_or(&text)
        );
        return Err(match status.as_u16() {
            400 | 401 => TokenError::Refused(reason),
            _ => TokenError::Failed(ApiError::Auth(format!(
                "the Snowflake token endpoint failed: {reason}"
            ))),
        });
    }
    tokens_from(client, &body).map_err(|reason| TokenError::Failed(ApiError::Auth(reason)))
}

/// The tokens in a token endpoint answer, or why they cannot be used.
fn tokens_from(client: &OauthClient, body: &serde_json::Value) -> Result<OauthTokens, String> {
    let access_token = body["access_token"]
        .as_str()
        .ok_or("the Snowflake token endpoint sent no access_token")?;
    if let Some(username) = body["username"].as_str()
        && !username.eq_ignore_ascii_case(&client.user)
    {
        return Err(format!(
            "signed in to Snowflake as {username}, but this connection's user is {}; sign in as {} instead",
            client.user, client.user
        ));
    }
    let now = now_secs();
    Ok(OauthTokens {
        access_token: Secret(access_token.to_owned()),
        renew_after: renew_after(now, body["expires_in"].as_u64()),
        refresh_token: body["refresh_token"]
            .as_str()
            .map(|token| Secret(token.to_owned())),
        refresh_expires_at: body["refresh_token_expires_in"]
            .as_u64()
            .map(|seconds| now.saturating_add(seconds)),
    })
}

/// The access token to send now. In order: the one held, while its renewal time has not come; newer tokens another connection or process cached; one renewed with the refresh token (keeping the refresh token when Snowflake sends no new one); one from a new browser sign-in. Every new token is cached. A refused refresh first looks for a refresh token another holder rotated it to meanwhile, and only then signs in; a failed sign-in fails every later request of the run that the cache cannot serve, so nobody is asked twice.
pub(crate) async fn fresh_access_token(
    client: &OauthClient,
    state: &tokio::sync::Mutex<OauthState>,
    io: &SignInIo,
) -> Result<String, ApiError> {
    let mut held = state.lock().await;
    let now = now_secs();
    if let Some(access) = usable_access(held.tokens.as_ref(), now) {
        return Ok(access);
    }
    let newer = read_cached(client).filter(|cached| {
        held.tokens
            .as_ref()
            .is_none_or(|current| cached.renew_after > current.renew_after)
    });
    if newer.is_some() {
        held.tokens = newer;
    }
    if let Some(access) = usable_access(held.tokens.as_ref(), now) {
        return Ok(access);
    }
    if let Some(failure) = &held.failure {
        return Err(ApiError::Auth(failure.clone()));
    }
    let mut refreshed = refresh(client, held.tokens.as_ref(), now).await?;
    let sent = held
        .tokens
        .as_ref()
        .and_then(|current| current.refresh_token.clone());
    let rotated = read_cached(client).filter(|cached| cached.refresh_token != sent);
    if let Some(cached) = rotated.filter(|_| refreshed.is_none()) {
        if let Some(access) = usable_access(Some(&cached), now) {
            held.tokens = Some(cached);
            return Ok(access);
        }
        refreshed = refresh(client, Some(&cached), now).await?;
    }
    let renewed = match refreshed {
        Some(renewed) => renewed,
        None => match sign_in(client, io).await {
            Ok(signed_in) => signed_in,
            Err(error) => {
                held.failure = Some(error.to_string());
                return Err(error);
            }
        },
    };
    if let Err(error) = write_cached(client, &renewed) {
        tracing::warn!(%error, "cannot cache the Snowflake sign-in; the next run signs in again");
    }
    let access = renewed.access_token.expose().to_owned();
    held.tokens = Some(renewed);
    Ok(access)
}

/// The access token of `tokens` while its renewal time has not come.
fn usable_access(tokens: Option<&OauthTokens>, now: u64) -> Option<String> {
    tokens
        .filter(|current| current.renew_after > now)
        .map(|current| current.access_token.expose().to_owned())
}

/// Tokens renewed with the refresh token of `current`, keeping it when Snowflake sends no new one; `None` when there is no unexpired refresh token or Snowflake refused it.
async fn refresh(
    client: &OauthClient,
    current: Option<&OauthTokens>,
    now: u64,
) -> Result<Option<OauthTokens>, ApiError> {
    let Some((refresh, expires)) = current.and_then(|current| {
        current
            .refresh_token
            .clone()
            .filter(|_| {
                current
                    .refresh_expires_at
                    .is_none_or(|expires| expires > now)
            })
            .map(|token| (token, current.refresh_expires_at))
    }) else {
        return Ok(None);
    };
    let grant = [
        ("grant_type", "refresh_token"),
        ("refresh_token", refresh.expose()),
    ];
    match token_request(client, &grant).await {
        Ok(mut renewed) => {
            if renewed.refresh_token.is_none() {
                renewed.refresh_token = Some(refresh);
                renewed.refresh_expires_at = expires;
            }
            Ok(Some(renewed))
        }
        Err(TokenError::Refused(reason)) => {
            tracing::info!(%reason, "Snowflake refused the cached refresh token; signing in again");
            Ok(None)
        }
        Err(TokenError::Failed(error)) => Err(error),
    }
}

/// When to renew an access token issued at `now` for `lifetime` seconds (Snowflake's default of 600 when not given): a minute before it expires, or halfway through for a token of under two minutes.
pub(crate) fn renew_after(now: u64, lifetime: Option<u64>) -> u64 {
    let lifetime = lifetime.unwrap_or(DEFAULT_ACCESS_LIFETIME_SECS);
    now.saturating_add(lifetime - (lifetime / 2).min(OAUTH_REFRESH_MARGIN_SECS))
}

/// Now, in Unix seconds.
pub(crate) fn now_secs() -> u64 {
    u64::try_from(now_ms() / 1000).unwrap_or(0)
}