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.

feat(auth): implement new auth extractor/service (#4751)

Will Hutchinson5ad28329f3ba
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index a743605a9c..a2544c1e94 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -2995,6 +2995,18 @@
"crates/remote_env_var",
"crates/workspace-hack"
],
+ "macro_authorization": [
+ "crates/cowlike",
+ "crates/macro_auth",
+ "crates/macro_authorization",
+ "crates/macro_env",
+ "crates/macro_env_var",
+ "crates/macro_user_id",
+ "crates/model-error-response",
+ "crates/model_user",
+ "crates/remote_env_var",
+ "crates/workspace-hack"
+ ],
"macro_aws_config": [
"crates/macro_aws_config",
"crates/macro_env_var",
diff --git a/Cargo.lock b/Cargo.lock
index 458a71448d..865b46f921 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -8091,6 +8091,30 @@ dependencies = [
"workspace-hack",
]
+[[package]]
+name = "macro_authorization"
+version = "0.1.0"
+dependencies = [
+ "axum",
+ "cookie",
+ "http-body-util",
+ "jsonwebtoken 10.3.0",
+ "macro_auth",
+ "macro_user_id",
+ "model-error-response",
+ "model_user",
+ "rootcause",
+ "serde",
+ "serde_json",
+ "serde_urlencoded",
+ "thiserror 2.0.18",
+ "tokio",
+ "tower 0.5.3",
+ "tracing",
+ "urlencoding",
+ "workspace-hack",
+]
+
[[package]]
name = "macro_aws_config"
version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index 0d2c7b3b0f..a31e7ec113 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -26,6 +26,7 @@ members = [
"crates/integration_tests/test_build_full_pdf_modification_data",
"crates/integration_tests/test_pdf_modification_data_deserialize",
"crates/loops_client",
+ "crates/macro_authorization",
"crates/macro_config",
"crates/macro_event_broker",
"crates/macro_event_topics",
diff --git a/crates/macro_authorization/Cargo.toml b/crates/macro_authorization/Cargo.toml
new file mode 100644
index 0000000000..0261e2b83b
--- /dev/null
+++ b/crates/macro_authorization/Cargo.toml
@@ -0,0 +1,40 @@
+[package]
+edition = "2024"
+name = "macro_authorization"
+publish = false
+version = "0.1.0"
+
+[features]
+axum = [
+ "dep:axum",
+ "dep:macro_auth",
+ "dep:macro_user_id",
+ "dep:model-error-response",
+ "dep:serde",
+ "dep:tracing",
+]
+default = ["axum", "outbound"]
+outbound = ["dep:macro_auth", "dep:tracing"]
+
+[dependencies]
+axum = { workspace = true, optional = true }
+macro_auth = { path = "../macro_auth", optional = true }
+macro_user_id = { path = "../macro_user_id", optional = true }
+model-error-response = { path = "../model-error-response", optional = true }
+model_user = { path = "../model_user" }
+rootcause = { workspace = true }
+serde = { workspace = true, optional = true }
+thiserror = { workspace = true }
+tracing = { workspace = true, optional = true }
+workspace-hack = { version = "0.1", path = "../workspace-hack" }
+
+[dev-dependencies]
+cookie = { workspace = true }
+http-body-util = { workspace = true }
+jsonwebtoken = { workspace = true }
+macro_auth = { path = "../macro_auth", features = ["testing"] }
+serde_json = { workspace = true }
+serde_urlencoded = { workspace = true }
+tokio = { workspace = true, features = ["macros", "rt"] }
+tower = { workspace = true, features = ["util"] }
+urlencoding = { workspace = true }
diff --git a/crates/macro_authorization/src/domain.rs b/crates/macro_authorization/src/domain.rs
new file mode 100644
index 0000000000..940bb52324
--- /dev/null
+++ b/crates/macro_authorization/src/domain.rs
@@ -0,0 +1,8 @@
+//! Authorization domain models, ports, and service implementation.
+
+/// Models produced and consumed by the authorization domain.
+pub mod models;
+/// Interfaces that connect the authorization domain to its adapters.
+pub mod ports;
+/// Authorization service implementation.
+pub mod service;
diff --git a/crates/macro_authorization/src/domain/models.rs b/crates/macro_authorization/src/domain/models.rs
new file mode 100644
index 0000000000..4fbaf125f0
--- /dev/null
+++ b/crates/macro_authorization/src/domain/models.rs
@@ -0,0 +1,33 @@
+use std::collections::HashSet;
+
+use thiserror::Error;
+
+/// 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 {
+ /// 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>>,
+}
+
+/// Errors returned when a credential cannot authorize a user.
+///
+/// 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,
+}
diff --git a/crates/macro_authorization/src/domain/ports.rs b/crates/macro_authorization/src/domain/ports.rs
new file mode 100644
index 0000000000..89c28c1ca5
--- /dev/null
+++ b/crates/macro_authorization/src/domain/ports.rs
@@ -0,0 +1,27 @@
+use std::future::Future;
+
+use model_user::UserContext;
+use rootcause::Report;
+
+use super::models::{MacroAuthorizationError, ValidatedIdentity};
+
+/// Cryptographic credential validation used by the authorization domain.
+///
+/// Implementations resolve any required secrets during startup, allowing this
+/// operation to remain synchronous.
+pub trait JwtValidator: Clone + Send + Sync + 'static {
+ /// Validate a credential and return its transport-independent identity.
+ fn validate(&self, jwt: &str) -> Result<ValidatedIdentity, Report<MacroAuthorizationError>>;
+}
+
+/// Authorizes credentials and constructs application user contexts.
+///
+/// The operation is asynchronous so implementations can later enrich an
+/// identity from persistent storage without changing this interface.
+pub trait MacroAuthorizationService: Clone + Send + Sync + 'static {
+ /// Authorize a credential and return its authenticated user context.
+ fn authorize(
+ &self,
+ jwt: &str,
+ ) -> impl Future<Output = Result<UserContext, Report<MacroAuthorizationError>>> + Send;
+}
diff --git a/crates/macro_authorization/src/domain/service.rs b/crates/macro_authorization/src/domain/service.rs
new file mode 100644
index 0000000000..e8359eed82
--- /dev/null
+++ b/crates/macro_authorization/src/domain/service.rs
@@ -0,0 +1,39 @@
+#[cfg(test)]
+mod test;
+
+use model_user::UserContext;
+use rootcause::Report;
+
+use super::{
+ models::MacroAuthorizationError,
+ ports::{JwtValidator, MacroAuthorizationService},
+};
+
+/// Default authorization service backed by a credential validator.
+#[derive(Clone)]
+pub struct MacroAuthorizationServiceImpl<V> {
+ validator: V,
+}
+
+impl<V> MacroAuthorizationServiceImpl<V> {
+ /// Create an authorization service using the supplied validator.
+ pub fn new(validator: V) -> Self {
+ Self { validator }
+ }
+}
+
+impl<V> MacroAuthorizationService for MacroAuthorizationServiceImpl<V>
+where
+ V: JwtValidator,
+{
+ async fn authorize(&self, jwt: &str) -> Result<UserContext, Report<MacroAuthorizationError>> {
+ let identity = self.validator.validate(jwt)?;
+
+ Ok(UserContext {
+ user_id: identity.user_id,
+ fusion_user_id: identity.fusion_user_id,
+ permissions: identity.permissions,
+ organization_id: identity.organization_id,
+ })
+ }
+}
diff --git a/crates/macro_authorization/src/domain/service/test.rs b/crates/macro_authorization/src/domain/service/test.rs
new file mode 100644
index 0000000000..e2500f9dcb
--- /dev/null
+++ b/crates/macro_authorization/src/domain/service/test.rs
@@ -0,0 +1,68 @@
+use std::collections::HashSet;
+
+use rootcause::Report;
+
+use super::*;
+use crate::domain::{
+ models::{MacroAuthorizationError, ValidatedIdentity},
+ ports::JwtValidator,
+};
+
+#[derive(Clone)]
+struct FakeJwtValidator {
+ result: Result<ValidatedIdentity, MacroAuthorizationError>,
+}
+
+impl JwtValidator for FakeJwtValidator {
+ fn validate(&self, _jwt: &str) -> Result<ValidatedIdentity, Report<MacroAuthorizationError>> {
+ self.result.clone().map_err(Report::new)
+ }
+}
+
+#[tokio::test]
+async fn authorize_constructs_user_context_from_validated_identity() {
+ let permissions = HashSet::from(["documents:read".to_string(), "documents:write".to_string()]);
+ let service = MacroAuthorizationServiceImpl::new(FakeJwtValidator {
+ result: Ok(ValidatedIdentity {
+ user_id: "macro|[email protected]".to_string(),
+ fusion_user_id: "fusion-user-id".to_string(),
+ organization_id: Some(42),
+ permissions: Some(permissions.clone()),
+ }),
+ });
+
+ let context = service.authorize("valid-jwt").await.unwrap();
+
+ assert_eq!(context.user_id, "macro|[email protected]");
+ assert_eq!(context.fusion_user_id, "fusion-user-id");
+ assert_eq!(context.organization_id, Some(42));
+ assert_eq!(context.permissions, Some(permissions));
+}
+
+#[tokio::test]
+async fn authorize_propagates_expired_credentials() {
+ let service = MacroAuthorizationServiceImpl::new(FakeJwtValidator {
+ result: Err(MacroAuthorizationError::CredentialsExpired),
+ });
+
+ let error = service.authorize("expired-jwt").await.unwrap_err();
+
+ assert_eq!(
+ error.current_context(),
+ &MacroAuthorizationError::CredentialsExpired
+ );
+}
+
+#[tokio::test]
+async fn authorize_propagates_invalid_credentials() {
+ let service = MacroAuthorizationServiceImpl::new(FakeJwtValidator {
+ result: Err(MacroAuthorizationError::InvalidCredentials),
+ });
+
+ let error = service.authorize("invalid-jwt").await.unwrap_err();
+
+ assert_eq!(
+ error.current_context(),
+ &MacroAuthorizationError::InvalidCredentials
+ );
+}
diff --git a/crates/macro_authorization/src/inbound.rs b/crates/macro_authorization/src/inbound.rs
new file mode 100644
index 0000000000..49d978ce30
--- /dev/null
+++ b/crates/macro_authorization/src/inbound.rs
@@ -0,0 +1,8 @@
+//! Inbound transport adapters for authorizing credentials.
+
+/// Axum extractors backed by the authorization service.
+pub mod axum;
+
+pub use axum::{
+ MacroAuthorizationExtractor, MacroAuthorizationRejection, OptionalMacroAuthorizationExtractor,
+};
diff --git a/crates/macro_authorization/src/inbound/axum.rs b/crates/macro_authorization/src/inbound/axum.rs
new file mode 100644
index 0000000000..35eebd5d17
--- /dev/null
+++ b/crates/macro_authorization/src/inbound/axum.rs
@@ -0,0 +1,199 @@
+#[cfg(test)]
+mod test;
+
+use std::{marker::PhantomData, sync::Arc};
+
+use ::axum::{
+ Json,
+ extract::{FromRef, FromRequestParts, Query},
+ http::{StatusCode, header, request::Parts},
+};
+use macro_auth::headers::AccessTokenExtractor;
+use macro_user_id::{cowlike::CowLike, user_id::MacroUserIdStr};
+use model_error_response::ErrorResponse;
+use model_user::UserContext;
+use rootcause::Report;
+use serde::Deserialize;
+
+use crate::{MacroAuthorizationError, MacroAuthorizationService};
+
+/// Rejection returned when request credentials cannot authorize a user.
+pub type MacroAuthorizationRejection = (StatusCode, Json<ErrorResponse<'static>>);
+
+#[derive(Deserialize)]
+#[serde(rename_all = "kebab-case")]
+struct AuthorizationQuery {
+ macro_api_token: Option<String>,
+}
+
+struct AuthorizedUser {
+ macro_user_id: MacroUserIdStr<'static>,
+ user_context: UserContext,
+}
+
+/// Extracts and authorizes credentials for a required authenticated user.
+///
+/// Credentials are read from the `macro-api-token` query parameter first,
+/// followed by a bearer header or access-token cookie. The authorization
+/// service is resolved from Axum state.
+#[non_exhaustive]
+pub struct MacroAuthorizationExtractor<Svc> {
+ /// The validated Macro user identifier.
+ pub macro_user_id: MacroUserIdStr<'static>,
+ /// The complete context returned by the authorization service.
+ pub user_context: UserContext,
+ _service: PhantomData<fn() -> Svc>,
+}
+
+impl<Svc> Clone for MacroAuthorizationExtractor<Svc> {
+ fn clone(&self) -> Self {
+ Self {
+ macro_user_id: self.macro_user_id.clone(),
+ user_context: self.user_context.clone(),
+ _service: PhantomData,
+ }
+ }
+}
+
+impl<S, Svc> FromRequestParts<S> for MacroAuthorizationExtractor<Svc>
+where
+ Arc<Svc>: FromRef<S>,
+ Svc: MacroAuthorizationService,
+ S: Send + Sync + 'static,
+{
+ type Rejection = MacroAuthorizationRejection;
+
+ async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+ let Some(authorized_user) = authorize_request::<S, Svc>(parts, state).await? else {
+ return Err(rejection("unauthorized"));
+ };
+
+ Ok(Self {
+ macro_user_id: authorized_user.macro_user_id,
+ user_context: authorized_user.user_context,
+ _service: PhantomData,
+ })
+ }
+}
+
+/// Extracts and authorizes credentials when an authenticated user is present.
+///
+/// Requests without credentials succeed with an empty [`UserContext`]. Any
+/// supplied credential must still pass authorization.
+#[non_exhaustive]
+pub struct OptionalMacroAuthorizationExtractor<Svc> {
+ /// The validated Macro user identifier, or `None` for an anonymous request.
+ pub macro_user_id: Option<MacroUserIdStr<'static>>,
+ /// The authorized context, or the default context for an anonymous request.
+ pub user_context: UserContext,
+ _service: PhantomData<fn() -> Svc>,
+}
+
+impl<Svc> Clone for OptionalMacroAuthorizationExtractor<Svc> {
+ fn clone(&self) -> Self {
+ Self {
+ macro_user_id: self.macro_user_id.clone(),
+ user_context: self.user_context.clone(),
+ _service: PhantomData,
+ }
+ }
+}
+
+impl<S, Svc> FromRequestParts<S> for OptionalMacroAuthorizationExtractor<Svc>
+where
+ Arc<Svc>: FromRef<S>,
+ Svc: MacroAuthorizationService,
+ S: Send + Sync + 'static,
+{
+ type Rejection = MacroAuthorizationRejection;
+
+ async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+ let Some(authorized_user) = authorize_request::<S, Svc>(parts, state).await? else {
+ return Ok(Self {
+ macro_user_id: None,
+ user_context: UserContext::default(),
+ _service: PhantomData,
+ });
+ };
+
+ Ok(Self {
+ macro_user_id: Some(authorized_user.macro_user_id),
+ user_context: authorized_user.user_context,
+ _service: PhantomData,
+ })
+ }
+}
+
+async fn authorize_request<S, Svc>(
+ parts: &mut Parts,
+ state: &S,
+) -> Result<Option<AuthorizedUser>, MacroAuthorizationRejection>
+where
+ Arc<Svc>: FromRef<S>,
+ Svc: MacroAuthorizationService,
+ S: Send + Sync + 'static,
+{
+ let Some(token) = extract_token(parts, state).await? else {
+ return Ok(None);
+ };
+
+ let service = Arc::<Svc>::from_ref(state);
+ let user_context = service
+ .authorize(&token)
+ .await
+ .map_err(authorization_rejection)?;
+ let macro_user_id = MacroUserIdStr::parse_from_str(&user_context.user_id)
+ .map(CowLike::into_owned)
+ .map_err(|error| {
+ tracing::error!(error=?error, "authorized context contained invalid macro user id");
+ rejection("invalid user id")
+ })?;
+
+ Ok(Some(AuthorizedUser {
+ macro_user_id,
+ user_context,
+ }))
+}
+
+async fn extract_token<S>(
+ parts: &mut Parts,
+ state: &S,
+) -> Result<Option<String>, MacroAuthorizationRejection>
+where
+ S: Send + Sync,
+{
+ let query_token = Query::<AuthorizationQuery>::from_request_parts(parts, state)
+ .await
+ .ok()
+ .and_then(|Query(query)| query.macro_api_token);
+
+ if let Some(token) = query_token {
+ return Ok(Some(token));
+ }
+
+ match AccessTokenExtractor::from_request_parts(parts, state).await {
+ Ok(token) => Ok(Some(token.as_ref().to_owned())),
+ Err(_) if parts.headers.contains_key(header::AUTHORIZATION) => {
+ Err(rejection("unauthorized"))
+ }
+ Err(_) => Ok(None),
+ }
+}
+
+fn authorization_rejection(error: Report<MacroAuthorizationError>) -> MacroAuthorizationRejection {
+ let message = match error.current_context() {
+ MacroAuthorizationError::CredentialsExpired => "jwt expired",
+ MacroAuthorizationError::InvalidCredentials => "unauthorized",
+ };
+ tracing::error!(error=?error, "credential authorization failed");
+ rejection(message)
+}
+
+fn rejection(message: &'static str) -> MacroAuthorizationRejection {
+ (
+ StatusCode::UNAUTHORIZED,
+ Json(ErrorResponse {
+ message: message.into(),
+ }),
+ )
+}
diff --git a/crates/macro_authorization/src/inbound/axum/test.rs b/crates/macro_authorization/src/inbound/axum/test.rs
new file mode 100644
index 0000000000..ab42c54ede
--- /dev/null
+++ b/crates/macro_authorization/src/inbound/axum/test.rs
@@ -0,0 +1,327 @@
+use std::sync::{Arc, Mutex};
+
+use ::axum::{
+ Json, Router,
+ body::Body,
+ extract::FromRef,
+ http::{Request, StatusCode},
+ routing::get,
+};
+use http_body_util::BodyExt;
+use rootcause::Report;
+use serde_json::{Value, json};
+use tower::ServiceExt;
+
+use super::*;
+
+const VALID_USER_ID: &str = "macro|[email protected]";
+const COOKIE_USER_ID: &str = "macro|[email protected]";
+const QUERY_USER_ID: &str = "macro|[email protected]";
+const BEARER_USER_ID: &str = "macro|[email protected]";
+const OPTIONAL_USER_ID: &str = "macro|[email protected]";
+const ACCESS_TOKEN_COOKIE: &str = "macro-access-token";
+
+#[derive(Clone, Default)]
+struct FakeAuthorizationService {
+ calls: Arc<Mutex<Vec<String>>>,
+}
+
+impl FakeAuthorizationService {
+ fn calls(&self) -> Vec<String> {
+ self.calls.lock().expect("calls lock poisoned").clone()
+ }
+}
+
+impl MacroAuthorizationService for FakeAuthorizationService {
+ async fn authorize(&self, jwt: &str) -> Result<UserContext, Report<MacroAuthorizationError>> {
+ self.calls
+ .lock()
+ .expect("calls lock poisoned")
+ .push(jwt.to_string());
+
+ match jwt {
+ "valid" => Ok(user_context(VALID_USER_ID, None)),
+ "cookie" => Ok(user_context(COOKIE_USER_ID, None)),
+ "query" => Ok(user_context(QUERY_USER_ID, None)),
+ "bearer" => Ok(user_context(BEARER_USER_ID, None)),
+ "optional" => Ok(user_context(OPTIONAL_USER_ID, None)),
+ "organization" => Ok(user_context(VALID_USER_ID, Some(42))),
+ "malformed-user" => Ok(user_context("not-a-macro-user-id", None)),
+ "empty-user" => Ok(user_context("", None)),
+ "expired" => Err(Report::new(MacroAuthorizationError::CredentialsExpired)),
+ _ => Err(Report::new(MacroAuthorizationError::InvalidCredentials)),
+ }
+ }
+}
+
+fn user_context(user_id: &str, organization_id: Option<i32>) -> UserContext {
+ UserContext {
+ user_id: user_id.to_string(),
+ fusion_user_id: "fusion-user-id".to_string(),
+ permissions: None,
+ organization_id,
+ }
+}
+
+#[derive(Clone)]
+struct TestState {
+ authorization: Arc<FakeAuthorizationService>,
+ _unrelated_state: &'static str,
+}
+
+impl FromRef<TestState> for Arc<FakeAuthorizationService> {
+ fn from_ref(state: &TestState) -> Self {
+ state.authorization.clone()
+ }
+}
+
+async fn required_handler(
+ extractor: MacroAuthorizationExtractor<FakeAuthorizationService>,
+) -> Json<Value> {
+ Json(json!({
+ "macro_user_id": extractor.macro_user_id.to_string(),
+ "user_context": extractor.user_context,
+ }))
+}
+
+async fn optional_handler(
+ extractor: OptionalMacroAuthorizationExtractor<FakeAuthorizationService>,
+) -> Json<Value> {
+ Json(json!({
+ "macro_user_id": extractor.macro_user_id.map(|id| id.to_string()),
+ "user_context": extractor.user_context,
+ }))
+}
+
+fn test_router() -> (Router, FakeAuthorizationService) {
+ let service = FakeAuthorizationService::default();
+ let state = TestState {
+ authorization: Arc::new(service.clone()),
+ _unrelated_state: "composite state",
+ };
+ let router = Router::new()
+ .route("/required", get(required_handler))
+ .route("/optional", get(optional_handler))
+ .with_state(state);
+
+ (router, service)
+}
+
+async fn send(router: &Router, request: Request<Body>) -> (StatusCode, Value) {
+ let response = router.clone().oneshot(request).await.unwrap();
+ let status = response.status();
+ let body = response.into_body().collect().await.unwrap().to_bytes();
+ let body = serde_json::from_slice(&body).expect("response should contain JSON");
+
+ (status, body)
+}
+
+fn request(path: &str) -> ::axum::http::request::Builder {
+ Request::get(path)
+}
+
+fn empty_body(request: ::axum::http::request::Builder) -> Request<Body> {
+ request.body(Body::empty()).unwrap()
+}
+
+fn assert_clone_without_service_clone<T: Clone>() {}
+
+#[test]
+fn extractors_are_clone_without_requiring_service_clone() {
+ struct NotClone;
+
+ assert_clone_without_service_clone::<MacroAuthorizationExtractor<NotClone>>();
+ assert_clone_without_service_clone::<OptionalMacroAuthorizationExtractor<NotClone>>();
+}
+
+#[tokio::test]
+async fn required_extracts_valid_bearer_and_preserves_organization() {
+ let (router, service) = test_router();
+ let request = empty_body(request("/required").header("authorization", "Bearer organization"));
+
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(body["macro_user_id"], VALID_USER_ID);
+ assert_eq!(body["user_context"]["organization_id"], 42);
+ assert_eq!(service.calls(), ["organization"]);
+}
+
+#[tokio::test]
+async fn required_extracts_valid_cookie() {
+ let (router, service) = test_router();
+ let request =
+ empty_body(request("/required").header("cookie", format!("{ACCESS_TOKEN_COOKIE}=cookie")));
+
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(body["macro_user_id"], COOKIE_USER_ID);
+ assert_eq!(service.calls(), ["cookie"]);
+}
+
+#[tokio::test]
+async fn query_token_takes_precedence_over_bearer_and_cookie() {
+ let (router, service) = test_router();
+ let request = empty_body(
+ request("/required?macro-api-token=query")
+ .header("authorization", "Bearer invalid")
+ .header("cookie", format!("{ACCESS_TOKEN_COOKIE}=invalid")),
+ );
+
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(body["macro_user_id"], QUERY_USER_ID);
+ assert_eq!(service.calls(), ["query"]);
+}
+
+#[tokio::test]
+async fn bearer_token_takes_precedence_over_cookie() {
+ let (router, service) = test_router();
+ let request = empty_body(
+ request("/required")
+ .header("authorization", "Bearer bearer")
+ .header("cookie", format!("{ACCESS_TOKEN_COOKIE}=invalid")),
+ );
+
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(body["macro_user_id"], BEARER_USER_ID);
+ assert_eq!(service.calls(), ["bearer"]);
+}
+
+#[tokio::test]
+async fn malformed_query_falls_back_to_other_or_absent_credentials() {
+ let (router, service) = test_router();
+ let malformed_query = "macro-api-token=query&macro-api-token=invalid";
+
+ let bearer_request = empty_body(
+ request(&format!("/required?{malformed_query}")).header("authorization", "Bearer bearer"),
+ );
+ let (status, body) = send(&router, bearer_request).await;
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(body["macro_user_id"], BEARER_USER_ID);
+
+ let cookie_request = empty_body(
+ request(&format!("/required?{malformed_query}"))
+ .header("cookie", format!("{ACCESS_TOKEN_COOKIE}=cookie")),
+ );
+ let (status, body) = send(&router, cookie_request).await;
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(body["macro_user_id"], COOKIE_USER_ID);
+
+ let (status, body) = send(
+ &router,
+ empty_body(request(&format!("/optional?{malformed_query}"))),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(body["macro_user_id"], Value::Null);
+ assert_eq!(body["user_context"]["user_id"], "");
+ assert_eq!(service.calls(), ["bearer", "cookie"]);
+}
+
+#[tokio::test]
+async fn required_rejects_missing_credentials() {
+ let (router, service) = test_router();
+
+ let (status, body) = send(&router, empty_body(request("/required"))).await;
+
+ assert_eq!(status, StatusCode::UNAUTHORIZED);
+ assert_eq!(body, json!({ "message": "unauthorized" }));
+ assert!(service.calls().is_empty());
+}
+
+#[tokio::test]
+async fn optional_returns_default_context_for_missing_credentials() {
+ let (router, service) = test_router();
+
+ let (status, body) = send(&router, empty_body(request("/optional"))).await;
+
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(body["macro_user_id"], Value::Null);
+ assert_eq!(body["user_context"]["user_id"], "");
+ assert_eq!(body["user_context"]["fusion_user_id"], "");
+ assert_eq!(body["user_context"]["organization_id"], Value::Null);
+ assert_eq!(body["user_context"]["permissions"], Value::Null);
+ assert!(service.calls().is_empty());
+}
+
+#[tokio::test]
+async fn required_rejects_invalid_credentials() {
+ let (router, service) = test_router();
+ let request = empty_body(request("/required").header("authorization", "Bearer invalid"));
+
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::UNAUTHORIZED);
+ assert_eq!(body, json!({ "message": "unauthorized" }));
+ assert_eq!(service.calls(), ["invalid"]);
+}
+
+#[tokio::test]
+async fn optional_rejects_supplied_invalid_credentials() {
+ let (router, service) = test_router();
+ let request = empty_body(request("/optional").header("authorization", "Bearer invalid"));
+
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::UNAUTHORIZED);
+ assert_eq!(body, json!({ "message": "unauthorized" }));
+ assert_eq!(service.calls(), ["invalid"]);
+}
+
+#[tokio::test]
+async fn required_and_optional_reject_expired_credentials() {
+ let (router, service) = test_router();
+
+ for path in ["/required", "/optional"] {
+ let request = empty_body(request(path).header("authorization", "Bearer expired"));
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::UNAUTHORIZED);
+ assert_eq!(body, json!({ "message": "jwt expired" }));
+ }
+
+ assert_eq!(service.calls(), ["expired", "expired"]);
+}
+
+#[tokio::test]
+async fn required_rejects_malformed_user_id() {
+ let (router, service) = test_router();
+ let request = empty_body(request("/required").header("authorization", "Bearer malformed-user"));
+
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::UNAUTHORIZED);
+ assert_eq!(body, json!({ "message": "invalid user id" }));
+ assert_eq!(service.calls(), ["malformed-user"]);
+}
+
+#[tokio::test]
+async fn optional_rejects_empty_user_id_from_authorized_context() {
+ let (router, service) = test_router();
+ let request = empty_body(request("/optional").header("authorization", "Bearer empty-user"));
+
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::UNAUTHORIZED);
+ assert_eq!(body, json!({ "message": "invalid user id" }));
+ assert_eq!(service.calls(), ["empty-user"]);
+}
+
+#[tokio::test]
+async fn optional_returns_authenticated_output() {
+ let (router, service) = test_router();
+ let request = empty_body(request("/optional").header("authorization", "Bearer optional"));
+
+ let (status, body) = send(&router, request).await;
+
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(body["macro_user_id"], OPTIONAL_USER_ID);
+ assert_eq!(body["user_context"]["user_id"], OPTIONAL_USER_ID);
+ assert_eq!(body["user_context"]["fusion_user_id"], "fusion-user-id");
+ assert_eq!(service.calls(), ["optional"]);
+}
diff --git a/crates/macro_authorization/src/lib.rs b/crates/macro_authorization/src/lib.rs
new file mode 100644
index 0000000000..5a253afb57
--- /dev/null
+++ b/crates/macro_authorization/src/lib.rs
@@ -0,0 +1,27 @@
+#![deny(missing_docs)]
+//! Transport-independent authorization services and optional transport adapters.
+//!
+//! The domain layer validates credentials through a cryptographic validation
+//! port and returns the authenticated user's [`model_user::UserContext`].
+
+pub mod domain;
+/// Inbound transport adapters backed by the authorization service.
+#[cfg(feature = "axum")]
+pub mod inbound;
+/// Adapters for validating credentials with external authentication systems.
+#[cfg(feature = "outbound")]
+pub mod outbound;
+
+pub use domain::{
+ models::{MacroAuthorizationError, ValidatedIdentity},
+ ports::{JwtValidator, MacroAuthorizationService},
+ service::MacroAuthorizationServiceImpl,
+};
+/// Service-backed Axum authorization extractors and their rejection type.
+#[cfg(feature = "axum")]
+pub use inbound::{
+ MacroAuthorizationExtractor, MacroAuthorizationRejection, OptionalMacroAuthorizationExtractor,
+};
+/// JWT validator backed by the shared `macro_auth` implementation.
+#[cfg(feature = "outbound")]
+pub use outbound::MacroAuthJwtValidator;
diff --git a/crates/macro_authorization/src/outbound.rs b/crates/macro_authorization/src/outbound.rs
new file mode 100644
index 0000000000..025dca1f83
--- /dev/null
+++ b/crates/macro_authorization/src/outbound.rs
@@ -0,0 +1,7 @@
+//! Outbound authorization adapters.
+
+/// JWT validation backed by the shared `macro_auth` implementation.
+pub mod macro_auth;
+
+/// JWT validator backed by the shared `macro_auth` implementation.
+pub use macro_auth::MacroAuthJwtValidator;
diff --git a/crates/macro_authorization/src/outbound/macro_auth.rs b/crates/macro_authorization/src/outbound/macro_auth.rs
new file mode 100644
index 0000000000..8390c3ad7a
--- /dev/null
+++ b/crates/macro_authorization/src/outbound/macro_auth.rs
@@ -0,0 +1,72 @@
+#[cfg(test)]
+mod test;
+
+use ::macro_auth::{
+ error::MacroAuthError,
+ middleware::decode_jwt::{self, JwtToken, JwtValidationArgs},
+};
+use rootcause::Report;
+
+use crate::domain::{
+ models::{MacroAuthorizationError, ValidatedIdentity},
+ ports::JwtValidator,
+};
+
+/// JWT validator backed by the shared `macro_auth` validation implementation.
+///
+/// The adapter delegates all cryptographic and claims validation to
+/// [`decode_jwt::handler`] and converts validated token claims into the
+/// authorization domain model.
+#[derive(Clone)]
+pub struct MacroAuthJwtValidator {
+ jwt_validation_args: JwtValidationArgs,
+}
+
+impl MacroAuthJwtValidator {
+ /// Create a validator with resolved Macro authentication configuration.
+ pub fn new(jwt_validation_args: JwtValidationArgs) -> Self {
+ Self {
+ jwt_validation_args,
+ }
+ }
+}
+
+impl JwtValidator for MacroAuthJwtValidator {
+ #[tracing::instrument(err, skip(self, jwt))]
+ fn validate(&self, jwt: &str) -> Result<ValidatedIdentity, Report<MacroAuthorizationError>> {
+ decode_jwt::handler(&self.jwt_validation_args, jwt)
+ .map(identity_from_token)
+ .map_err(validation_error)
+ }
+}
+
+fn identity_from_token(token: JwtToken) -> ValidatedIdentity {
+ let (user_id, fusion_user_id, organization_id) = match token {
+ JwtToken::MacroAccessToken(token) => (
+ token.macro_user_id,
+ token.root_macro_id.unwrap_or(token.fusion_user_id),
+ token.macro_organization_id,
+ ),
+ JwtToken::MacroApiToken(token) => (
+ token.macro_user_id,
+ token.fusion_user_id,
+ token.macro_organization_id,
+ ),
+ };
+
+ ValidatedIdentity {
+ user_id,
+ fusion_user_id,
+ organization_id,
+ permissions: None,
+ }
+}
+
+fn validation_error(error: MacroAuthError) -> Report<MacroAuthorizationError> {
+ let authorization_error = match &error {
+ MacroAuthError::JwtExpired => MacroAuthorizationError::CredentialsExpired,
+ _ => MacroAuthorizationError::InvalidCredentials,
+ };
+
+ Report::new(error).context(authorization_error)
+}
diff --git a/crates/macro_authorization/src/outbound/macro_auth/test.rs b/crates/macro_authorization/src/outbound/macro_auth/test.rs
new file mode 100644
index 0000000000..b362464050
--- /dev/null
+++ b/crates/macro_authorization/src/outbound/macro_auth/test.rs
@@ -0,0 +1,153 @@
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use ::macro_auth::{
+ error::MacroAuthError,
+ macro_api_token::MacroApiToken,
+ middleware::decode_jwt::{JwtToken, JwtValidationArgs, MacroAccessToken},
+};
+use jsonwebtoken::{Algorithm, EncodingKey, Header, encode};
+use rootcause::Report;
+
+use super::*;
+
+const MACRO_USER_ID: &str = "macro|[email protected]";
+const FUSION_USER_ID: &str = "fusion-user-id";
+
+fn unix_timestamp() -> usize {
+ SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .expect("system time should be after the Unix epoch")
+ .as_secs() as usize
+}
+
+fn access_token(
+ secret: &str,
+ expiration: usize,
+ root_macro_id: Option<&str>,
+ organization_id: Option<i32>,
+) -> String {
+ let claims = MacroAccessToken {
+ aud: String::new(),
+ exp: expiration,
+ tid: "tenant-id".to_string(),
+ iss: String::new(),
+ email: "[email protected]".to_string(),
+ fusion_user_id: FUSION_USER_ID.to_string(),
+ macro_user_id: MACRO_USER_ID.to_string(),
+ macro_organization_id: organization_id,
+ root_macro_id: root_macro_id.map(str::to_string),
+ };
+ let mut header = Header::new(Algorithm::HS256);
+ header.kid = Some("fusionauth".to_string());
+
+ encode(
+ &header,
+ &claims,
+ &EncodingKey::from_secret(secret.as_bytes()),
+ )
+ .expect("test JWT should encode")
+}
+
+fn validator() -> MacroAuthJwtValidator {
+ MacroAuthJwtValidator::new(JwtValidationArgs::new_testing())
+}
+
+fn macro_auth_cause(report: &Report<MacroAuthorizationError>) -> &MacroAuthError {
+ report
+ .iter_sub_reports()
+ .find_map(|cause| cause.downcast_current_context::<MacroAuthError>())
+ .expect("validation report should retain its macro_auth cause")
+}
+
+#[test]
+fn validates_access_token() {
+ let token = access_token("", unix_timestamp() + 3_600, None, None);
+
+ let identity = validator().validate(&token).unwrap();
+
+ assert_eq!(identity.user_id, MACRO_USER_ID);
+ assert_eq!(identity.fusion_user_id, FUSION_USER_ID);
+ assert_eq!(identity.organization_id, None);
+ assert_eq!(identity.permissions, None);
+}
+
+#[test]
+fn maps_expired_access_token_to_typed_error() {
+ let token = access_token("", unix_timestamp() - 3_600, None, None);
+
+ let error = validator().validate(&token).unwrap_err();
+
+ assert_eq!(
+ error.current_context(),
+ &MacroAuthorizationError::CredentialsExpired
+ );
+ assert!(matches!(
+ macro_auth_cause(&error),
+ MacroAuthError::JwtExpired
+ ));
+}
+
+#[test]
+fn maps_malformed_token_to_invalid_credentials() {
+ let error = validator().validate("not-a-jwt").unwrap_err();
+
+ assert_eq!(
+ error.current_context(),
+ &MacroAuthorizationError::InvalidCredentials
+ );
+ assert!(matches!(
+ macro_auth_cause(&error),
+ MacroAuthError::Generic(_)
+ ));
+}
+
+#[test]
+fn maps_wrong_signature_to_invalid_credentials() {
+ let token = access_token("wrong-secret", unix_timestamp() + 3_600, None, None);
+
+ let error = validator().validate(&token).unwrap_err();
+
+ assert_eq!(
+ error.current_context(),
+ &MacroAuthorizationError::InvalidCredentials
+ );
+ assert!(matches!(
+ macro_auth_cause(&error),
+ MacroAuthError::JwtValidationFailed { .. }
+ ));
+}
+
+#[test]
+fn maps_root_macro_id_to_fusion_identity_field() {
+ let token = access_token("", unix_timestamp() + 3_600, Some("root-macro-id"), None);
+
+ let identity = validator().validate(&token).unwrap();
+
+ assert_eq!(identity.user_id, MACRO_USER_ID);
+ assert_eq!(identity.fusion_user_id, "root-macro-id");
+}
+
+#[test]
+fn preserves_access_token_organization_id() {
+ let token = access_token("", unix_timestamp() + 3_600, None, Some(42));
+
+ let identity = validator().validate(&token).unwrap();
+
+ assert_eq!(identity.organization_id, Some(42));
+}
+
+#[test]
+fn maps_macro_api_token_claims() {
+ let identity = identity_from_token(JwtToken::MacroApiToken(MacroApiToken {
+ exp: unix_timestamp() + 3_600,
+ iss: String::new(),
+ fusion_user_id: FUSION_USER_ID.to_string(),
+ macro_user_id: MACRO_USER_ID.to_string(),
+ macro_organization_id: Some(84),
+ }));
+
+ assert_eq!(identity.user_id, MACRO_USER_ID);
+ assert_eq!(identity.fusion_user_id, FUSION_USER_ID);
+ assert_eq!(identity.organization_id, Some(84));
+ assert_eq!(identity.permissions, None);
+}