Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

10.4 KB
Raw Blame
//! Signed, expiring OAuth `state` for account-link flows.
//!
//! `/link/gmail`, `/link/github`, and `/link/outlook` send the browser to a
//! provider's consent screen with a `state` parameter that comes back, as
//! sent, to `/oauth2/{provider}/callback`. The callback uses it to find the
//! pending `in_progress_user_link` row and to decide where to redirect, so a
//! forged `state` could point another user's consent at an attacker's pending
//! link or redirect the browser elsewhere. The state is therefore signed, and
//! the callback refuses anything it cannot verify.
//!
//! The token is `base64url(payload).base64url(signature)`, without padding,
//! where the signature is HMAC-SHA256 over the encoded payload. This mirrors
//! the GitHub App installation state in the `github` crate.
//!
//! The same key signs the `state` of a Microsoft tenant-wide admin-consent
//! request ([`AdminConsentState`]), which returns to the same callback.

use std::sync::Arc;

use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
use hmac::{Hmac, Mac};
use serde::{Deserialize, Serialize};
use sha2::Sha256;
use uuid::Uuid;
use zeroize::Zeroizing;

#[cfg(test)]
mod test;

type HmacSha256 = Hmac<Sha256>;

/// How long a signed state stays valid. Consent takes minutes, and a pending
/// link is only kept for a day, so an hour leaves room for a slow user without
/// letting a leaked authorization URL stay live indefinitely.
pub(crate) const ACCOUNT_LINK_STATE_TTL: chrono::Duration = chrono::Duration::hours(1);

/// HMAC-SHA256 keys shorter than the digest weaken the construction (RFC 2104
/// recommends at least the output length).
const MIN_SECRET_LENGTH: usize = 32;

/// The callback a state was issued for. The same path segment the callback
/// router receives, so a state issued for one provider cannot complete
/// another's callback.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub(crate) enum LinkProvider {
    /// Gmail (and Google Calendar) linking.
    Google,
    /// GitHub account linking.
    Github,
    /// Microsoft Outlook linking.
    Microsoft,
}

impl LinkProvider {
    /// The `{provider}` segment of `/oauth2/{provider}/callback`.
    pub(crate) fn as_str(self) -> &'static str {
        match self {
            Self::Google => "google",
            Self::Github => "github",
            Self::Microsoft => "microsoft",
        }
    }
}

impl std::fmt::Display for LinkProvider {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// Authenticated context carried through an account-link OAuth flow.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub(crate) struct AccountLinkState {
    /// Which callback may complete this state.
    pub provider: LinkProvider,
    /// The FusionAuth identity provider that will hold the resulting grant.
    pub identity_provider_id: String,
    /// The pending `in_progress_user_link` row this consent completes.
    pub link_id: Uuid,
    /// The FusionAuth user who began the link. The callback refuses to
    /// complete a link whose pending row belongs to anyone else.
    pub fusion_user_id: Uuid,
    /// Where to send the browser once the link completes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub original_url: Option<String>,
    /// Expiration time in Unix seconds.
    pub exp: i64,
}

impl AccountLinkState {
    /// A state for a link that `fusion_user_id` just began, expiring
    /// [`ACCOUNT_LINK_STATE_TTL`] from now.
    pub(crate) fn new(
        provider: LinkProvider,
        identity_provider_id: String,
        link_id: Uuid,
        fusion_user_id: Uuid,
        original_url: Option<String>,
    ) -> Self {
        Self {
            provider,
            identity_provider_id,
            link_id,
            fusion_user_id,
            original_url,
            exp: (chrono::Utc::now() + ACCOUNT_LINK_STATE_TTL).timestamp(),
        }
    }
}

/// Signed `state` for a tenant-wide admin-consent request.
///
/// An administrator completes this flow from a copied link, often days later
/// and from a different device, so it names no pending link or user and does
/// not expire. The callback only redirects to the allow-listed `original_url`
/// with the outcome, which is all a replay could do. The required `kind`
/// field is what keeps an [`AccountLinkState`] token, which has none, from
/// verifying as this type.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub(crate) struct AdminConsentState {
    /// The payload discriminator; always [`AdminConsentKind::AdminConsent`].
    pub kind: AdminConsentKind,
    /// Which callback may complete this state.
    pub provider: LinkProvider,
    /// Where to send the browser once the administrator has answered.
    pub original_url: String,
}

/// The `kind` of an [`AdminConsentState`] payload.
///
/// A one-variant enum rather than a `#[serde(tag)]` on the struct: serde
/// writes a struct tag but does not check it when deserializing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub(crate) enum AdminConsentKind {
    AdminConsent,
}

/// What a signed `state` token verified as.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(untagged)]
pub(crate) enum SignedState {
    /// A tenant-wide admin-consent request. Tried first: its `kind` field is
    /// required, so an account-link payload never matches.
    AdminConsent(AdminConsentState),
    /// A pending account link.
    AccountLink(AccountLinkState),
}

/// An error encountered while signing or verifying account-link state.
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
pub(crate) enum AccountLinkStateError {
    /// The payload could not be serialized.
    #[error("account-link state payload could not be serialized")]
    Serialization,
    /// The token does not have the expected encoding or payload shape.
    #[error("account-link state token is malformed")]
    Malformed,
    /// The token's signature is invalid.
    #[error("account-link state signature is invalid")]
    InvalidSignature,
    /// The token is authentic but has reached its expiration time. Carries
    /// the pending link it named so the caller can release that row.
    #[error("account-link state token has expired")]
    Expired {
        /// The pending link the expired state was issued for.
        link_id: Uuid,
    },
}

/// The HMAC key that signs account-link state. Never printed.
#[derive(Clone)]
pub(crate) struct AccountLinkStateKey(Arc<Zeroizing<Vec<u8>>>);

impl AccountLinkStateKey {
    /// Wraps the configured secret.
    ///
    /// # Errors
    /// If the secret is blank or shorter than 32 bytes. A short key is a
    /// configuration mistake the service should refuse at startup.
    pub(crate) fn new(secret: &str) -> anyhow::Result<Self> {
        let secret = secret.trim();
        if secret.len() < MIN_SECRET_LENGTH {
            anyhow::bail!(
                "ACCOUNT_LINK_STATE_SECRET must be at least {MIN_SECRET_LENGTH} bytes of random data"
            );
        }
        Ok(Self(Arc::new(Zeroizing::new(secret.as_bytes().to_vec()))))
    }

    fn as_bytes(&self) -> &[u8] {
        &self.0
    }
}

impl std::fmt::Debug for AccountLinkStateKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("AccountLinkStateKey(<redacted>)")
    }
}

/// Serialize and sign an account-link state.
pub(crate) fn sign_account_link_state(
    state: &AccountLinkState,
    key: &AccountLinkStateKey,
) -> Result<String, AccountLinkStateError> {
    sign_payload(state, key)
}

/// Serialize and sign an admin-consent state.
pub(crate) fn sign_admin_consent_state(
    state: &AdminConsentState,
    key: &AccountLinkStateKey,
) -> Result<String, AccountLinkStateError> {
    sign_payload(state, key)
}

fn sign_payload<T: Serialize>(
    payload: &T,
    key: &AccountLinkStateKey,
) -> Result<String, AccountLinkStateError> {
    let json = serde_json::to_vec(payload).map_err(|_| AccountLinkStateError::Serialization)?;
    let encoded_payload = URL_SAFE_NO_PAD.encode(json);
    let signature = signature_for(encoded_payload.as_bytes(), key);

    Ok(format!(
        "{encoded_payload}.{}",
        URL_SAFE_NO_PAD.encode(signature)
    ))
}

/// Verify and deserialize a signed `state` token of either kind.
///
/// `current_timestamp` is expressed in Unix seconds. An account-link token is
/// expired when the current timestamp is equal to or later than its `exp`
/// value; admin-consent tokens do not expire (see [`AdminConsentState`]). The
/// signature is checked before the payload is decoded, so nothing in a
/// rejected token is ever interpreted.
pub(crate) fn verify_signed_state(
    token: &str,
    key: &AccountLinkStateKey,
    current_timestamp: i64,
) -> Result<SignedState, AccountLinkStateError> {
    let (encoded_payload, encoded_signature) = split_token(token)?;
    let signature = URL_SAFE_NO_PAD
        .decode(encoded_signature)
        .map_err(|_| AccountLinkStateError::Malformed)?;

    let mut verifier =
        HmacSha256::new_from_slice(key.as_bytes()).expect("HMAC-SHA256 accepts keys of any length");
    verifier.update(encoded_payload.as_bytes());
    verifier
        .verify_slice(&signature)
        .map_err(|_| AccountLinkStateError::InvalidSignature)?;

    let json = URL_SAFE_NO_PAD
        .decode(encoded_payload)
        .map_err(|_| AccountLinkStateError::Malformed)?;
    let state: SignedState =
        serde_json::from_slice(&json).map_err(|_| AccountLinkStateError::Malformed)?;

    if let SignedState::AccountLink(link) = &state
        && current_timestamp >= link.exp
    {
        return Err(AccountLinkStateError::Expired {
            link_id: link.link_id,
        });
    }

    Ok(state)
}

fn split_token(token: &str) -> Result<(&str, &str), AccountLinkStateError> {
    let mut segments = token.split('.');
    let payload = segments.next().filter(|segment| !segment.is_empty());
    let signature = segments.next().filter(|segment| !segment.is_empty());

    match (payload, signature, segments.next()) {
        (Some(payload), Some(signature), None) => Ok((payload, signature)),
        _ => Err(AccountLinkStateError::Malformed),
    }
}

fn signature_for(payload: &[u8], key: &AccountLinkStateKey) -> [u8; 32] {
    let mut signer =
        HmacSha256::new_from_slice(key.as_bytes()).expect("HMAC-SHA256 accepts keys of any length");
    signer.update(payload);
    signer.finalize().into_bytes().into()
}