Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
entity_access
What it is
Shared infrastructure used across nearly every feature: entity access control for cloud storage, checking a user's or bot's access level to any entity (documents, chats, projects, and more). One of the most widely depended-on crates in the backend.
Start here
src/domain/service.rs+src/domain/ports.rs:EntityAccessServiceand theAccessRepositorytrait it's built on — oneget_<entity>_accessmethod per entity kind.src/domain/models.rs:AccessLevel,RequiredPermission,EntityAccessReceipt— the typed receipt proving a checked access level.src/inbound/axum_extractors.rs: Axum extractors that resolve a receipt from the request (featureinbound).src/outbound/pg_access_repo.rs: the Postgres adapter (featureoutbound). Form Edit/Owner grants Edit on the backing database; form View grants database View only when that form shares its responses.src/bin/explain_access.rs: CLI to explain why a user has (or lacks) access to an entity (featureexplain_binary).
Scope
- Owns: read-side access-level checks and their
EntityAccessReceiptproof type. - Not here: writing/propagating access grants (project moves, sharing
updates) →
crates/entity_access_management; the rawentity_accesstable queries →crates/entity_access_db_utils.
Boundaries
- Depends on:
model-entity,model_owner,models_entity_access_management,models_permissions,macro_user_id,bot_id. - Used by: nearly every domain crate that authorizes a request (
documents,chat,projects,crm,forms,databases,channels,agent_session,graphql_*crates, and most services) — a signature change here ripples widely; check callers first.
Recipes
- Add an entity kind's access check:
src/domain/ports.rs(AccessRepositorymethod) →src/domain/service.rs→src/outbound/pg_access_repo.rs. - Debug a specific grant:
cargo run -p entity_access --bin explain_access --features explain_binary.
Checks
cargo test -p entity_access(SQLX_OFFLINEunset; requires local MacroDB —just setup_macrodb).
The message sender extractor maps signed user agent_id attribution to a bot
receipt scoped to that same user and organization only for new posts. Reads,
edits, deletes, and reactions keep the caller identity; access policy remains in
the entity-access domain service.
Gotchas
#![deny(missing_docs)].EntityAccessReceipt<R: RequiredPermission>is the only proof a caller checked access at the right level; domain code downstream (e.g.entity_mutation) takes a receipt, not a raw boolean/level.ExternalChatresolves ordinary entity-access/link/team grants throughexternal_chat_access_level; its extractor readschat_id.
Related
- Rules:
.agents/rules/rust/architecture.md,.agents/rules/rust/security.md· Skill:cloud-storage-hexagonal-architecture