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.

23.4 KB
Raw Blame
//! Domain models for entity access.

#[cfg(test)]
mod test;

use std::marker::PhantomData;

use macro_user_id::user_id::MacroUserIdStr;
use serde::{Deserialize, Serialize};
use uuid::Uuid;

#[cfg(feature = "explain_binary")]
mod access_explanation;

#[cfg(feature = "explain_binary")]
pub use access_explanation::{
    AccessExplanation, AccessGrant, EmailAttachmentReason, ForeignEntityAuthEntity,
};
pub use bot_id::{BotId, BotIdStr};
pub use model_entity::EntityType;
pub use models_entity_access_management::EntityAccessSourceType;
pub use models_permissions::share_permission::access_level::AccessLevel;
pub use models_permissions::share_permission::access_level::{
    CommentAccessLevel, EditAccessLevel, OwnerAccessLevel, ViewAccessLevel,
};

/// The access scope under which a bot-authorized request is resolved.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BotAccessScope {
    /// Resolve access as the verified acting user.
    User {
        /// The verified acting user's identifier.
        user_id: MacroUserIdStr<'static>,
        /// The verified acting user's organization identifier, when present.
        user_org_id: Option<i64>,
    },
    /// Resolve access from a team's shared access pool.
    Team {
        /// The owning team's identifier.
        team_id: Uuid,
    },
}

impl BotAccessScope {
    /// User scope for a caller that knows only the acting user, such as an AI
    /// tool request, which carries no organization context.
    pub fn user(user_id: MacroUserIdStr<'static>) -> Self {
        Self::User {
            user_id,
            user_org_id: None,
        }
    }

    /// Returns the verified acting user's identifier for user scope.
    pub fn user_id(&self) -> Option<&MacroUserIdStr<'static>> {
        match self {
            Self::User { user_id, .. } => Some(user_id),
            Self::Team { .. } => None,
        }
    }

    /// Returns the verified acting user's organization identifier for user scope.
    pub fn user_org_id(&self) -> Option<i64> {
        match self {
            Self::User { user_org_id, .. } => *user_org_id,
            Self::Team { .. } => None,
        }
    }

    /// Returns the owning team's identifier for team scope.
    pub fn team_id(&self) -> Option<Uuid> {
        match self {
            Self::Team { team_id } => Some(*team_id),
            Self::User { .. } => None,
        }
    }
}

/// The bot scope context retained in an entity-access receipt.
///
/// User organization identifiers are intentionally omitted because they are
/// request-time authorization context rather than receipt identity.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(tag = "scope", rename_all = "snake_case")]
pub enum BotReceiptScope {
    /// An autonomous webhook authorized only by its active channel membership.
    Channel {
        /// The sole channel authorized by this receipt.
        channel_id: Uuid,
    },
    /// Access was resolved as a verified acting user.
    User {
        /// The verified acting user's identifier.
        acting_user: MacroUserIdStr<'static>,
    },
    /// Access was resolved from a team's shared access pool.
    Team {
        /// The owning team's identifier.
        team_id: Uuid,
    },
}

impl BotReceiptScope {
    /// Returns the verified acting user's identifier for user scope.
    pub fn acting_user_id(&self) -> Option<&MacroUserIdStr<'static>> {
        match self {
            Self::User { acting_user } => Some(acting_user),
            Self::Team { .. } | Self::Channel { .. } => None,
        }
    }

    /// Returns the owning team's identifier for team scope.
    pub fn team_id(&self) -> Option<Uuid> {
        match self {
            Self::Team { team_id } => Some(*team_id),
            Self::User { .. } | Self::Channel { .. } => None,
        }
    }
}

impl From<&BotAccessScope> for BotReceiptScope {
    fn from(scope: &BotAccessScope) -> Self {
        match scope {
            BotAccessScope::User { user_id, .. } => Self::User {
                acting_user: user_id.clone(),
            },
            BotAccessScope::Team { team_id } => Self::Team { team_id: *team_id },
        }
    }
}

/// A user's resolved access to a CRM entity (company or contact) paired with
/// the entity's owning team — both produced by the same ownership lookup, so
/// the team is guaranteed to be the one that granted access (not the user's
/// default team).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CrmEntityAccess {
    /// The access level the user holds on the entity.
    pub access_level: AccessLevel,
    /// The team that owns the entity.
    pub team_id: Uuid,
    /// The role the user holds on the owning team. Hidden-row visibility
    /// keys on this (admin/owner) rather than on the access level.
    pub team_role: TeamRole,
}

/// The role a user has within a channel.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum ParticipantRole {
    /// Channel owner with full control.
    Owner,
    /// Channel administrator.
    Admin,
    /// Regular channel member.
    #[default]
    Member,
}

/// The role a user has within a team.
///
/// Ordered least to most privileged so comparisons reflect access strength.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "outbound", derive(sqlx::Type))]
#[cfg_attr(
    feature = "outbound",
    sqlx(type_name = "\"team_role\"", rename_all = "lowercase")
)]
#[serde(rename_all = "snake_case")]
pub enum TeamRole {
    /// Regular team member.
    #[default]
    Member,
    /// Team administrator.
    Admin,
    /// Team owner with full control.
    Owner,
}

/// Team member role.
#[derive(Debug, Clone, Copy)]
pub struct MemberTeamRole;

/// Team administrator role.
#[derive(Debug, Clone, Copy)]
pub struct AdminTeamRole;

/// Team owner role with full control.
#[derive(Debug, Clone, Copy)]
pub struct OwnerTeamRole;

/// Channel owner role with full control
#[derive(Debug, Clone, Copy)]
pub struct OwnerParticipantRole;

/// Channel Administrator
#[derive(Debug, Clone, Copy)]
pub struct AdminParticipantRole;

/// Regular channel member.
#[derive(Debug, Clone, Copy)]
pub struct MemberParticipantRole;

/// Permission to view a channel without requiring an active participant role.
#[derive(Debug, Clone, Copy)]
pub struct ViewOnly;

/// Permission marker that accepts every valid entity permission.
#[derive(Debug, Clone, Copy)]
pub struct AnyEntityPermission;

/// Trait implemented by marker types that encode a permission requirement.
pub trait RequiredPermission: std::fmt::Debug + Send + Sync + 'static {
    /// Returns whether the provided permission satisfies this requirement.
    fn is_satisfied_by(permission: &EntityPermission) -> bool;
}

/// A user's permission for an entity, discriminated by entity kind.
///
/// Items (documents, chats, projects, threads) use access levels.
/// Channels use view-only permission or participant roles.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum EntityPermission {
    /// Permission for item-based entities (document, chat, project, thread).
    AccessLevel {
        /// The access level the user has.
        access_level: AccessLevel,
    },
    /// View-only permission for a channel without an active participant role.
    ChannelViewOnly,
    /// Permission for channel-based entities with an active participant role.
    ChannelRole {
        /// The role the user has in the channel.
        role: ParticipantRole,
    },
    /// Permission for team-based entities.
    TeamRole {
        /// The role the user has in the team.
        role: TeamRole,
    },
}

impl EntityPermission {
    /// Returns whether this permission grants at least the requested access level.
    pub fn allows_access_level(&self, required: AccessLevel) -> bool {
        matches!(
            self,
            EntityPermission::AccessLevel { access_level } if *access_level >= required
        )
    }

    /// Returns whether this permission grants at least the requested channel role.
    pub fn allows_participant_role(&self, required: ParticipantRole) -> bool {
        matches!(
            (self, required),
            (
                EntityPermission::ChannelRole {
                    role: ParticipantRole::Owner,
                },
                ParticipantRole::Owner,
            ) | (
                EntityPermission::ChannelRole {
                    role: ParticipantRole::Owner | ParticipantRole::Admin,
                },
                ParticipantRole::Admin,
            ) | (
                EntityPermission::ChannelRole {
                    role: ParticipantRole::Owner | ParticipantRole::Admin | ParticipantRole::Member,
                },
                ParticipantRole::Member
            )
        )
    }

    /// Returns whether this permission grants at least the requested team role.
    pub fn allows_team_role(&self, required: TeamRole) -> bool {
        matches!(
            self,
            EntityPermission::TeamRole { role } if *role >= required
        )
    }

    /// Returns whether this permission satisfies the provided marker type.
    pub fn satisfies<T: RequiredPermission>(&self) -> bool {
        T::is_satisfied_by(self)
    }
}

impl RequiredPermission for AnyEntityPermission {
    fn is_satisfied_by(_permission: &EntityPermission) -> bool {
        true
    }
}

impl RequiredPermission for ViewAccessLevel {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_access_level(AccessLevel::View)
    }
}

impl RequiredPermission for CommentAccessLevel {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_access_level(AccessLevel::Comment)
    }
}

impl RequiredPermission for EditAccessLevel {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_access_level(AccessLevel::Edit)
    }
}

impl RequiredPermission for OwnerAccessLevel {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_access_level(AccessLevel::Owner)
    }
}

impl RequiredPermission for ViewOnly {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        matches!(
            permission,
            EntityPermission::ChannelViewOnly | EntityPermission::ChannelRole { .. }
        )
    }
}

impl RequiredPermission for OwnerParticipantRole {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_participant_role(ParticipantRole::Owner)
    }
}

impl RequiredPermission for AdminParticipantRole {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_participant_role(ParticipantRole::Admin)
    }
}

impl RequiredPermission for MemberParticipantRole {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_participant_role(ParticipantRole::Member)
    }
}

impl RequiredPermission for MemberTeamRole {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_team_role(TeamRole::Member)
    }
}

impl RequiredPermission for AdminTeamRole {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_team_role(TeamRole::Admin)
    }
}

impl RequiredPermission for OwnerTeamRole {
    fn is_satisfied_by(permission: &EntityPermission) -> bool {
        permission.allows_team_role(TeamRole::Owner)
    }
}

/// The team a user belongs to and the role they hold in it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct UserTeamInfo {
    /// The team's id.
    pub team_id: Uuid,
    /// The user's role within the team.
    pub role: TeamRole,
}

/// Result of resolving a user's role in a channel.
///
/// Distinguishes between an active participant role, view-only access,
/// no access to an existing channel, and a channel that does not exist.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ChannelRoleResult {
    /// User has a role in the channel.
    Role(ParticipantRole),
    /// User can view the channel without an active participant role.
    ViewOnly,
    /// Channel exists but user has no access.
    NoAccess,
    /// Channel does not exist.
    NotFound,
}

/// A given entity
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct Entity {
    /// The id of the entity
    pub entity_id: String,
    /// The type of the entity
    pub entity_type: EntityType,
}

/// A live conversation whose current access can be inherited by its agent session.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AgentSessionParent {
    /// Document discussion, including documents with legacy string identifiers.
    Document(String),
    /// Call chat, identified by the active or archived call.
    Call(Uuid),
}

impl From<AgentSessionParent> for Entity {
    fn from(parent: AgentSessionParent) -> Self {
        match parent {
            AgentSessionParent::Document(entity_id) => Self {
                entity_id,
                entity_type: EntityType::Document,
            },
            AgentSessionParent::Call(call_id) => Self {
                entity_id: call_id.to_string(),
                entity_type: EntityType::Call,
            },
        }
    }
}

/// Authentication context retained for a bot entity-access receipt.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct BotReceiptAuth {
    bot_id: BotIdStr<'static>,
    #[serde(flatten)]
    scope: BotReceiptScope,
}

impl BotReceiptAuth {
    /// Creates receipt authentication context for a bot and its access scope.
    pub fn new(bot_id: BotIdStr<'static>, scope: BotReceiptScope) -> Self {
        Self { bot_id, scope }
    }

    /// Returns the bot's canonical identifier.
    pub fn bot_id(&self) -> BotId {
        self.bot_id.bot_id()
    }

    /// Returns the bot's canonical storage principal.
    pub fn bot_id_str(&self) -> &BotIdStr<'static> {
        &self.bot_id
    }

    /// Returns the scope retained in the receipt.
    pub fn scope(&self) -> &BotReceiptScope {
        &self.scope
    }
}

impl std::fmt::Display for BotReceiptAuth {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(formatter, "{}", self.bot_id)
    }
}

/// The entity access auth type
#[derive(Debug, Clone, Serialize)]
#[serde(untagged)]
pub enum EntityAccessAuth {
    /// The user is authenticated
    Authenticated(MacroUserIdStr<'static>),
    /// A bot is authenticated under a specific access scope.
    Bot(BotReceiptAuth),
    /// The user is unauthenticated
    Unauthenticated,
    /// Internally authenticated
    Internal,
}

/// Represents that a given user has a given permission for the provided id.
///
/// The type parameter `T` encodes the minimum permission that was verified
/// when this receipt was created.
#[derive(Debug, Clone)]
pub struct EntityAccessReceipt<T: RequiredPermission> {
    /// The entity access authentication method
    pub(crate) auth: EntityAccessAuth,
    /// The entity that was requested access
    pub(crate) entity: Entity,
    /// The permission for the user on the entity
    pub(crate) entity_permission: EntityPermission,
    /// Phantom data to carry the access level type
    pub(crate) _marker: PhantomData<T>,
}

impl<T: RequiredPermission> EntityAccessReceipt<T> {
    /// Re-tag this receipt for another permission requirement after
    /// revalidating the already-resolved permission.
    ///
    /// This safely supports passing a stronger receipt to a read-only domain
    /// method without repeating the underlying access lookup.
    pub fn try_into_requirement<U: RequiredPermission>(
        self,
    ) -> Result<EntityAccessReceipt<U>, AccessError> {
        EntityAccessReceipt::<U>::try_new(self.auth, self.entity, self.entity_permission)
    }

    /// Creates an access receipt for the given auth after validating the
    /// provided permission against the required level `T`.
    pub fn try_new(
        auth: EntityAccessAuth,
        entity: Entity,
        entity_permission: EntityPermission,
    ) -> Result<EntityAccessReceipt<T>, AccessError> {
        if !entity_permission.satisfies::<T>() {
            return Err(AccessError::Unauthorized);
        }

        Ok(EntityAccessReceipt {
            auth,
            entity,
            entity_permission,
            _marker: PhantomData,
        })
    }

    /// Creates an access receipt for an authenticated user after validating the provided permission.
    pub fn try_new_authenticated_user(
        user_id: MacroUserIdStr<'static>,
        entity: Entity,
        entity_permission: EntityPermission,
    ) -> Result<EntityAccessReceipt<T>, AccessError> {
        Self::try_new(
            EntityAccessAuth::Authenticated(user_id),
            entity,
            entity_permission,
        )
    }

    /// Creates an access receipt for an authenticated bot after validating the provided permission.
    pub fn try_new_bot(
        bot_id: BotIdStr<'static>,
        scope: BotReceiptScope,
        entity: Entity,
        entity_permission: EntityPermission,
    ) -> Result<EntityAccessReceipt<T>, AccessError> {
        Self::try_new(
            EntityAccessAuth::Bot(BotReceiptAuth::new(bot_id, scope)),
            entity,
            entity_permission,
        )
    }

    /// Get the authenticated user or return an authorization error.
    pub fn get_authenticated_user(&self) -> Result<&MacroUserIdStr<'static>, AccessError> {
        match &self.auth {
            EntityAccessAuth::Authenticated(user) => Ok(user),
            EntityAccessAuth::Bot(_)
            | EntityAccessAuth::Unauthenticated
            | EntityAccessAuth::Internal => Err(AccessError::Unauthorized),
        }
    }

    /// Get the authenticated bot's canonical storage principal or return an authorization error.
    pub fn get_authenticated_bot(&self) -> Result<&BotIdStr<'static>, AccessError> {
        Ok(self.get_authenticated_bot_auth()?.bot_id_str())
    }

    /// Get the authenticated bot and receipt scope or return an authorization error.
    pub fn get_authenticated_bot_auth(&self) -> Result<&BotReceiptAuth, AccessError> {
        match &self.auth {
            EntityAccessAuth::Bot(bot_auth) => Ok(bot_auth),
            EntityAccessAuth::Authenticated(_)
            | EntityAccessAuth::Unauthenticated
            | EntityAccessAuth::Internal => Err(AccessError::Unauthorized),
        }
    }

    /// Returns the direct user or verified acting user represented by this receipt.
    pub fn acting_user_id(&self) -> Option<&MacroUserIdStr<'static>> {
        match &self.auth {
            EntityAccessAuth::Authenticated(user_id) => Some(user_id),
            EntityAccessAuth::Bot(bot_auth) => bot_auth.scope().acting_user_id(),
            EntityAccessAuth::Unauthenticated | EntityAccessAuth::Internal => None,
        }
    }

    /// Getter for auth
    pub fn auth(&self) -> &EntityAccessAuth {
        &self.auth
    }

    /// Getter for entity
    pub fn entity(&self) -> &Entity {
        &self.entity
    }

    /// Getter for entity permission
    pub fn entity_permission(&self) -> &EntityPermission {
        &self.entity_permission
    }

    /// Dangerously generates a EntityAccessReceipt for an internal user
    /// **NOTE** This should only be used in specific circumstances and not as a way
    /// to circumvent AI tool permissioning
    /// This **DOES NOT** assert the existence of the item
    pub fn dangerously_assert_internal_user(
        entity_id: &str,
        entity_type: EntityType,
    ) -> EntityAccessReceipt<T> {
        EntityAccessReceipt {
            auth: EntityAccessAuth::Internal,
            entity: Entity {
                entity_id: entity_id.to_string(),
                entity_type,
            },
            entity_permission: EntityPermission::AccessLevel {
                access_level: AccessLevel::Owner,
            },
            _marker: PhantomData,
        }
    }

    /// Dangerously generates an `EntityAccessReceipt` for an authenticated user
    /// without performing the underlying access check.
    ///
    /// **NOTE** This is intended for tests. It **DOES NOT** assert the
    /// existence of the item or that the user actually has the required
    /// permission.
    pub fn dangerously_assert_authenticated_user(
        user_id: MacroUserIdStr<'static>,
        entity_id: &str,
        entity_type: EntityType,
    ) -> EntityAccessReceipt<T> {
        EntityAccessReceipt {
            auth: EntityAccessAuth::Authenticated(user_id),
            entity: Entity {
                entity_id: entity_id.to_string(),
                entity_type,
            },
            entity_permission: EntityPermission::AccessLevel {
                access_level: AccessLevel::Owner,
            },
            _marker: PhantomData,
        }
    }

    /// Dangerously generates an `EntityAccessReceipt` for an authenticated bot
    /// without performing the underlying access check.
    ///
    /// **NOTE** This is intended for tests. It **DOES NOT** assert the
    /// existence of the item or that the bot actually has the required
    /// permission.
    pub fn dangerously_assert_bot(
        bot_id: BotIdStr<'static>,
        scope: BotReceiptScope,
        entity_id: &str,
        entity_type: EntityType,
    ) -> EntityAccessReceipt<T> {
        EntityAccessReceipt {
            auth: EntityAccessAuth::Bot(BotReceiptAuth::new(bot_id, scope)),
            entity: Entity {
                entity_id: entity_id.to_string(),
                entity_type,
            },
            entity_permission: EntityPermission::AccessLevel {
                access_level: AccessLevel::Owner,
            },
            _marker: PhantomData,
        }
    }
}

/// Information about a call's channel association and share permission.
#[derive(Debug, Clone)]
pub struct CallChannelInfo {
    /// The channel the call belongs to.
    pub channel_id: Option<Uuid>,
    /// The share permission ID for this call.
    pub share_permission_id: String,
}

/// Errors that can occur during access checking.
///
/// The variants are the domain's failure vocabulary; causes never appear as
/// typed payloads. Where a cause exists (a database error, a failed lookup)
/// it travels inside a [`rootcause::Report`] attached to the variant, so it
/// is visible in logs but structurally opaque to domain logic.
#[derive(Debug, thiserror::Error)]
pub enum AccessError {
    /// User does not have access to the requested resource.
    #[error("User does not have access to the requested resource")]
    Unauthorized,

    /// User does not have access with a specific message.
    #[error("{0}")]
    UnauthorizedWithMessage(&'static str),

    /// Access could not be checked because a backing service failed
    /// transiently; retrying may succeed. The cause is attached.
    #[error("access check temporarily unavailable: {0}")]
    Unavailable(rootcause::Report),

    /// Bad request parameters.
    #[error("Bad request: {0}")]
    BadRequest(&'static str),

    /// Requested resource was not found.
    #[error("Not found: {0}")]
    NotFound(&'static str),

    /// Internal server error; retrying will not help. The cause is attached.
    #[error("Internal error: {0}")]
    Internal(rootcause::Report),
}

impl AccessError {
    /// Non-retryable internal failure with a short reason attached to the
    /// report, for sites that have no underlying cause to carry.
    pub fn internal(reason: &'static str) -> Self {
        Self::Internal(rootcause::report!(reason).into_dynamic())
    }
}