Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
8.2 KB
Raw Blame
//! Per-request actor context helpers for MCP tool handlers.
//!
//! ## Why this exists
//!
//! The auth middleware injects canonical [`ActorContext`] and [`AuthLevel`]
//! values into request extensions. Tool handlers receive raw HTTP `Parts` via
//! rmcp's `Extension<Parts>` extractor (rmcp 1.7+) and read those extensions;
//! raw actor headers are intentionally not trusted in handlers.
//!
//! ## Why not `tokio::task_local`
//!
//! We tried that first. `rmcp::transport::streamable_http_server::tower`
//! dispatches each tool handler via `tokio::spawn` (see
//! `tower.rs:569+619+1183`), which **does not** inherit task-locals from
//! the outer axum middleware. The Extension extractor is the official
//! supported path — see
//! <https://docs.rs/rmcp/1.7/rmcp/transport/streamable_http_server/struct.StreamableHttpService.html#accessing-http-request-data-from-tool-handlers>.
//!
//! ## Skip-list header
//!
//! `X-Memory-Skip-Admission-Chain` is a loop-prevention escape hatch for
//! trusted webhook re-entry. It is honored only for root/auth-disabled requests
//! (or test/stdio calls with no auth extension), so a regular DB user cannot
//! bypass a reject-policy admission webhook by setting a client-controlled
//! header.

use ai_memory_core::{ActorContext, AuthLevel, UserId};
use axum::http::HeaderMap;
use axum::http::request::Parts;

fn header_str(headers: &HeaderMap, name: &str) -> Option<String> {
    headers
        .get(name)
        .and_then(|v| v.to_str().ok())
        .map(|s| s.trim().to_string())
        .filter(|s| !s.is_empty())
}

/// Build an [`ActorContext`] from `X-Memory-Actor-*` headers.
///
/// Header names are matched case-insensitively (per HTTP spec).
#[must_use]
pub fn actor_from_headers(headers: &HeaderMap) -> ActorContext {
    ActorContext {
        agent: header_str(headers, "x-memory-actor-agent"),
        user: header_str(headers, "x-memory-actor-user"),
        issuer: header_str(headers, "x-memory-actor-issuer"),
        sub: header_str(headers, "x-memory-actor-sub"),
        client: header_str(headers, "x-memory-actor-client"),
        session_id: header_str(headers, "x-memory-actor-session-id"),
        // `name`/`email` aren't carried by the `X-Memory-Actor-*` bridge;
        // the four-rung auth middleware fills those when it injects the
        // canonical `Extension<ActorContext>` directly.
        ..ActorContext::default()
    }
}

/// Return the authenticated actor injected by the auth middleware. Raw
/// `X-Memory-Actor-*` headers are deliberately ignored here; handlers should
/// only trust middleware-resolved identity.
#[must_use]
pub fn actor_from_parts(parts: &Parts) -> ActorContext {
    parts
        .extensions
        .get::<ActorContext>()
        .cloned()
        .unwrap_or_else(ActorContext::anonymous)
}

/// Return the authenticated DB user's id when multi-user auth resolved one.
#[must_use]
pub fn author_id_from_parts(parts: &Parts) -> Option<UserId> {
    parts.extensions.get::<UserId>().copied()
}

fn header_value(headers: &HeaderMap) -> Option<&str> {
    headers
        .get(ai_memory_core::SKIP_ADMISSION_CHAIN_HEADER)
        .and_then(|v| v.to_str().ok())
}

/// Parse the admission-chain loop-prevention skip list from the
/// `X-Memory-Skip-Admission-Chain` request header (comma-separated
/// webhook names). A webhook that writes back into the engine (e.g. via
/// `memory_write_page`) sets this so the chain doesn't re-invoke it on
/// the recursive write — see [`ai_memory_wiki::AdmissionContext::skip_webhooks`].
///
/// Returns an empty `Vec` when the header is absent. Entries are trimmed
/// and empty tokens dropped, so `"a, ,b,"` → `["a", "b"]`.
#[must_use]
pub fn skip_webhooks_from_headers(headers: &HeaderMap) -> Vec<String> {
    ai_memory_core::parse_skip_admission_chain(header_value(headers))
}

/// Parse the skip-list header only for trusted re-entry contexts.
#[must_use]
pub fn skip_webhooks_from_parts(parts: &Parts) -> Vec<String> {
    let level = parts
        .extensions
        .get::<AuthLevel>()
        .copied()
        .unwrap_or(AuthLevel::Anonymous);
    ai_memory_core::skip_admission_chain_for(level, header_value(&parts.headers))
}

#[cfg(test)]
mod tests {
    use super::*;
    use axum::http::HeaderValue;

    #[test]
    fn full_header_set_maps_correctly() {
        let mut h = HeaderMap::new();
        h.insert(
            "x-memory-actor-agent",
            HeaderValue::from_static("claude-code"),
        );
        h.insert("x-memory-actor-user", HeaderValue::from_static("djalmajr"));
        h.insert(
            "x-memory-actor-issuer",
            HeaderValue::from_static("https://idp.example"),
        );
        h.insert("x-memory-actor-sub", HeaderValue::from_static("8f3a-uuid"));
        h.insert(
            "x-memory-actor-client",
            HeaderValue::from_static("72836f52-uuid"),
        );
        h.insert(
            "x-memory-actor-session-id",
            HeaderValue::from_static("019e6d-session"),
        );
        let ctx = actor_from_headers(&h);
        assert_eq!(ctx.agent.as_deref(), Some("claude-code"));
        assert_eq!(ctx.user.as_deref(), Some("djalmajr"));
        assert_eq!(ctx.issuer.as_deref(), Some("https://idp.example"));
        assert_eq!(ctx.sub.as_deref(), Some("8f3a-uuid"));
        assert_eq!(ctx.client.as_deref(), Some("72836f52-uuid"));
        assert_eq!(ctx.session_id.as_deref(), Some("019e6d-session"));
        assert!(ctx.has_any());
    }

    #[test]
    fn missing_headers_leave_none() {
        let h = HeaderMap::new();
        let ctx = actor_from_headers(&h);
        assert!(ctx.agent.is_none());
        assert!(ctx.user.is_none());
        assert!(ctx.issuer.is_none());
        assert!(ctx.sub.is_none());
        assert!(ctx.client.is_none());
        assert!(ctx.session_id.is_none());
        assert!(!ctx.has_any());
    }

    #[test]
    fn empty_or_whitespace_header_treated_as_none() {
        let mut h = HeaderMap::new();
        h.insert("x-memory-actor-agent", HeaderValue::from_static("   "));
        h.insert("x-memory-actor-user", HeaderValue::from_static(""));
        let ctx = actor_from_headers(&h);
        assert!(ctx.agent.is_none(), "whitespace must trim to None");
        assert!(ctx.user.is_none(), "empty must be None");
        assert!(!ctx.has_any());
    }

    #[test]
    fn case_insensitive_header_lookup() {
        // HeaderMap normalises names to lowercase on insert; this verifies
        // that the canonical `X-Memory-Actor-Agent` form also resolves.
        let mut h = HeaderMap::new();
        h.insert("X-Memory-Actor-Agent", HeaderValue::from_static("codex"));
        let ctx = actor_from_headers(&h);
        assert_eq!(ctx.agent.as_deref(), Some("codex"));
    }

    #[test]
    fn skip_webhooks_parses_csv_trims_and_drops_empties() {
        let mut h = HeaderMap::new();
        h.insert(
            "x-memory-skip-admission-chain",
            HeaderValue::from_static("contributors, ,git-mirror,"),
        );
        assert_eq!(
            skip_webhooks_from_headers(&h),
            vec!["contributors".to_string(), "git-mirror".to_string()]
        );
    }

    #[test]
    fn skip_webhooks_absent_header_is_empty() {
        let h = HeaderMap::new();
        assert!(skip_webhooks_from_headers(&h).is_empty());
    }

    #[test]
    fn actor_from_parts_prefers_authenticated_extension_over_headers() {
        let mut req = axum::http::Request::builder().uri("/mcp").body(()).unwrap();
        req.headers_mut().insert(
            "x-memory-actor-user",
            HeaderValue::from_static("spoofed-user"),
        );
        req.extensions_mut().insert(ActorContext {
            user: Some("real-user".into()),
            ..ActorContext::default()
        });
        let parts = req.into_parts().0;

        let actor = actor_from_parts(&parts);
        assert_eq!(actor.user.as_deref(), Some("real-user"));
    }

    #[test]
    fn skip_header_is_ignored_for_db_user_requests() {
        let mut req = axum::http::Request::builder().uri("/mcp").body(()).unwrap();
        req.headers_mut().insert(
            "x-memory-skip-admission-chain",
            HeaderValue::from_static("validator"),
        );
        req.extensions_mut().insert(AuthLevel::User);
        let parts = req.into_parts().0;

        assert!(skip_webhooks_from_parts(&parts).is_empty());
    }
}