Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
macro_authorization
What it is
Belongs to shared infrastructure: transport-independent authorization used
by nearly every authenticated service. Validates user, bot,
internal-service, harness, and user-API-key credentials and returns a typed
principal; the Axum layer (axum feature) exposes this as extractors keyed
by policy.
Start here
src/lib.rs: doc comment has the full extractor/policy table (which principals eachAuthorizationPolicyadmits, and its narrowed output type) — read this before adding or choosing an extractor.src/domain/service.rs:MacroAuthorizationServiceImpl— the composed authorization service; bot and user-API-key authorizers are required explicitly (passNoBotAuthorizer/NoUserApiKeyAuthorizerto opt out).src/inbound/axum.rs: the Axum extractors and rejection type.src/outbound/pg_*.rs: Postgres-backed bot/harness/user-API-key authorization repos (featurepostgres).
Scope
- Owns: authenticating a caller (user/bot/internal/harness/API-key) into a
typed principal, and the bot scope (
user/team) header contract. - Not here: deciding whether that principal may act on a specific entity — that's a typed entity-access receipt in the domain layer that calls in.
Boundaries
- Depends on:
macro_auth(outbound JWT validation),bot_id,bot_token,harness_id,harness_token,model_user,model-error-response. - Used by: essentially every
authenticated HTTP surface (
agent_session,agent_harness,ai_tools,bots,calendar_events,channels,chat,documents, ...).
Recipes
- Add a new axum policy: add the
AuthorizationPolicyimpl + its narrowed output type insrc/inbound/axum.rs→ document it in thelib.rstable → re-export both fromlib.rs. - Wire a new service with MacroDB:
PgBotAuthorizer+PgUserApiKeyAuthorizer(featurepostgres) in the composition root — seecalendar_serviceor any service inservices/for the pattern.
Checks
cargo test -p macro_authorization(SQLX_OFFLINEunset).
ValidatedIdentity contains identity facts; ValidatedCredential and
MacroUserAuthentication additionally carry CredentialOrigin (session, Macro API
JWT, user API key, or the acting user of a bot, harness or internal caller), set
where the credential is verified. Every JwtValidator implements
validate_credential (validate derives from it) and every
MacroAuthorizationService implements authorize_identity; neither has a default
that assumes a session. Session-only fakes use ValidatedCredential::session. The
production MacroAuthJwtValidator derives origin from the verified token enum in
one decode.
Personal-session-only capabilities match origin == Session (and no agent
attribution) instead of sniffing request headers. authorize_identity retains
verified origin and signed agent attribution on user authentication. It
does not turn a user credential into bot authority or change endpoint policies.
An account manager's credential arrives as a normal x-macro-user-api-key and
authenticates as the managed account, with CredentialOrigin::AccountManager
naming the grant and the agent holding it. AccountHolderOrInternal is
UserOrInternal minus that credential: use it on anything that mints credentials,
changes who can sign in, deletes the account, or changes its managers.
Gotchas
- Both extractors reject (400) a request that combines explicit credential types (internal key, bot token, user API key, bearer/query user) rather than picking one — don't "fix" this by adding precedence logic.
- Cookies are ambient and only considered when no explicit credential is present; an explicit credential always wins over a cookie.
- A valid principal not admitted by the chosen policy is a 403, not a 401.
mark_harness_token_usedruns on every harness-authenticated request. It writeslast_used_atat most once a minute and skips a row another request is already updating. Don't make it a plain per-requestUPDATE: one busy token would then queue its requests on the row lock, each holding a pool connection.
Related
- Rules:
.agents/rules/rust/security.md,.agents/rules/rust/architecture.md