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
#[cfg(test)]
mod test;
use std::{collections::HashSet, fmt};
use bot_id::BotId;
use harness_id::HarnessId;
use macro_user_id::user_id::MacroUserIdStr;
use model_user::UserContext;
use thiserror::Error;
use uuid::Uuid;
/// A user identity that has been authenticated or verified for a bot.
#[derive(Clone, Debug)]
pub struct MacroUserAuthentication {
/// The kind of credential that established this user.
pub origin: CredentialOrigin,
/// Signed agent attribution for user-authorized SDK messages, not a bot credential.
pub agent_id: Option<BotId>,
/// Signed label of the client the user drives `agent_id` through.
pub agent_via: Option<String>,
/// The user's parsed Macro identifier.
pub macro_user_id: MacroUserIdStr<'static>,
/// The authenticated user context.
pub user_context: UserContext,
}
/// The kind of credential that authenticated a user, set where the credential
/// is verified. Policies that need a person's own session match on it rather
/// than on request hints.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum CredentialOrigin {
/// A personal session JWT.
Session,
/// A verified Macro API JWT (SDK, MCP), with or without agent attribution.
MacroApiJwt,
/// A user API key.
UserApiKey,
/// A manager's credential for this account, held by another account.
AccountManager(AccountManagerCredential),
/// The acting user of a verified bot credential.
Bot,
/// The acting user of a verified harness credential.
Harness,
/// The acting user claimed by a verified internal service caller.
Internal,
}
/// Who holds an account manager credential, and through which grant.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct AccountManagerCredential {
/// The grant that issued the credential.
pub grant_id: Uuid,
/// The agent account holding the credential.
pub manager_user_id: MacroUserIdStr<'static>,
}
/// The access scope selected for a bot-authorized request.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum BotScope {
/// Authorize access in the bot's user scope.
User,
/// Authorize access in the bot's team scope.
Team,
}
impl BotScope {
/// Return the header representation of this scope.
pub const fn as_str(self) -> &'static str {
match self {
Self::User => "user",
Self::Team => "team",
}
}
}
impl fmt::Display for BotScope {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(self.as_str())
}
}
/// A bot principal whose token has been validated.
///
/// The raw token is deliberately excluded so it cannot flow into handlers,
/// tracing spans, or logs after authentication.
#[derive(Clone, Debug)]
pub struct BotAuthentication {
/// The validated bot.
pub bot_id: BotId,
/// The token row used to authenticate, for audit and telemetry.
pub token_id: Uuid,
/// The access scope required by this bot-authorized request.
pub bot_scope: BotScope,
/// The bot's owning team for team-owned bots, regardless of the requested scope.
pub team_id: Option<Uuid>,
/// The verified acting user, when one was requested and authorized.
pub acting_user: Option<MacroUserAuthentication>,
}
/// A harness principal whose token has been validated.
///
/// The raw token is deliberately excluded so it cannot flow into handlers,
/// tracing spans, or logs after authentication.
#[derive(Clone, Debug)]
pub struct HarnessAuthentication {
/// The validated harness.
pub harness_id: HarnessId,
/// The token row used to authenticate, for audit and telemetry.
pub token_id: Uuid,
/// The harness owner used by acting-user policy.
pub owner: HarnessAuthorizationOwner,
/// The verified user this request acts for.
///
/// Always resolved server-side: the claimed user when the daemon forwards
/// one (a mention sender, verified against harness ownership), otherwise
/// the harness owner for private harnesses or its creator for team
/// harnesses. A guaranteed acting user lets acting-user-gated endpoints
/// (webhook feed registration) admit harness callers unchanged.
pub acting_user: MacroUserAuthentication,
}
/// How the caller authenticated.
///
/// This enum is exhaustive so adding an authentication source requires every
/// authorization decision to account for it explicitly.
#[derive(Clone, Debug)]
pub enum MacroAuthorization {
/// A caller authenticated directly with user credentials.
User(MacroUserAuthentication),
/// A caller authenticated with a bot token.
Bot(BotAuthentication),
/// A caller authenticated with a harness token.
Harness(HarnessAuthentication),
/// An internally authenticated service, optionally acting for a user.
Internal(Option<MacroUserAuthentication>),
}
impl MacroAuthorization {
/// Return the authenticated or verified user the caller is acting for.
pub fn acting_user(&self) -> Option<&MacroUserAuthentication> {
match self {
Self::User(user) => Some(user),
Self::Bot(bot) => bot.acting_user.as_ref(),
Self::Harness(harness) => Some(&harness.acting_user),
Self::Internal(user) => user.as_ref(),
}
}
/// Return whether the caller authenticated as an internal service.
pub fn is_internal(&self) -> bool {
matches!(self, Self::Internal(_))
}
/// Return the authenticated bot principal, when the caller is a bot.
pub fn bot(&self) -> Option<&BotAuthentication> {
match self {
Self::Bot(bot) => Some(bot),
Self::User(_) | Self::Harness(_) | Self::Internal(_) => None,
}
}
/// Return the authenticated harness principal, when the caller is a harness.
pub fn harness(&self) -> Option<&HarnessAuthentication> {
match self {
Self::Harness(harness) => Some(harness),
Self::User(_) | Self::Bot(_) | Self::Internal(_) => None,
}
}
}
/// Ownership facts for a bot whose token has been validated.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum BotAuthorizationOwner {
/// A bot owned by one Macro user.
User {
/// The owning Macro user identifier.
user_id: String,
},
/// A bot owned by a team.
Team {
/// The owning team identifier.
team_id: Uuid,
},
/// A first-party system bot with no user or team owner.
System,
}
/// Ownership facts for a harness whose token has been validated.
///
/// Unlike bots, a harness always has a user or team owner; there are no
/// system harnesses.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum HarnessAuthorizationOwner {
/// A harness owned by one Macro user.
User {
/// The owning Macro user identifier.
user_id: String,
},
/// A harness owned by a team.
Team {
/// The owning team identifier.
team_id: Uuid,
},
}
/// Valid harness-token facts returned by the authorization repository.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct HarnessTokenAuthorization {
/// The authenticated harness.
pub harness_id: HarnessId,
/// The token row used to authenticate.
pub token_id: Uuid,
/// The harness owner used by acting-user policy.
pub owner: HarnessAuthorizationOwner,
/// The Macro user id that registered the harness.
///
/// The default acting user for team-owned harnesses.
pub created_by: String,
}
/// Valid bot-token facts returned by the authorization repository.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct BotTokenAuthorization {
/// The authenticated bot.
pub bot_id: BotId,
/// The token row used to authenticate.
pub token_id: Uuid,
/// The bot owner used by acting-user policy.
pub owner: BotAuthorizationOwner,
}
/// Acting-user facts resolved from the user store.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ResolvedBotActingUser {
/// The user's parsed Macro identifier.
pub macro_user_id: MacroUserIdStr<'static>,
/// The user's FusionAuth identifier.
pub fusion_user_id: String,
/// The user's organization, when present.
pub organization_id: Option<i32>,
}
/// User identity facts resolved for a valid user API key.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ResolvedApiKeyUser {
/// The user's parsed Macro identifier.
pub macro_user_id: MacroUserIdStr<'static>,
/// The user's FusionAuth identifier.
pub fusion_user_id: String,
/// The user's organization, when present.
pub organization_id: Option<i32>,
/// Set when the key is an account manager's credential, not the user's own.
pub account_manager: Option<AccountManagerCredential>,
}
/// A user API key's owner, and the manager holding the key when it isn't theirs.
#[derive(Clone, Debug)]
pub struct AuthorizedUserApiKey {
/// The account the key acts as.
pub user_context: UserContext,
/// Set when the key is an account manager's credential, not the user's own.
pub account_manager: Option<AccountManagerCredential>,
}
/// Unverified acting-user claims presented by a bot.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct BotActingUserClaims {
/// The claimed Macro user identifier.
pub user_id: Option<String>,
/// The claimed FusionAuth user identifier.
pub fusion_user_id: Option<String>,
/// The claimed organization identifier.
pub organization_id: Option<i32>,
}
/// Identity claims presented by an internally authenticated caller.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct InternalIdentityClaims {
/// The acting user's Macro identifier, when the caller acts on a user's behalf.
pub user_id: Option<String>,
/// The acting user's FusionAuth identifier.
pub fusion_user_id: Option<String>,
/// The acting user's organization.
pub organization_id: Option<i32>,
}
/// Configuration enabling internal service-to-service authorization.
#[derive(Clone)]
pub struct InternalAuthConfig {
/// The shared secret internal callers must present.
pub api_key: String,
/// Identity assumed for internal callers that supply no acting user.
pub default_user_id: Option<String>,
}
/// An identity whose credential has already passed cryptographic validation.
///
/// Validation adapters construct this value without exposing token claim types
/// to the authorization service.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ValidatedIdentity {
/// Agent attribution from a cryptographically verified Macro API token.
pub agent_id: Option<BotId>,
/// Client label signed with `agent_id`, such as "Claude Code".
pub agent_via: Option<String>,
/// The user's Macro identifier.
pub user_id: String,
/// The user's FusionAuth or root identifier.
pub fusion_user_id: String,
/// The organization the user belongs to, when present.
pub organization_id: Option<i32>,
/// Permissions established while validating or enriching the identity.
pub permissions: Option<HashSet<String>>,
}
/// A validated identity together with its cryptographically established origin.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ValidatedCredential {
/// Identity established by credential validation.
pub identity: ValidatedIdentity,
/// The kind of credential that was verified.
pub origin: CredentialOrigin,
}
impl ValidatedCredential {
/// A personal session for this user context, with no agent attribution.
pub fn session(context: UserContext) -> Self {
Self {
origin: CredentialOrigin::Session,
identity: ValidatedIdentity {
agent_id: None,
agent_via: None,
user_id: context.user_id,
fusion_user_id: context.fusion_user_id,
organization_id: context.organization_id,
permissions: context.permissions,
},
}
}
}
/// Errors returned when a credential cannot authorize a caller.
///
/// The variants deliberately omit validation implementation details so callers
/// can handle authorization failures without exposing sensitive information.
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
pub enum MacroAuthorizationError {
/// The supplied credential was valid but has expired.
#[error("credentials expired")]
CredentialsExpired,
/// The supplied credential is otherwise invalid.
#[error("invalid credentials")]
InvalidCredentials,
/// The authenticated bot is not authorized to act for the claimed user.
#[error("acting user not authorized")]
ActingUserNotAuthorized,
/// The authenticated bot cannot use the requested access scope.
#[error("bot scope not authorized")]
BotScopeNotAuthorized,
/// Authorization could not be completed because a required service failed.
#[error("authorization unavailable")]
Unavailable,
}