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.

chore(macro_authorization): add documentation for the crate (#4918)

Will Hutchinson75ee07985a75
diff --git a/crates/macro_authorization/src/inbound/axum.rs b/crates/macro_authorization/src/inbound/axum.rs
index 97b997320c..82ac9c765e 100644
--- a/crates/macro_authorization/src/inbound/axum.rs
+++ b/crates/macro_authorization/src/inbound/axum.rs
@@ -103,11 +103,16 @@ static INTERNAL_HEADER_CONVENTIONS: [InternalHeaderConvention; 2] = [
},
];
-/// Extracts and authorizes credentials for a required authenticated user.
+/// Extracts and authorizes a required acting user.
///
-/// Internal service credentials are checked first. User credentials are read
-/// from the `macro-api-token` query parameter, followed by a bearer header or
-/// access-token cookie. The authorization service is resolved from Axum state.
+/// This extractor automatically supports both direct user access and internal
+/// service access. Internal credentials are checked first and must resolve to
+/// an acting user through an identity header or the configured default user.
+/// User credentials are read from the `macro-api-token` query parameter,
+/// followed by a bearer header or access-token cookie. Use
+/// [`InternalMacroAuthorizationExtractor`] instead only when the endpoint must
+/// be exclusively internal and does not require an acting user. The
+/// authorization service is resolved from Axum state.
#[non_exhaustive]
pub struct MacroAuthorizationExtractor<Svc> {
/// The validated Macro user identifier.
@@ -153,11 +158,19 @@ where
}
}
-/// Authorizes an internal service request using its internal API key.
+/// Authorizes an exclusively internal service endpoint using an internal API key.
+///
+/// Use this extractor only for endpoints that will never accept direct user
+/// access. Do not use it merely to support internal callers:
+/// [`MacroAuthorizationExtractor`] and [`OptionalMacroAuthorizationExtractor`]
+/// already accept internal credentials automatically. This extractor does not
+/// accept user credentials as a substitute and intentionally exposes no user
+/// identity.
///
/// Both the standard and legacy DSS internal API key headers are accepted.
/// Acting-user identity headers are forwarded to the authorization service so
-/// it can construct a user context, but only the internal API key is required.
+/// it can validate any supplied identity, but only the internal API key is
+/// required.
#[non_exhaustive]
pub struct InternalMacroAuthorizationExtractor<Svc> {
_service: PhantomData<fn() -> Svc>,
@@ -191,10 +204,16 @@ where
}
}
-/// Extracts and authorizes credentials when an authenticated user is present.
+/// Extracts and authorizes an optional acting user.
///
-/// Requests without credentials succeed with an empty [`UserContext`]. Any
-/// supplied credential must still pass authorization.
+/// This extractor automatically supports anonymous callers, direct user
+/// credentials, and internal service credentials. Internal credentials are
+/// checked first and set `is_internal_access` even when they establish no user
+/// identity. Requests without credentials succeed with an empty
+/// [`UserContext`]. Any supplied credential must still pass authorization; an
+/// invalid credential is never treated as anonymous. Use
+/// [`InternalMacroAuthorizationExtractor`] instead only when the endpoint must
+/// be exclusively internal.
#[non_exhaustive]
pub struct OptionalMacroAuthorizationExtractor<Svc> {
/// The validated Macro user identifier, or `None` for an anonymous request.
diff --git a/crates/macro_authorization/src/lib.rs b/crates/macro_authorization/src/lib.rs
index 3b69807bd2..be7dc322be 100644
--- a/crates/macro_authorization/src/lib.rs
+++ b/crates/macro_authorization/src/lib.rs
@@ -3,6 +3,34 @@
//!
//! The domain layer validates credentials through a cryptographic validation
//! port and returns the authenticated user's [`model_user::UserContext`].
+//!
+//! # Choosing an Axum extractor
+//!
+//! The `axum` feature provides three request extractors:
+//!
+//! - [`MacroAuthorizationExtractor`] requires an acting user. It accepts either
+//! user credentials or internal service credentials automatically. An
+//! internal request must resolve to a user through its acting-user header or
+//! [`InternalAuthConfig::default_user_id`].
+//! - [`OptionalMacroAuthorizationExtractor`] supports anonymous, authenticated
+//! user, and internal service callers. Missing credentials succeed without a
+//! user identity, but supplied invalid or expired credentials are rejected.
+//! - [`InternalMacroAuthorizationExtractor`] is for endpoints that will only
+//! ever be called by trusted internal services. It requires an internal API
+//! key, does not accept user credentials as a substitute, and exposes no user
+//! identity.
+//!
+//! [`MacroAuthorizationExtractor`] and [`OptionalMacroAuthorizationExtractor`]
+//! detect internal headers before user credentials, validate the internal key,
+//! and set `is_internal_access` to `true`. Do not add
+//! [`InternalMacroAuthorizationExtractor`] merely to let an internal service
+//! call an endpoint: use it only when being internal-only is part of the
+//! endpoint's security contract.
+//!
+//! These extractors authenticate the caller; they do not decide whether that
+//! caller may act on a particular entity. Entity authorization and business
+//! policy belong in the domain layer, typically using a typed entity-access
+//! receipt.
pub mod domain;
/// Inbound transport adapters backed by the authorization service.