Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Owner-bound Microsoft linking and serialized refresh-token rotation.
use chrono::{DateTime, Duration, Utc};
use feature_flags::FeatureFlags;
use macro_user_id::user_id::MacroUserIdStr;
use std::{
collections::HashMap,
sync::{Arc, Mutex},
};
use uuid::Uuid;
use zeroize::Zeroizing;
pub mod token;
use token::{EncryptedMicrosoftToken, MicrosoftRefreshToken, MicrosoftTokenCipher};
#[cfg(test)]
mod test;
/// PostHog flag that admits a user to new Outlook connections when the
/// deployment switch is on. Reconnecting an existing inbox never reads it.
pub const OUTLOOK_FLAG: &str = "enable-outlook";
/// The [`OUTLOOK_FLAG`] decision for one user, recorded as `outlook.flag`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, strum::IntoStaticStr)]
#[strum(serialize_all = "snake_case")]
pub enum OutlookFlag {
On,
Off,
/// The flags could not be loaded; new connections stay closed.
Error,
/// No flag provider is configured (local and tests); the switch decides.
Unconfigured,
}
impl OutlookFlag {
fn admits(self) -> bool {
matches!(self, Self::On | Self::Unconfigured)
}
}
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum MicrosoftAuthError {
#[error("a professional subscription is required to link an additional inbox")]
PaymentRequired,
#[error("Microsoft linking is not configured")]
NotConfigured,
#[error("this Microsoft linking attempt has expired or was already used")]
InvalidAttempt,
#[error("too many Microsoft linking attempts")]
TooManyAttempts,
#[error("Microsoft did not grant all required mailbox permissions")]
MissingPermissions,
#[error("Microsoft authorization requires reconnecting")]
ReauthorizationRequired,
#[error("Microsoft authorization is temporarily busy; retry shortly")]
Busy,
#[error("Microsoft authorization is temporarily unavailable")]
Unavailable,
#[error("the Microsoft mailbox identity could not be verified")]
InvalidIdentity,
#[error("this mailbox is already connected to another owner")]
OwnershipConflict,
}
/// Secret state is deliberately neither Debug nor serializable to the client.
pub struct LinkAttempt {
pub id: Uuid,
pub owner: Uuid,
pub identity_provider_id: String,
pub redirect_uri: String,
pub return_uri: Option<String>,
pub verifier: Zeroizing<String>,
pub nonce: String,
pub calendar_requested: bool,
pub expires_at: DateTime<Utc>,
}
pub struct LinkStart {
pub id: Uuid,
pub authorization_url: String,
}
/// The provider adapter verifies signature, issuer, audience, nonce and Graph /me.
pub struct VerifiedGrant {
pub tenant_id: String,
pub subject_id: String,
pub mailbox_id: String,
pub email: String,
pub scopes: Vec<String>,
pub refresh_token: MicrosoftRefreshToken,
}
pub struct StoredGrant {
pub scopes: Vec<String>,
pub id: Uuid,
pub generation: i64,
pub revision: i64,
pub owner: String,
pub email: String,
pub envelope: EncryptedMicrosoftToken,
}
/// Verified, non-secret mailbox binding for the email domain's initializer.
/// The initiating principal must match the completed OAuth attempt.
#[derive(Debug, Clone, serde::Serialize)]
pub struct CompletedMicrosoftGrant {
pub calendar_requested: bool,
pub grant_id: Uuid,
pub generation: i64,
pub owner: Uuid,
pub email: String,
pub tenant_id: String,
pub mailbox_id: String,
pub scopes: Vec<String>,
}
pub struct RefreshedGrant {
pub access_token: Zeroizing<String>,
pub refresh_token: Option<MicrosoftRefreshToken>,
pub expires_in: u64,
pub scopes: Vec<String>,
}
/// Token and the permissions observed for the same grant acquisition.
pub struct MicrosoftAccessGrant {
token: Zeroizing<String>,
pub scopes: Vec<String>,
/// Served from this process's token cache rather than a refresh.
pub cached: bool,
}
impl MicrosoftAccessGrant {
pub fn as_str(&self) -> &str {
self.token.as_str()
}
}
#[cfg_attr(test, mockall::automock)]
#[async_trait::async_trait]
pub trait MicrosoftGrantRepository: Send + Sync {
/// Expire completed/abandoned link attempts, then collect unbound grants.
/// Keep every grant referenced by a mailbox, custodian, or remaining attempt.
async fn collect_expired_grants(
&self,
older_than: DateTime<Utc>,
limit: i64,
) -> Result<u64, MicrosoftAuthError>;
async fn connection_facts(
&self,
owner: Uuid,
reconnect: Option<Uuid>,
) -> Result<email::domain::inbox_entitlement::InboxConnectionFacts, MicrosoftAuthError>;
/// Delete only the exact released grant when no active mailbox binds it.
/// Delayed work cannot revoke a later reconnect or a current custodian.
async fn revoke_released_grant(
&self,
id: Uuid,
generation: i64,
owner: &str,
) -> Result<(), MicrosoftAuthError>;
/// Enforces the pending-attempt cap atomically for this owner.
async fn begin_link(&self, attempt: &LinkAttempt) -> Result<(), MicrosoftAuthError>;
/// Atomically claims an unexpired, provider-bound attempt exactly once.
async fn claim_link(&self, id: Uuid) -> Result<LinkAttempt, MicrosoftAuthError>;
async fn abandon_link(&self, id: Uuid) -> Result<(), MicrosoftAuthError>;
async fn completed_grant(
&self,
attempt: Uuid,
owner: Uuid,
) -> Result<CompletedMicrosoftGrant, MicrosoftAuthError>;
/// Persists the grant and marks the same owner's pending link consumable in
/// one transaction. Reconnecting increments generation and fences rotation.
async fn complete_link(
&self,
attempt: &LinkAttempt,
identity: &VerifiedGrant,
envelope: &EncryptedMicrosoftToken,
grant_id: Uuid,
) -> Result<(), MicrosoftAuthError>;
/// Resolves an active Outlook link's exact grant generation; never accepts a
/// caller-supplied email address as proof of mailbox ownership.
async fn active_grant(
&self,
link_id: Uuid,
generation: i64,
sync_generation: i64,
) -> Result<StoredGrant, MicrosoftAuthError>;
/// Only the frozen exact binding may obtain credentials for disconnect cleanup.
async fn disconnecting_grant(
&self,
link_id: Uuid,
generation: i64,
sync_generation: i64,
) -> Result<StoredGrant, MicrosoftAuthError>;
async fn acquire_refresh(
&self,
grant: &StoredGrant,
lease: Uuid,
) -> Result<bool, MicrosoftAuthError>;
/// Compare-and-swap includes generation, revision and lease owner.
async fn finish_refresh(
&self,
grant: &StoredGrant,
lease: Uuid,
envelope: &EncryptedMicrosoftToken,
scopes: &[String],
) -> Result<bool, MicrosoftAuthError>;
async fn release_refresh(
&self,
grant: &StoredGrant,
lease: Uuid,
revoke: bool,
) -> Result<(), MicrosoftAuthError>;
}
#[cfg_attr(test, mockall::automock)]
#[async_trait::async_trait]
pub trait MicrosoftIdentityProvider: Send + Sync {
async fn identity_provider_id(&self) -> Result<String, MicrosoftAuthError>;
fn authorize(&self, attempt: &LinkAttempt) -> Result<String, MicrosoftAuthError>;
/// The tenant-wide consent page an administrator completes when their
/// directory refuses user consent; Microsoft returns to `redirect_uri`,
/// which then sends the browser on to `return_uri`.
fn admin_consent_url(
&self,
redirect_uri: &str,
return_uri: &str,
calendar: bool,
) -> Result<String, MicrosoftAuthError>;
async fn exchange(
&self,
attempt: &LinkAttempt,
code: &str,
) -> Result<VerifiedGrant, MicrosoftAuthError>;
async fn refresh(
&self,
token: &MicrosoftRefreshToken,
) -> Result<RefreshedGrant, MicrosoftAuthError>;
}
#[async_trait::async_trait]
pub trait MicrosoftAuth: Send + Sync {
/// Whether `user` may start a new Outlook connection: the deployment
/// switch, then their [`OUTLOOK_FLAG`]. Records `outlook.flag` on the
/// current span when the flag is read.
async fn new_connections_enabled(&self, user: &MacroUserIdStr<'_>) -> bool;
/// Where an administrator grants Macro's delegated permissions for their
/// whole directory, for users whose consent attempt needs admin approval.
fn admin_consent_url(
&self,
redirect_uri: &str,
return_uri: &str,
calendar: bool,
) -> Result<String, MicrosoftAuthError>;
async fn revoke_released_grant(
&self,
id: Uuid,
generation: i64,
owner: &str,
) -> Result<(), MicrosoftAuthError>;
async fn completed_grant(
&self,
attempt: Uuid,
owner: Uuid,
) -> Result<CompletedMicrosoftGrant, MicrosoftAuthError>;
/// A new connection needs [`Self::new_connections_enabled`] for `user`;
/// reconnecting an inbox `owner` can already access does not.
async fn start_link(
&self,
owner: Uuid,
user: &MacroUserIdStr<'_>,
redirect_uri: String,
return_uri: Option<String>,
calendar_requested: bool,
reconnect: Option<Uuid>,
) -> Result<LinkStart, MicrosoftAuthError>;
/// Return destinations come from server state, never the callback's mutable state.
async fn complete_link(
&self,
id: Uuid,
identity_provider_id: &str,
code: &str,
) -> Result<Option<String>, MicrosoftAuthError>;
async fn disconnect_token(
&self,
link_id: Uuid,
generation: i64,
sync_generation: i64,
) -> Result<MicrosoftAccessGrant, MicrosoftAuthError>;
async fn access_token(
&self,
link_id: Uuid,
generation: i64,
sync_generation: i64,
force_refresh: bool,
) -> Result<MicrosoftAccessGrant, MicrosoftAuthError>;
}
/// Credential retention must not depend on the owner signing in again.
pub async fn collect_expired_grants(
repository: &impl MicrosoftGrantRepository,
) -> Result<u64, MicrosoftAuthError> {
const BATCH_SIZE: i64 = 256;
repository
.collect_expired_grants(Utc::now() - Duration::hours(24), BATCH_SIZE)
.await
}
struct CachedToken {
value: Zeroizing<String>,
scopes: Vec<String>,
expires_at: DateTime<Utc>,
}
pub struct MicrosoftAuthService<R, P, F> {
connections_enabled: bool,
/// `None` when no flag provider is configured; see [`OutlookFlag::Unconfigured`].
feature_flags: Option<F>,
repo: R,
provider: P,
cipher: Arc<dyn MicrosoftTokenCipher>,
cache: Mutex<HashMap<(Uuid, i64), CachedToken>>,
}
impl<R, P, F> MicrosoftAuthService<R, P, F> {
pub fn with_connections_enabled(mut self, enabled: bool) -> Self {
self.connections_enabled = enabled;
self
}
pub fn with_feature_flags(mut self, feature_flags: Option<F>) -> Self {
self.feature_flags = feature_flags;
self
}
pub fn new(repo: R, provider: P, cipher: Arc<dyn MicrosoftTokenCipher>) -> Self {
Self {
repo,
provider,
cipher,
cache: Mutex::new(HashMap::new()),
connections_enabled: true,
feature_flags: None,
}
}
}
impl<R, P, F: FeatureFlags> MicrosoftAuthService<R, P, F> {
async fn outlook_flag(&self, user: &MacroUserIdStr<'_>) -> OutlookFlag {
let flag = match &self.feature_flags {
None => OutlookFlag::Unconfigured,
Some(feature_flags) => match feature_flags.load(user).await {
Ok(flags) if flags.is_enabled(OUTLOOK_FLAG) => OutlookFlag::On,
Ok(_) => OutlookFlag::Off,
Err(error) => {
tracing::warn!(
error = ?error,
flag = OUTLOOK_FLAG,
"feature flags unavailable; new Outlook connections stay closed"
);
OutlookFlag::Error
}
},
};
tracing::Span::current().record("outlook.flag", <&str>::from(flag));
flag
}
async fn admits_new_connection(&self, user: &MacroUserIdStr<'_>) -> bool {
self.connections_enabled && self.outlook_flag(user).await.admits()
}
}
/// Persist one spelling for Graph capabilities so every consumer sees the same grant.
fn normalize_scopes(scopes: Vec<String>) -> Vec<String> {
const KNOWN: &[&str] = &[
"User.Read",
"Mail.ReadWrite",
"Mail.Send",
"Contacts.Read",
"Calendars.ReadWrite",
"MailboxSettings.ReadWrite",
"openid",
"profile",
"email",
"offline_access",
];
let mut normalized = scopes
.into_iter()
.map(|scope| {
let name = scope.rsplit('/').next().unwrap_or(&scope);
KNOWN
.iter()
.find(|known| known.eq_ignore_ascii_case(name))
.map_or(scope.clone(), |known| (*known).to_owned())
})
.collect::<Vec<_>>();
normalized.sort();
normalized.dedup();
normalized
}
fn has_required_scopes(scopes: &[String]) -> bool {
["user.read", "mail.readwrite", "mail.send"]
.iter()
.all(|required| {
scopes.iter().any(|scope| {
scope
.rsplit('/')
.next()
.is_some_and(|scope| scope.eq_ignore_ascii_case(required))
})
})
}
#[async_trait::async_trait]
impl<R: MicrosoftGrantRepository, P: MicrosoftIdentityProvider, F: FeatureFlags> MicrosoftAuth
for MicrosoftAuthService<R, P, F>
{
async fn new_connections_enabled(&self, user: &MacroUserIdStr<'_>) -> bool {
self.admits_new_connection(user).await
}
fn admin_consent_url(
&self,
redirect_uri: &str,
return_uri: &str,
calendar: bool,
) -> Result<String, MicrosoftAuthError> {
self.provider
.admin_consent_url(redirect_uri, return_uri, calendar)
}
async fn revoke_released_grant(
&self,
id: Uuid,
generation: i64,
owner: &str,
) -> Result<(), MicrosoftAuthError> {
self.repo
.revoke_released_grant(id, generation, owner)
.await?;
self.cache
.lock()
.map_err(|_| MicrosoftAuthError::Unavailable)?
.remove(&(id, generation));
Ok(())
}
async fn completed_grant(
&self,
attempt: Uuid,
owner: Uuid,
) -> Result<CompletedMicrosoftGrant, MicrosoftAuthError> {
let grant = self.repo.completed_grant(attempt, owner).await?;
if grant.owner != owner {
return Err(MicrosoftAuthError::InvalidAttempt);
}
if !has_required_scopes(&grant.scopes) {
return Err(MicrosoftAuthError::MissingPermissions);
}
Ok(grant)
}
async fn start_link(
&self,
owner: Uuid,
user: &MacroUserIdStr<'_>,
redirect_uri: String,
return_uri: Option<String>,
calendar_requested: bool,
reconnect: Option<Uuid>,
) -> Result<LinkStart, MicrosoftAuthError> {
let facts = self.repo.connection_facts(owner, reconnect).await?;
if !facts.reconnecting && !self.admits_new_connection(user).await {
return Err(MicrosoftAuthError::NotConfigured);
}
if !facts.permits_connection() {
return Err(MicrosoftAuthError::PaymentRequired);
}
use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
// OS-backed randomness; no caller-controlled OAuth secrets.
let verifier = URL_SAFE_NO_PAD.encode(rand::random::<[u8; 32]>());
let nonce = URL_SAFE_NO_PAD.encode(rand::random::<[u8; 32]>());
let attempt = LinkAttempt {
id: macro_uuid::generate_uuid_v7(),
owner,
identity_provider_id: self.provider.identity_provider_id().await?,
redirect_uri,
return_uri,
verifier: Zeroizing::new(verifier),
nonce,
calendar_requested,
expires_at: Utc::now() + Duration::minutes(10),
};
let authorization_url = self.provider.authorize(&attempt)?;
self.repo.begin_link(&attempt).await?;
Ok(LinkStart {
id: attempt.id,
authorization_url,
})
}
async fn complete_link(
&self,
id: Uuid,
identity_provider_id: &str,
code: &str,
) -> Result<Option<String>, MicrosoftAuthError> {
let attempt = self.repo.claim_link(id).await?;
let result = async {
if attempt.identity_provider_id != identity_provider_id {
return Err(MicrosoftAuthError::InvalidAttempt);
}
let mut identity = self.provider.exchange(&attempt, code).await?;
identity.scopes = normalize_scopes(identity.scopes);
if !has_required_scopes(&identity.scopes) {
return Err(MicrosoftAuthError::MissingPermissions);
}
if identity.subject_id.is_empty()
|| identity.mailbox_id.is_empty()
|| identity.tenant_id.is_empty()
|| email_validator::normalize_email(&identity.email).is_none()
{
return Err(MicrosoftAuthError::InvalidIdentity);
}
let owner = attempt.owner.to_string();
// The owner is always the principal that initiated this attempt.
let envelope = self
.cipher
.encrypt(
&owner,
&identity.email,
MicrosoftRefreshToken::new(identity.refresh_token.as_str().to_owned()),
)
.await
.map_err(|_| MicrosoftAuthError::Unavailable)?;
self.repo
.complete_link(
&attempt,
&identity,
&envelope,
macro_uuid::generate_uuid_v7(),
)
.await?;
Ok(attempt.return_uri.clone())
}
.await;
if result.is_err() {
let _ = self.repo.abandon_link(id).await;
}
result
}
async fn disconnect_token(
&self,
link_id: Uuid,
generation: i64,
sync_generation: i64,
) -> Result<MicrosoftAccessGrant, MicrosoftAuthError> {
let grant = self
.repo
.disconnecting_grant(link_id, generation, sync_generation)
.await?;
self.token_for_grant(grant, false).await
}
async fn access_token(
&self,
link_id: Uuid,
generation: i64,
sync_generation: i64,
force_refresh: bool,
) -> Result<MicrosoftAccessGrant, MicrosoftAuthError> {
// Check revocation/generation on every call, including cache hits.
let grant = self
.repo
.active_grant(link_id, generation, sync_generation)
.await?;
self.token_for_grant(grant, force_refresh).await
}
}
impl<R: MicrosoftGrantRepository, P: MicrosoftIdentityProvider, F> MicrosoftAuthService<R, P, F> {
async fn token_for_grant(
&self,
grant: StoredGrant,
force_refresh: bool,
) -> Result<MicrosoftAccessGrant, MicrosoftAuthError> {
let key = (grant.id, grant.generation);
if force_refresh {
self.cache
.lock()
.map_err(|_| MicrosoftAuthError::Unavailable)?
.remove(&key);
}
if let Some(cached) = self
.cache
.lock()
.map_err(|_| MicrosoftAuthError::Unavailable)?
.get(&key)
.filter(|cached| cached.expires_at > Utc::now())
{
return Ok(MicrosoftAccessGrant {
token: cached.value.clone(),
scopes: cached.scopes.clone(),
cached: true,
});
}
let lease = macro_uuid::generate_uuid_v7();
if !self.repo.acquire_refresh(&grant, lease).await? {
return Err(MicrosoftAuthError::Busy);
}
let result = async {
let refresh = self
.cipher
.decrypt(&grant.owner, &grant.email, &grant.envelope)
.await
.map_err(|_| MicrosoftAuthError::Unavailable)?;
let mut refreshed = self.provider.refresh(&refresh).await?;
// OAuth permits omitting scope when the granted set is unchanged.
if refreshed.scopes.is_empty() {
refreshed.scopes = grant.scopes.clone();
}
refreshed.scopes = normalize_scopes(refreshed.scopes);
if !has_required_scopes(&refreshed.scopes) {
return Err(MicrosoftAuthError::MissingPermissions);
}
let envelope = if let Some(replacement) = refreshed.refresh_token {
self.cipher
.encrypt(&grant.owner, &grant.email, replacement)
.await
.map_err(|_| MicrosoftAuthError::Unavailable)?
} else {
grant.envelope.clone()
};
if !self
.repo
.finish_refresh(&grant, lease, &envelope, &refreshed.scopes)
.await?
{
return Err(MicrosoftAuthError::Busy);
}
let lifetime = refreshed.expires_in.min(86_400).saturating_sub(120) as i64;
let mut cache = self
.cache
.lock()
.map_err(|_| MicrosoftAuthError::Unavailable)?;
cache.retain(|_, token| token.expires_at > Utc::now());
if cache.len() >= 10_000 {
cache.clear();
}
cache.insert(
key,
CachedToken {
value: refreshed.access_token.clone(),
scopes: refreshed.scopes.clone(),
expires_at: Utc::now() + Duration::seconds(lifetime),
},
);
Ok(MicrosoftAccessGrant {
token: refreshed.access_token,
scopes: refreshed.scopes,
cached: false,
})
}
.await;
if let Err(error) = &result {
self.repo
.release_refresh(
&grant,
lease,
matches!(
error,
MicrosoftAuthError::ReauthorizationRequired
| MicrosoftAuthError::MissingPermissions
),
)
.await?;
}
result
}
}