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: credential-stamping egress for agent sandboxes and Cursor cloud agents (#5756)

Wolf Mermelstein1542073835dc
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index 827cbefdd4..8153d95f51 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -39,6 +39,104 @@
"crates/remote_env_var",
"crates/workspace-hack"
],
+ "agent_egress": [
+ "crates/activity",
+ "crates/agent",
+ "crates/agent_egress",
+ "crates/agent_fold",
+ "crates/agent_runtime_protocol",
+ "crates/agent_session",
+ "crates/ai_toolset",
+ "crates/ai_usage",
+ "crates/attachment",
+ "crates/authentication_service_client",
+ "crates/bot_id",
+ "crates/bot_token",
+ "crates/bots",
+ "crates/broadcast",
+ "crates/call",
+ "crates/channel_sender",
+ "crates/channels",
+ "crates/connection",
+ "crates/connection_gateway_client",
+ "crates/connection_gateway_models",
+ "crates/contacts",
+ "crates/cowlike",
+ "crates/crm",
+ "crates/document_sub_type",
+ "crates/documents",
+ "crates/email",
+ "crates/email_utils",
+ "crates/embedding",
+ "crates/entity_access",
+ "crates/entity_access_db_utils",
+ "crates/entity_access_management",
+ "crates/entity_mutation",
+ "crates/filter_ast",
+ "crates/foreign_entity",
+ "crates/frecency",
+ "crates/fusionauth",
+ "crates/github",
+ "crates/invite_email",
+ "crates/item_filters",
+ "crates/kafka_util",
+ "crates/last_online_tracker",
+ "crates/lexical_client",
+ "crates/macro_auth",
+ "crates/macro_authorization",
+ "crates/macro_aws_config",
+ "crates/macro_db_client",
+ "crates/macro_entrypoint",
+ "crates/macro_env",
+ "crates/macro_env_var",
+ "crates/macro_event_broker",
+ "crates/macro_event_topics",
+ "crates/macro_service_urls",
+ "crates/macro_sync_service_jwt",
+ "crates/macro_tower_layers",
+ "crates/macro_user_id",
+ "crates/macro_uuid",
+ "crates/mention_utils",
+ "crates/model",
+ "crates/model-entity",
+ "crates/model-error-response",
+ "crates/model_file_type",
+ "crates/model_notifications",
+ "crates/model_user",
+ "crates/models_bulk_upload",
+ "crates/models_dcs",
+ "crates/models_entity_access_management",
+ "crates/models_opensearch",
+ "crates/models_pagination",
+ "crates/models_permissions",
+ "crates/models_properties",
+ "crates/models_search",
+ "crates/models_search_cursor",
+ "crates/models_soup",
+ "crates/models_team",
+ "crates/non_empty",
+ "crates/notification",
+ "crates/opensearch_client",
+ "crates/opensearch_query_builder",
+ "crates/pipedream_mcp",
+ "crates/prompt",
+ "crates/properties",
+ "crates/rate_limit",
+ "crates/reminders",
+ "crates/remote_env_var",
+ "crates/s3_key",
+ "crates/secretsmanager_client",
+ "crates/share_permission_db_utils",
+ "crates/sqs_worker",
+ "crates/sync_service",
+ "crates/sync_service_client",
+ "crates/system_properties",
+ "crates/system_skills",
+ "crates/task_dedup",
+ "crates/unfurl",
+ "crates/user_quota",
+ "crates/workspace-hack"
+ ],
"agent_fold": [
"crates/agent_fold",
"crates/agent_runtime_protocol",
@@ -50,6 +148,7 @@
"agent_harness": [
"crates/activity",
"crates/agent",
+ "crates/agent_egress",
"crates/agent_fold",
"crates/agent_harness",
"crates/agent_runtime_protocol",
@@ -75,14 +174,19 @@
"crates/cursor_api_key",
"crates/cursor_cloud_agents",
"crates/document_sub_type",
+ "crates/documents",
"crates/email",
"crates/email_utils",
+ "crates/embedding",
"crates/entity_access",
"crates/entity_access_db_utils",
"crates/entity_access_management",
"crates/entity_mutation",
"crates/filter_ast",
+ "crates/foreign_entity",
"crates/frecency",
+ "crates/fusionauth",
+ "crates/github",
"crates/invite_email",
"crates/item_filters",
"crates/kafka_util",
@@ -91,11 +195,14 @@
"crates/macro_auth",
"crates/macro_authorization",
"crates/macro_aws_config",
+ "crates/macro_db_client",
+ "crates/macro_entrypoint",
"crates/macro_env",
"crates/macro_env_var",
"crates/macro_event_broker",
"crates/macro_event_topics",
"crates/macro_service_urls",
+ "crates/macro_sync_service_jwt",
"crates/macro_tower_layers",
"crates/macro_user_id",
"crates/macro_uuid",
@@ -107,6 +214,7 @@
"crates/model_notifications",
"crates/model_user",
"crates/models_bulk_upload",
+ "crates/models_dcs",
"crates/models_entity_access_management",
"crates/models_opensearch",
"crates/models_pagination",
@@ -115,24 +223,34 @@
"crates/models_search",
"crates/models_search_cursor",
"crates/models_soup",
+ "crates/models_team",
"crates/non_empty",
"crates/notification",
"crates/opensearch_client",
"crates/opensearch_query_builder",
+ "crates/pipedream_mcp",
"crates/prompt",
"crates/properties",
"crates/rate_limit",
"crates/reminders",
"crates/remote_env_var",
+ "crates/s3_key",
+ "crates/secretsmanager_client",
"crates/share_permission_db_utils",
"crates/sqs_worker",
+ "crates/sync_service",
+ "crates/sync_service_client",
"crates/system_properties",
+ "crates/system_skills",
+ "crates/task_dedup",
"crates/unfurl",
+ "crates/user_quota",
"crates/workspace-hack"
],
"agent_harness_service": [
"crates/activity",
"crates/agent",
+ "crates/agent_egress",
"crates/agent_fold",
"crates/agent_harness",
"crates/agent_inmem",
@@ -178,7 +296,9 @@
"crates/filter_ast",
"crates/foreign_entity",
"crates/frecency",
+ "crates/fusionauth",
"crates/generic_email_domains",
+ "crates/github",
"crates/import",
"crates/invite_email",
"crates/item_filters",
diff --git a/.sqlx/query-0f26267379d1fe3337f14aa30959204ac2d89c9acbe728426c199bde4b41eda7.json b/.sqlx/query-0f26267379d1fe3337f14aa30959204ac2d89c9acbe728426c199bde4b41eda7.json
new file mode 100644
index 0000000000..79b97d7820
--- /dev/null
+++ b/.sqlx/query-0f26267379d1fe3337f14aa30959204ac2d89c9acbe728426c199bde4b41eda7.json
@@ -0,0 +1,142 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n SELECT\n id, name, owner_id, thread_id, originating_message_id, bot_id,\n model, harness, repo_url, workspace, sandbox_size, acp_session_id, status,\n status_event_name, agent_session.created_at, modified_at,\n (SELECT channel_id FROM comms_messages WHERE id = agent_session.thread_id)\n AS \"thread_channel_id?\",\n ext.provider AS \"external_provider?\", ext.external_id AS \"external_id?\",\n ext.external_name AS \"external_name?\", ext.external_url AS \"external_url?\"\n FROM agent_session\n LEFT JOIN external_agent_session AS ext ON ext.agent_session_id = agent_session.id\n WHERE egress_token_hash = $1\n ",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 1,
+ "name": "name",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 2,
+ "name": "owner_id",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 3,
+ "name": "thread_id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 4,
+ "name": "originating_message_id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 5,
+ "name": "bot_id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 6,
+ "name": "model",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 7,
+ "name": "harness",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 8,
+ "name": "repo_url",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 9,
+ "name": "workspace",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 10,
+ "name": "sandbox_size",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 11,
+ "name": "acp_session_id",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 12,
+ "name": "status",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 13,
+ "name": "status_event_name",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 14,
+ "name": "created_at",
+ "type_info": "Timestamptz"
+ },
+ {
+ "ordinal": 15,
+ "name": "modified_at",
+ "type_info": "Timestamptz"
+ },
+ {
+ "ordinal": 16,
+ "name": "thread_channel_id?",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 17,
+ "name": "external_provider?",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 18,
+ "name": "external_id?",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 19,
+ "name": "external_name?",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 20,
+ "name": "external_url?",
+ "type_info": "Text"
+ }
+ ],
+ "parameters": {
+ "Left": [
+ "Text"
+ ]
+ },
+ "nullable": [
+ false,
+ false,
+ false,
+ true,
+ true,
+ false,
+ false,
+ false,
+ true,
+ false,
+ false,
+ true,
+ false,
+ true,
+ false,
+ false,
+ null,
+ false,
+ false,
+ true,
+ true
+ ]
+ },
+ "hash": "0f26267379d1fe3337f14aa30959204ac2d89c9acbe728426c199bde4b41eda7"
+}
diff --git a/.sqlx/query-f634845737b7046901568d7847ebcfb54bfcbdfffe26953fe0732579987f4d2e.json b/.sqlx/query-71e4d8840c1d337af853e4b6d6d25ccf7f6126ff9d96105b04868a5367ad8b92.json
similarity index 75%
rename from .sqlx/query-f634845737b7046901568d7847ebcfb54bfcbdfffe26953fe0732579987f4d2e.json
rename to .sqlx/query-71e4d8840c1d337af853e4b6d6d25ccf7f6126ff9d96105b04868a5367ad8b92.json
index cc431b84db..368d0560ab 100644
--- a/.sqlx/query-f634845737b7046901568d7847ebcfb54bfcbdfffe26953fe0732579987f4d2e.json
+++ b/.sqlx/query-71e4d8840c1d337af853e4b6d6d25ccf7f6126ff9d96105b04868a5367ad8b92.json
@@ -1,6 +1,6 @@
{
"db_name": "PostgreSQL",
- "query": "\n INSERT INTO agent_session (\n id, owner_id, thread_id, originating_message_id, bot_id, model,\n harness, repo_url, workspace, sandbox_size, acp_session_id, status,\n status_event_name\n )\n VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)\n RETURNING\n id, name, owner_id, thread_id, originating_message_id, bot_id,\n model, harness, repo_url, workspace, sandbox_size, acp_session_id, status,\n status_event_name, created_at, modified_at,\n (SELECT channel_id FROM comms_messages WHERE id = agent_session.thread_id)\n AS \"thread_channel_id?\",\n -- A row being created cannot have an external identity yet.\n NULL::TEXT AS \"external_provider?\", NULL::TEXT AS \"external_id?\",\n NULL::TEXT AS \"external_name?\", NULL::TEXT AS \"external_url?\"\n ",
+ "query": "\n INSERT INTO agent_session (\n id, owner_id, thread_id, originating_message_id, bot_id, model,\n harness, repo_url, workspace, sandbox_size, acp_session_id, status,\n status_event_name, egress_token_hash\n )\n VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)\n RETURNING\n id, name, owner_id, thread_id, originating_message_id, bot_id,\n model, harness, repo_url, workspace, sandbox_size, acp_session_id, status,\n status_event_name, created_at, modified_at,\n (SELECT channel_id FROM comms_messages WHERE id = agent_session.thread_id)\n AS \"thread_channel_id?\",\n -- A row being created cannot have an external identity yet.\n NULL::TEXT AS \"external_provider?\", NULL::TEXT AS \"external_id?\",\n NULL::TEXT AS \"external_name?\", NULL::TEXT AS \"external_url?\"\n ",
"describe": {
"columns": [
{
@@ -123,6 +123,7 @@
"Text",
"Text",
"Text",
+ "Text",
"Text"
]
},
@@ -150,5 +151,5 @@
null
]
},
- "hash": "f634845737b7046901568d7847ebcfb54bfcbdfffe26953fe0732579987f4d2e"
+ "hash": "71e4d8840c1d337af853e4b6d6d25ccf7f6126ff9d96105b04868a5367ad8b92"
}
diff --git a/Cargo.lock b/Cargo.lock
index 50e30de2d5..b916e40f04 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -168,6 +168,42 @@ dependencies = [
"tracing",
]
+[[package]]
+name = "agent_egress"
+version = "0.1.0"
+dependencies = [
+ "agent_fold",
+ "agent_runtime_protocol",
+ "agent_session",
+ "anyhow",
+ "axum",
+ "axum-extra",
+ "base64 0.22.1",
+ "bytes",
+ "chrono",
+ "github",
+ "http 1.4.0",
+ "http-body-util",
+ "lru",
+ "macro_auth",
+ "macro_db_client",
+ "macro_user_id",
+ "pipedream_mcp",
+ "rand 0.9.4",
+ "reqwest 0.13.4",
+ "rootcause",
+ "serde",
+ "serde_json",
+ "sha2 0.10.9",
+ "sqlx",
+ "thiserror 2.0.18",
+ "tokio",
+ "tower 0.5.3",
+ "tracing",
+ "url",
+ "workspace-hack",
+]
+
[[package]]
name = "agent_fold"
version = "0.1.0"
@@ -199,6 +235,7 @@ name = "agent_harness"
version = "0.1.0"
dependencies = [
"agent-client-protocol",
+ "agent_egress",
"agent_fold",
"agent_runtime_protocol",
"agent_session",
@@ -224,6 +261,7 @@ dependencies = [
"macro_user_id",
"macro_uuid",
"mockall",
+ "pipedream_mcp",
"reqwest 0.13.4",
"rootcause",
"rustls 0.23.40",
@@ -243,6 +281,7 @@ dependencies = [
name = "agent_harness_service"
version = "0.1.0"
dependencies = [
+ "agent_egress",
"agent_fold",
"agent_harness",
"agent_inmem",
@@ -265,6 +304,7 @@ dependencies = [
"cursor_cloud_agents",
"database_env_vars",
"entity_access",
+ "github",
"kafka_util",
"lexical_client",
"macro_auth",
@@ -282,6 +322,7 @@ dependencies = [
"macro_user_id",
"macro_uuid",
"notification",
+ "pipedream_mcp",
"rdkafka",
"secretsmanager_client",
"serde",
@@ -290,6 +331,7 @@ dependencies = [
"tokio",
"tokio-util",
"tracing",
+ "url",
"utoipa",
"utoipa-swagger-ui",
"workspace-hack",
@@ -12026,6 +12068,7 @@ dependencies = [
"thiserror 2.0.18",
"tokio",
"tracing",
+ "url",
"utoipa",
"workspace-hack",
]
diff --git a/Cargo.toml b/Cargo.toml
index 93b7678dd5..2234ec3238 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -3,7 +3,7 @@ resolver = "2"
members = [
"crates/activity",
- "crates/agent", "crates/agent_fold",
+ "crates/agent", "crates/agent_egress", "crates/agent_fold",
"crates/agent_harness",
"crates/agent_inmem",
"crates/agent_runtime_protocol", "crates/agent_session",
diff --git a/crates/agent_egress/Cargo.toml b/crates/agent_egress/Cargo.toml
new file mode 100644
index 0000000000..1db3eb7ce7
--- /dev/null
+++ b/crates/agent_egress/Cargo.toml
@@ -0,0 +1,54 @@
+[package]
+edition = "2024"
+name = "agent_egress"
+publish = false
+version = "0.1.0"
+
+[dependencies]
+# `AgentSessionId` only. `default-features = false` drops the crate's CLI
+# binaries (clap, tokio), which the vocabulary does not need.
+agent_fold = { path = "../agent_fold", default-features = false }
+agent_runtime_protocol = { path = "../agent_runtime_protocol" }
+agent_session = { path = "../agent_session" }
+axum = { workspace = true }
+# `headers`' typed `Authorization`, which owns the Bearer/Basic parsing the
+# session-token extraction would otherwise hand-roll.
+axum-extra = { workspace = true, features = ["typed-header"] }
+base64 = { workspace = true }
+bytes = { workspace = true }
+chrono = { workspace = true }
+# The installation records that say whose installation an installation is, and
+# the team memberships that decide whether the session's owner is one of them.
+github = { path = "../github", default-features = false, features = [
+ "outbound",
+ "ports",
+ "sync",
+] }
+http = { workspace = true }
+http-body-util = { workspace = true }
+lru = { workspace = true }
+# Signing Macro API tokens, with the same shared vocabulary
+# `authentication_service` mints through.
+macro_auth = { path = "../macro_auth" }
+# The owner's `User` row, which carries the FusionAuth id the exchange needs.
+macro_db_client = { path = "../macro_db_client" }
+macro_user_id = { path = "../macro_user_id" }
+# The rows saying which apps an owner connected, and the client that turns one
+# into Pipedream's MCP endpoint plus the headers scoping a call to it.
+pipedream_mcp = { path = "../pipedream_mcp" }
+rand = { workspace = true }
+reqwest = { workspace = true }
+rootcause = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+sqlx = { workspace = true }
+sha2 = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+url = { workspace = true }
+workspace-hack = { version = "0.1", path = "../workspace-hack" }
+
+[dev-dependencies]
+anyhow = { workspace = true }
+tokio = { workspace = true, features = ["macros", "rt"] }
+tower = { workspace = true }
diff --git a/crates/agent_egress/src/domain/error.rs b/crates/agent_egress/src/domain/error.rs
new file mode 100644
index 0000000000..8dd05aee55
--- /dev/null
+++ b/crates/agent_egress/src/domain/error.rs
@@ -0,0 +1,75 @@
+//! Failures a proxied call can end in.
+
+use crate::domain::model::{McpServerSlug, RepoSlug};
+
+/// Everything that can stop a sandbox's request from reaching its upstream.
+///
+/// The variants are separated by what the caller should *do*, not by where
+/// they arose: a sandbox that gets [`EgressError::UnknownServer`] should stop
+/// dialling that slug, whereas one that gets [`EgressError::Upstream`] should
+/// retry. Collapsing them would leave the agent guessing, and an agent that
+/// guesses retries until its turn times out.
+#[derive(Debug, thiserror::Error)]
+pub enum EgressError {
+ /// The request is not entitled to egress: no token, a token we do not
+ /// know, or an owner the proxy does not admit.
+ ///
+ /// The reason is a `&'static str` on purpose: it names which gate
+ /// refused, in our own fixed words, and can never quote anything the
+ /// request carried - the response body rule (nothing request-derived
+ /// reaches the model) holds by construction.
+ #[error("not authorized: {0}")]
+ Unauthenticated(&'static str),
+
+ /// The token verified, but its session is closed or gone. Ending a
+ /// session revokes its egress without waiting for the token to expire.
+ #[error("session is no longer open")]
+ SessionClosed,
+
+ /// The request's path did not name anything this service serves - a slug
+ /// that is not a slug, a repository path that is not one, a git endpoint
+ /// outside the allowlist. Kept separate from
+ /// [`EgressError::UnknownServer`] so the domain never has to invent a
+ /// name for something that failed to parse.
+ #[error("nothing is served at that path: {0}")]
+ Unroutable(String),
+
+ /// The owner has no server under this slug. Also covers a server the
+ /// owner has since disabled or disconnected: from the sandbox's side
+ /// those are the same fact, and distinguishing them would report on the
+ /// owner's settings to code the model wrote.
+ #[error("no connected MCP server named {0}")]
+ UnknownServer(McpServerSlug),
+
+ /// We cannot mint a credential for the session's repository: our GitHub
+ /// App is not installed on it, or the installation belongs to somebody
+ /// with no connection to the session's owner. Not a refusal of anything
+ /// the sandbox asked for - it never names a repository - but of the
+ /// session's own configuration.
+ #[error("no usable GitHub App installation for {0}")]
+ RepoUnavailable(RepoSlug),
+
+ /// The destination a credential was about to be stamped for is not
+ /// https. Refused rather than downgraded: an MCP server's URL is typed in
+ /// by a person, and stamping the owner's OAuth token onto a cleartext
+ /// request would put that credential on the wire for anyone on the path to
+ /// take.
+ #[error("refusing to send a credential to {0} in cleartext")]
+ InsecureUpstream(url::Url),
+
+ /// A verb these routes have no use for. Refused rather than forwarded,
+ /// so adding a route that needs one has to say so.
+ #[error("method {0} is not allowed here")]
+ MethodNotAllowed(http::Method),
+
+ /// The upstream could not be reached, or answered in a way that broke
+ /// the exchange. A non-2xx *status* is not this - statuses pass through
+ /// to the caller untouched, because MCP and git both use them
+ /// semantically.
+ #[error("upstream request failed: {0}")]
+ Upstream(rootcause::Report),
+
+ /// Our side broke: storage, decryption, configuration.
+ #[error("egress failed: {0}")]
+ Internal(rootcause::Report),
+}
diff --git a/crates/agent_egress/src/domain/mod.rs b/crates/agent_egress/src/domain/mod.rs
new file mode 100644
index 0000000000..024cc230b7
--- /dev/null
+++ b/crates/agent_egress/src/domain/mod.rs
@@ -0,0 +1,11 @@
+//! The domain: what a session may reach, and with whose credentials.
+
+/// Failures a proxied call can end in.
+pub mod error;
+/// Vocabulary: grants, slugs, targets, and the transport-neutral request and
+/// response the service passes through.
+pub mod model;
+/// The capabilities the service needs from the outside.
+pub mod ports;
+/// The service itself.
+pub mod service;
diff --git a/crates/agent_egress/src/domain/model.rs b/crates/agent_egress/src/domain/model.rs
new file mode 100644
index 0000000000..2df692d26e
--- /dev/null
+++ b/crates/agent_egress/src/domain/model.rs
@@ -0,0 +1,705 @@
+//! Vocabulary: grants, slugs, targets, and the request rules the service
+//! applies on the way through.
+//!
+//! The requests and responses themselves are `http::Request` and
+//! `http::Response`. `http` is a vocabulary crate - types, no I/O, no
+//! runtime, no server - which is why axum, reqwest, hyper and tower all
+//! agree on it, and why using it here does not drag transport into the
+//! domain. The alternative, hand-rolled header and method types, would mean
+//! reimplementing case-insensitive lookup and header-value validation badly,
+//! and converting at both edges for the privilege.
+
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD as BASE64URL_NO_PAD;
+use bytes::Bytes;
+use http::header::{self, HeaderMap, HeaderName};
+use http::{HeaderValue, Method};
+use http_body_util::combinators::UnsyncBoxBody;
+use macro_user_id::email::ReadEmailParts;
+use macro_user_id::user_id::MacroUserIdStr;
+use rand::RngCore;
+use sha2::{Digest, Sha256};
+use std::fmt;
+use url::Url;
+
+use crate::domain::error::EgressError;
+
+pub use agent_fold::domain::log::AgentSessionId;
+
+#[cfg(test)]
+mod test;
+
+/// Whatever a body failed with. Type-erased because the domain neither
+/// produces these nor inspects them - it carries a body from one adapter to
+/// another.
+pub type BoxError = Box<dyn std::error::Error + Send + Sync>;
+
+/// A streaming body, in either direction.
+///
+/// Streamed rather than collected because both things this carries are
+/// unbounded: MCP replies arrive as server-sent events that stay open for
+/// the life of a tool call, and git's packfiles are as big as the
+/// repository. Buffering either would turn a working proxy into a memory
+/// leak.
+///
+/// A boxed `http_body::Body` rather than a bare stream because it is what
+/// both edges already are: axum's body is exactly this shape, and reqwest's
+/// response converts straight into `http::Response<reqwest::Body>`.
+///
+/// `UnsyncBoxBody` specifically, matching axum: a body is polled from one
+/// task, so `Sync` buys nothing, and requiring it would mean wrapping every
+/// request that comes in off the wire.
+pub type ProxyBody = UnsyncBoxBody<Bytes, BoxError>;
+
+/// A request on its way through.
+pub type ProxyRequest = http::Request<ProxyBody>;
+
+/// A response on its way back.
+pub type ProxyResponse = http::Response<ProxyBody>;
+
+/// The one secret a sandbox holds: proof that it is running a given session.
+///
+/// Opaque, and opaque all the way down: the token asserts nothing and is worth
+/// exactly the row it is stored against. What a request may do comes from that
+/// row, so there is no claim to drift out of step with the session and nothing
+/// to sign or verify.
+///
+/// The value itself exists in two places and no others - the sandbox's
+/// environment, and the response of the call that put it there. What is
+/// persisted is [`SessionToken::hash`].
+#[derive(Clone, PartialEq, Eq)]
+pub struct SessionToken(String);
+
+/// How many bytes of randomness a minted token carries.
+///
+/// 256 bits, which is the point past which guessing is not the attack anyone
+/// would try.
+const TOKEN_BYTES: usize = 32;
+
+impl SessionToken {
+ /// Wrap a token presented by a sandbox.
+ pub fn new(token: impl Into<String>) -> Self {
+ Self(token.into())
+ }
+
+ /// A fresh token for a sandbox about to be spawned.
+ ///
+ /// Unpredictability is the entire security property - there is no
+ /// signature backing it up - so this draws from a cryptographically secure
+ /// generator seeded by the operating system, never a reproducible one.
+ pub fn mint() -> Self {
+ let mut bytes = [0u8; TOKEN_BYTES];
+ rand::rng().fill_bytes(&mut bytes);
+ Self(BASE64URL_NO_PAD.encode(bytes))
+ }
+
+ /// The SHA-256 hash of this token, lowercase hex.
+ ///
+ /// What gets stored against a session, and what a presented token is
+ /// looked up by. Storing the hash rather than the token is what keeps a
+ /// database dump from yielding live credentials; the token has 256 bits of
+ /// entropy, so there is nothing for a rainbow table to precompute and
+ /// nothing a salt would add.
+ pub fn hash(&self) -> String {
+ Sha256::digest(self.0.as_bytes())
+ .iter()
+ .map(|byte| format!("{byte:02x}"))
+ .collect()
+ }
+
+ /// The token as presented.
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+// Redacted: a proxy logs every request it handles, and the credential is on
+// every one of them.
+impl fmt::Debug for SessionToken {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.write_str("SessionToken([REDACTED])")
+ }
+}
+
+/// An upstream credential, resolved on the owner's behalf and never seen by
+/// the sandbox.
+#[derive(Clone, PartialEq, Eq)]
+pub struct BearerToken(String);
+
+impl BearerToken {
+ /// Wrap a token obtained for an upstream.
+ pub fn new(token: impl Into<String>) -> Self {
+ Self(token.into())
+ }
+
+ /// The token itself.
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+impl fmt::Debug for BearerToken {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.write_str("BearerToken([REDACTED])")
+ }
+}
+
+/// How an upstream wants to be told who is calling.
+///
+/// Two shapes because two upstreams disagree: MCP servers take an OAuth
+/// bearer, and GitHub's git endpoints take Basic with the installation token
+/// as the *password* - git's credential helper protocol has no other way to
+/// carry one.
+#[derive(Clone, PartialEq, Eq)]
+pub enum UpstreamCredential {
+ /// `Authorization: Bearer <token>`.
+ Bearer(BearerToken),
+ /// `Authorization: Basic base64(username:secret)`.
+ Basic {
+ /// The user half, which GitHub ignores beyond requiring one.
+ username: String,
+ /// The password half - the credential proper.
+ secret: String,
+ },
+}
+
+impl UpstreamCredential {
+ /// This credential as an `Authorization` header value, marked sensitive
+ /// so the http stack keeps it out of its own logging.
+ ///
+ /// The single place a credential becomes a header, so it is also the
+ /// single place validation happens: a secret carrying a newline could
+ /// otherwise inject a header of its own choosing into the upstream
+ /// request, and `HeaderValue` is what refuses it.
+ pub fn header_value(&self) -> Result<HeaderValue, EgressError> {
+ let rendered = match self {
+ Self::Bearer(token) => format!("Bearer {}", token.as_str()),
+ Self::Basic { username, secret } => {
+ format!("Basic {}", BASE64.encode(format!("{username}:{secret}")))
+ }
+ };
+
+ let mut value = HeaderValue::from_str(&rendered).map_err(|error| {
+ EgressError::Internal(rootcause::report!(
+ "upstream credential is not a header value: {error}"
+ ))
+ })?;
+ value.set_sensitive(true);
+ Ok(value)
+ }
+}
+
+impl fmt::Debug for UpstreamCredential {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match self {
+ Self::Bearer(_) => f.write_str("Bearer([REDACTED])"),
+ Self::Basic { username, .. } => write!(f, "Basic({username}, [REDACTED])"),
+ }
+ }
+}
+
+/// The email domain Macro staff live under.
+const STAFF_EMAIL_DOMAIN: &str = "macro.com";
+
+/// Whether a user belongs to the Macro staff domain.
+///
+/// The proxy is staff-only for now: every credential it stamps spends real
+/// upstream access on the owner's behalf, and until that has earned broader
+/// trust, "owned by somebody @macro.com" is the whole admission policy. In
+/// the domain rather than deployment configuration so it cannot be switched
+/// off by an unset env var.
+pub fn is_macro_staff(user: &MacroUserIdStr<'_>) -> bool {
+ user.email_part().domain_part() == STAFF_EMAIL_DOMAIN
+}
+
+/// What a verified session token entitles its holder to.
+///
+/// The owner is the whole authorization story: a session spends the
+/// credentials of the person who opened it, and nobody else's.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SessionGrant {
+ /// The session the sandbox is running.
+ pub session: AgentSessionId,
+ /// Whose connected servers it may reach.
+ pub owner: MacroUserIdStr<'static>,
+ /// The one repository this session works on. Git egress is pinned to it.
+ pub repo: RepoSlug,
+}
+
+/// A GitHub repository, as `owner/name`.
+///
+/// Never parsed from a request: the sandbox does not name a repository, its
+/// session does, and this is read off the session's row. That makes the two
+/// segments our own configuration rather than sandbox input - but they still
+/// get interpolated into a URL, so parsing them is what keeps a mistyped
+/// repository from becoming a request somewhere else entirely.
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct RepoSlug {
+ owner: String,
+ name: String,
+}
+
+/// The only host a configured repository URL may name.
+///
+/// A URL pointing anywhere else would name a repository this proxy has no
+/// installation for and could not reach, so it is a configuration error rather
+/// than a repository.
+const GITHUB_HOST: &str = "github.com";
+
+impl RepoSlug {
+ /// The repository a configured GitHub URL names.
+ ///
+ /// Deliberately narrow: it must be `https://github.com/<owner>/<name>`,
+ /// optionally with `.git` or a trailing slash, and nothing else. Both ends
+ /// of a session read the same `repo_url` column - the harness to mint a
+ /// sandbox's token, the proxy to decide which repository that sandbox's
+ /// git traffic may reach - so a second, laxer reading of it in one of them
+ /// would be a way for the two to disagree about which repository a session
+ /// is. A URL that is nearly right is a configuration mistake worth failing
+ /// on rather than guessing at.
+ pub fn parse_github_url(repository_url: &str) -> Option<Self> {
+ let url = Url::parse(repository_url).ok()?;
+ if url.host_str() != Some(GITHUB_HOST) {
+ return None;
+ }
+
+ let mut segments = url.path_segments()?;
+ let owner = segments.next()?;
+ let name = segments.next()?;
+ // Anything after the repository name is not part of it. A trailing
+ // empty segment is just a trailing slash.
+ if segments.any(|segment| !segment.is_empty()) {
+ return None;
+ }
+
+ Self::parse(owner, name.trim_end_matches(".git"))
+ }
+
+ /// Accept an owner and repository name read off a session's row.
+ ///
+ /// The charset is `[A-Za-z0-9._-]`, and the exclusions are the substance:
+ /// these two segments get interpolated into
+ /// `https://github.com/{owner}/{name}.git/`, so a segment containing `/`,
+ /// `?`, `#`, `@` or `%` would not be a segment - it would be a path of its
+ /// own, a query string, a fragment, URL userinfo, or an encoded version of
+ /// any of those - and `@` in particular is what stops a claim value
+ /// rewriting the URL's host through userinfo. Rejecting `.` and `..`
+ /// outright closes the one traversal the charset alone still permits.
+ pub fn parse(owner: &str, name: &str) -> Option<Self> {
+ let acceptable = |segment: &str| {
+ !segment.is_empty()
+ && segment != "."
+ && segment != ".."
+ && segment.chars().all(|character| {
+ character.is_ascii_alphanumeric()
+ || character == '.'
+ || character == '_'
+ || character == '-'
+ })
+ };
+
+ (acceptable(owner) && acceptable(name)).then(|| Self {
+ owner: owner.to_owned(),
+ name: name.to_owned(),
+ })
+ }
+
+ /// The account or organization the repository lives under.
+ pub fn owner(&self) -> &str {
+ &self.owner
+ }
+
+ /// The repository's own name, without the owner.
+ pub fn name(&self) -> &str {
+ &self.name
+ }
+}
+
+impl fmt::Display for RepoSlug {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(f, "{}/{}", self.owner, self.name)
+ }
+}
+
+/// The identifier a sandbox calls one of its owner's connected MCP servers by:
+/// the Pipedream `app_slug`, verbatim.
+///
+/// Not derived from anything. Pipedream's app slug is already a stable,
+/// URL-safe machine identifier (`google_drive`, `datadog`), so both ends use
+/// it as-is: the provisioner advertises it in the session's server list and
+/// the credential resolver matches it against the owner's rows by equality.
+/// Nothing is normalized, so no two servers can ever meet at one name.
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct McpServerSlug(String);
+
+impl McpServerSlug {
+ /// Accept a slug from a request path or a connection row.
+ ///
+ /// Rejects rather than repairs: the path-segment side of this is chosen
+ /// by code the model wrote, and a slug that gets "cleaned up" into a
+ /// different valid slug is a way to ask for a server other than the one
+ /// named. The charset is Pipedream's own for app slugs.
+ pub fn parse(segment: &str) -> Option<Self> {
+ let valid = !segment.is_empty()
+ && segment.chars().all(|character| {
+ character.is_ascii_lowercase()
+ || character.is_ascii_digit()
+ || character == '-'
+ || character == '_'
+ });
+
+ valid.then(|| Self(segment.to_owned()))
+ }
+
+ /// The slug as it appears in a path and in the session's server list.
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+impl fmt::Display for McpServerSlug {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.write_str(&self.0)
+ }
+}
+
+/// Which half of git's smart-HTTP protocol a request is doing.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum GitService {
+ /// Reading: clone and fetch.
+ UploadPack,
+ /// Writing: push.
+ ReceivePack,
+}
+
+impl GitService {
+ /// The name git uses for this service on the wire.
+ pub fn as_str(&self) -> &'static str {
+ match self {
+ Self::UploadPack => "git-upload-pack",
+ Self::ReceivePack => "git-receive-pack",
+ }
+ }
+
+ fn parse(name: &str) -> Option<Self> {
+ match name {
+ "git-upload-pack" => Some(Self::UploadPack),
+ "git-receive-pack" => Some(Self::ReceivePack),
+ _ => None,
+ }
+ }
+}
+
+/// The git endpoints a sandbox may reach.
+///
+/// An allowlist of the three smart-HTTP routes, which is also what shuts off
+/// the dumb-HTTP object endpoints (`objects/…`, `info/packs`): those serve
+/// loose objects and packs by name, so a client that can walk them can read
+/// history the smart protocol would have negotiated away, and they are
+/// unnecessary against GitHub, which always speaks smart HTTP.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum GitEndpoint {
+ /// The reference advertisement that opens every clone, fetch, and push.
+ InfoRefs {
+ /// Which service the client is about to run.
+ service: GitService,
+ },
+ /// The fetch negotiation and packfile.
+ UploadPack,
+ /// The push negotiation and packfile.
+ ReceivePack,
+}
+
+impl GitEndpoint {
+ /// Recognize an endpoint from the path after `<owner>/<repo>.git/` and
+ /// the request's query string.
+ ///
+ /// Rejects rather than repairs, and rejects a mismatch too: `info/refs`
+ /// without a recognized `service` query is the dumb protocol's entry
+ /// point, so it is not an endpoint we serve.
+ pub fn parse(path: &str, query: Option<&str>) -> Option<Self> {
+ match path {
+ "info/refs" => {
+ let service = query?
+ .split('&')
+ .find_map(|pair| pair.strip_prefix("service="))?;
+ Some(Self::InfoRefs {
+ service: GitService::parse(service)?,
+ })
+ }
+ "git-upload-pack" => Some(Self::UploadPack),
+ "git-receive-pack" => Some(Self::ReceivePack),
+ _ => None,
+ }
+ }
+
+ /// The path and query this endpoint appends to a repository's git URL.
+ pub fn path_and_query(&self) -> String {
+ match self {
+ Self::InfoRefs { service } => format!("info/refs?service={}", service.as_str()),
+ Self::UploadPack => "git-upload-pack".to_owned(),
+ Self::ReceivePack => "git-receive-pack".to_owned(),
+ }
+ }
+}
+
+/// Where a proxied request is headed.
+///
+/// An enum rather than a URL because the sandbox never supplies a
+/// destination - it names something, and this crate decides what that
+/// resolves to.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum EgressTarget {
+ /// An MCP server the session may dial.
+ McpServer(McpDestination),
+ /// A git operation against the session's own repository.
+ ///
+ /// Carries no repository: the session has exactly one, and it comes from
+ /// the grant. There is nothing here for a sandbox to name, so there is
+ /// nothing to check.
+ GitHubGit {
+ /// Which of the three smart-HTTP routes.
+ endpoint: GitEndpoint,
+ },
+}
+
+impl EgressTarget {
+ /// What to call this target in a log line.
+ pub fn name(&self) -> String {
+ match self {
+ Self::McpServer(McpDestination::Macro) => "macro".to_owned(),
+ Self::McpServer(McpDestination::Connected(slug)) => slug.as_str().to_owned(),
+ Self::GitHubGit { endpoint } => format!("git {}", endpoint.path_and_query()),
+ }
+ }
+}
+
+/// Which MCP server a request names.
+///
+/// Macro's own server and the owner's connected apps live on different
+/// routes (`/mcp-macro` vs `/mcp/{slug}`), so they can never collide: there
+/// is no reserved word to shadow, and no connected app a name could hide.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum McpDestination {
+ /// Macro's own MCP server, available to every session.
+ Macro,
+ /// One of the owner's Pipedream-connected apps.
+ Connected(McpServerSlug),
+}
+
+/// A resolved destination and the credential to reach it with.
+///
+/// The fields are private and the constructors validate, so a credential
+/// paired with a destination nobody checked cannot be built. Both upstreams
+/// here are reached over the public internet, and one of the two URLs -
+/// Pipedream's MCP endpoint - is deployment configuration, so "https" is not
+/// an assumption this crate is entitled to make.
+#[derive(Clone, Debug)]
+pub struct UpstreamCall {
+ url: Url,
+ authorization: UpstreamCredential,
+ scope: Vec<(HeaderName, HeaderValue)>,
+}
+
+impl UpstreamCall {
+ /// A call authorized by a bearer token.
+ pub fn bearer(url: Url, token: BearerToken) -> Result<Self, EgressError> {
+ Self::new(url, UpstreamCredential::Bearer(token))
+ }
+
+ /// A call authorized by a bearer token, permitted over cleartext http.
+ ///
+ /// The one sanctioned exception to the https rule, for a destination that
+ /// never leaves the machine: a local dev stack's own Macro MCP server,
+ /// dialed across the compose bridge. TLS there would be theater - the
+ /// bytes never touch a wire anyone else can see - and the alternative,
+ /// looping through a public tunnel for a same-host hop, only *adds* an
+ /// internet round trip to the same cleartext segment.
+ ///
+ /// The composition root must gate every call to this on
+ /// `ENVIRONMENT=local`. It is named this way so a grep for it audits that.
+ pub fn bearer_over_local_cleartext(url: Url, token: BearerToken) -> Self {
+ Self {
+ url,
+ authorization: UpstreamCredential::Bearer(token),
+ scope: Vec::new(),
+ }
+ }
+
+ /// A call authorized by Basic credentials.
+ pub fn basic(
+ url: Url,
+ username: impl Into<String>,
+ secret: impl Into<String>,
+ ) -> Result<Self, EgressError> {
+ Self::new(
+ url,
+ UpstreamCredential::Basic {
+ username: username.into(),
+ secret: secret.into(),
+ },
+ )
+ }
+
+ fn new(url: Url, authorization: UpstreamCredential) -> Result<Self, EgressError> {
+ if url.scheme() != "https" {
+ return Err(EgressError::InsecureUpstream(url));
+ }
+
+ Ok(Self {
+ url,
+ authorization,
+ scope: Vec::new(),
+ })
+ }
+
+ /// The same call with scoping headers attached. Already-typed headers,
+ /// so there is nothing left to validate: a value that could smuggle a
+ /// newline is unrepresentable as a `HeaderValue`, refused wherever the
+ /// adapter built it.
+ ///
+ /// Scoping headers are part of the credential story, not decoration:
+ /// Pipedream decides *whose* connected account a request spends from
+ /// `x-pd-external-user-id` alone, so these pairs must come from the same
+ /// resolution that produced the token - never from the request.
+ #[must_use]
+ pub fn scoped_by(mut self, headers: HeaderMap) -> Self {
+ self.scope.extend(
+ headers
+ .iter()
+ .map(|(name, value)| (name.clone(), value.clone())),
+ );
+ self
+ }
+
+ /// Where the request goes.
+ pub fn url(&self) -> &Url {
+ &self.url
+ }
+
+ /// What gets stamped as `Authorization`.
+ pub fn authorization(&self) -> &UpstreamCredential {
+ &self.authorization
+ }
+
+ /// Headers stamped alongside the credential, scoping what it may spend.
+ pub fn scope_headers(&self) -> &[(HeaderName, HeaderValue)] {
+ &self.scope
+ }
+
+ /// The same call with `url` replaced, revalidated.
+ ///
+ /// Used to append a git endpoint to the repository base an adapter
+ /// returned. Going back through the constructor rather than assigning is
+ /// the point: the replacement is checked exactly as the original was.
+ pub fn redirected_to(self, url: Url) -> Result<Self, EgressError> {
+ let scope = self.scope;
+ let mut call = Self::new(url, self.authorization)?;
+ call.scope = scope;
+ Ok(call)
+ }
+}
+
+/// The methods a sandbox may use.
+///
+/// An allowlist, not a translation of HTTP: MCP's streamable transport POSTs
+/// requests, GETs the event stream, and DELETEs the session when it is done.
+/// Anything else is refused rather than forwarded, so a new route has to say
+/// out loud that it needs a new verb.
+pub fn ensure_method_allowed(method: &Method) -> Result<(), EgressError> {
+ match *method {
+ Method::GET | Method::POST | Method::DELETE => Ok(()),
+ _ => Err(EgressError::MethodNotAllowed(method.clone())),
+ }
+}
+
+/// Headers that must not be forwarded upstream.
+///
+/// Two kinds, and the distinction matters. `authorization` and `cookie` are
+/// the sandbox's own credentials for *us*: forwarding them would hand a
+/// third-party MCP server a token that spends this session's egress. The
+/// rest are hop-by-hop headers, which by definition describe the connection
+/// that just ended, not the one about to begin - `host` most of all, since a
+/// forwarded `host` sends the upstream a name that isn't its own.
+const STRIPPED_REQUEST_HEADERS: &[HeaderName] = &[
+ header::AUTHORIZATION,
+ header::COOKIE,
+ header::HOST,
+ header::CONNECTION,
+ header::PROXY_AUTHENTICATE,
+ header::PROXY_AUTHORIZATION,
+ header::TE,
+ header::TRAILER,
+ header::TRANSFER_ENCODING,
+ header::UPGRADE,
+ header::CONTENT_LENGTH,
+];
+
+/// Headers not to pass back to the sandbox.
+///
+/// The hop-by-hop set again, plus three that are about not handing the
+/// sandbox things it must not have. `set-cookie`: cookies an upstream tries to
+/// set belong to a session between it and this proxy, and letting them reach
+/// the sandbox would leak state the sandbox has no business keeping.
+/// `authorization` and `proxy-authorization`: these are not normally response
+/// headers at all, which is exactly why they are here - an upstream that
+/// echoes back the header it received would hand the owner's credential to
+/// model-authored code, and the whole point of this crate is that the sandbox
+/// never sees one. Not dead weight; do not tidy them away.
+const STRIPPED_RESPONSE_HEADERS: &[HeaderName] = &[
+ header::AUTHORIZATION,
+ header::PROXY_AUTHORIZATION,
+ header::CONNECTION,
+ header::PROXY_AUTHENTICATE,
+ header::TE,
+ header::TRAILER,
+ header::TRANSFER_ENCODING,
+ header::UPGRADE,
+ header::CONTENT_LENGTH,
+ header::SET_COOKIE,
+];
+
+/// The prefix of Pipedream's scoping headers, all of which are stripped in
+/// both directions.
+///
+/// These headers *are* the authorization: `x-pd-external-user-id` alone
+/// decides whose connected account a request spends. The ones this proxy
+/// stamps would overwrite a sandbox's copy anyway; the prefix strip is for
+/// the ones it does not stamp, so a scoping header Pipedream understands and
+/// we have never heard of cannot ride through from model-authored code - and,
+/// on the way back, so an upstream that echoes its scoping metadata does not
+/// report it to the sandbox.
+const STRIPPED_SCOPING_PREFIX: &str = "x-pd-";
+
+/// Drop everything the upstream must not see.
+///
+/// Everything MCP needs to work across a proxy survives: `mcp-session-id`
+/// identifies the server's session, `last-event-id` resumes a dropped event
+/// stream, and `accept` is how a client asks for one.
+pub fn sanitize_request_headers(headers: &mut HeaderMap) {
+ strip(headers, STRIPPED_REQUEST_HEADERS);
+ strip_scoping(headers);
+}
+
+/// Drop everything the sandbox must not see.
+pub fn sanitize_response_headers(headers: &mut HeaderMap) {
+ strip(headers, STRIPPED_RESPONSE_HEADERS);
+ strip_scoping(headers);
+}
+
+fn strip_scoping(headers: &mut HeaderMap) {
+ let scoping: Vec<HeaderName> = headers
+ .keys()
+ .filter(|name| name.as_str().starts_with(STRIPPED_SCOPING_PREFIX))
+ .cloned()
+ .collect();
+ strip(headers, &scoping);
+}
+
+fn strip(headers: &mut HeaderMap, stripped: &[HeaderName]) {
+ for name in stripped {
+ // `remove` takes one; a header sent twice needs draining.
+ while headers.remove(name).is_some() {}
+ }
+}
diff --git a/crates/agent_egress/src/domain/model/test.rs b/crates/agent_egress/src/domain/model/test.rs
new file mode 100644
index 0000000000..4fcfd347d8
--- /dev/null
+++ b/crates/agent_egress/src/domain/model/test.rs
@@ -0,0 +1,378 @@
+use super::*;
+use http::Method;
+
+fn header_map(pairs: &[(&str, &str)]) -> HeaderMap {
+ let mut headers = HeaderMap::new();
+ for (name, value) in pairs {
+ headers.append(
+ HeaderName::from_bytes(name.as_bytes()).expect("header name"),
+ HeaderValue::from_str(value).expect("header value"),
+ );
+ }
+ headers
+}
+
+fn names(headers: &HeaderMap) -> Vec<&str> {
+ headers.keys().map(HeaderName::as_str).collect()
+}
+
+/// A slug is a Pipedream `app_slug`, taken as-is: repairing input would let a
+/// sandbox name one server and reach another, and there is no derivation for
+/// the two ends to disagree over.
+#[test]
+fn parsing_rejects_rather_than_repairs() {
+ assert_eq!(McpServerSlug::parse("Datadog"), None);
+ assert_eq!(McpServerSlug::parse("data dog"), None);
+ assert_eq!(McpServerSlug::parse(""), None);
+ for verbatim in ["datadog-us5", "google_sheets", "linear"] {
+ assert_eq!(
+ McpServerSlug::parse(verbatim).map(|slug| slug.as_str().to_owned()),
+ Some(verbatim.to_owned()),
+ "{verbatim}"
+ );
+ }
+}
+
+/// A slug is a single path segment. Anything that could climb out of one -
+/// dots, slashes, encoded slashes - is not a slug.
+#[test]
+fn parsing_rejects_path_traversal() {
+ for segment in ["..", "../datadog", "datadog/../slack", "datadog%2f..", "."] {
+ assert_eq!(McpServerSlug::parse(segment), None, "accepted {segment}");
+ }
+}
+
+#[test]
+fn allows_only_the_verbs_mcp_speaks() {
+ for method in [Method::GET, Method::POST, Method::DELETE] {
+ assert!(ensure_method_allowed(&method).is_ok(), "refused {method}");
+ }
+
+ for method in [Method::PUT, Method::PATCH, Method::CONNECT, Method::TRACE] {
+ assert!(
+ matches!(
+ ensure_method_allowed(&method),
+ Err(EgressError::MethodNotAllowed(_))
+ ),
+ "allowed {method}"
+ );
+ }
+}
+
+#[test]
+fn strips_the_sandboxs_own_credentials_from_a_forwarded_request() {
+ let mut headers = header_map(&[
+ ("authorization", "Bearer session-token"),
+ ("cookie", "macro_session=abc"),
+ ("content-type", "application/json"),
+ ]);
+
+ sanitize_request_headers(&mut headers);
+
+ assert_eq!(names(&headers), ["content-type"]);
+}
+
+/// `HeaderMap` is case-insensitive by construction, so this is really a test
+/// that we are leaning on it rather than comparing strings ourselves.
+#[test]
+fn strips_regardless_of_header_case() {
+ let mut headers = header_map(&[
+ ("Authorization", "Bearer session-token"),
+ ("Host", "egress"),
+ ]);
+
+ sanitize_request_headers(&mut headers);
+
+ assert!(headers.is_empty());
+}
+
+/// A header sent twice has two values under one name, and stripping has to
+/// drain them - removing once would forward the rest.
+#[test]
+fn strips_every_value_of_a_repeated_header() {
+ let mut headers = header_map(&[
+ ("authorization", "Bearer one"),
+ ("authorization", "Bearer two"),
+ ("accept", "text/event-stream"),
+ ]);
+
+ sanitize_request_headers(&mut headers);
+
+ assert_eq!(names(&headers), ["accept"]);
+}
+
+/// The `x-pd-*` headers are Pipedream's authorization vocabulary -
+/// `x-pd-external-user-id` alone picks whose account a request spends - so
+/// none of them may ride through from the sandbox, including ones this proxy
+/// never stamps itself.
+#[test]
+fn strips_every_pipedream_scoping_header() {
+ let mut headers = header_map(&[
+ ("x-pd-external-user-id", "somebody-else"),
+ ("X-PD-Tool-Mode", "full-config"),
+ ("x-pd-anything-future", "1"),
+ ("accept", "text/event-stream"),
+ ]);
+
+ sanitize_request_headers(&mut headers);
+
+ assert_eq!(names(&headers), ["accept"]);
+}
+
+/// The headers MCP needs to work across a proxy at all: the server's session
+/// id, event-stream resumption, and the accept header that asks for a stream.
+#[test]
+fn keeps_the_headers_mcp_runs_on() {
+ let mut headers = header_map(&[
+ ("mcp-session-id", "abc123"),
+ ("last-event-id", "42"),
+ ("accept", "text/event-stream"),
+ ("connection", "keep-alive"),
+ ]);
+
+ sanitize_request_headers(&mut headers);
+
+ assert_eq!(
+ names(&headers),
+ ["mcp-session-id", "last-event-id", "accept"]
+ );
+}
+
+#[test]
+fn keeps_the_upstreams_session_id_on_the_way_back() {
+ let mut headers = header_map(&[
+ ("mcp-session-id", "abc123"),
+ ("content-type", "text/event-stream"),
+ ("set-cookie", "upstream=1"),
+ ("transfer-encoding", "chunked"),
+ ]);
+
+ sanitize_response_headers(&mut headers);
+
+ assert_eq!(names(&headers), ["mcp-session-id", "content-type"]);
+}
+
+/// The scoping strip is symmetric: an upstream that echoes its `x-pd-*`
+/// vocabulary does not report whose account was spent to the sandbox.
+#[test]
+fn echoed_scoping_headers_never_reach_the_sandbox() {
+ let mut headers = header_map(&[
+ ("x-pd-external-user-id", "macro|[email protected]"),
+ ("x-pd-project-id", "proj_abc"),
+ ("content-type", "application/json"),
+ ]);
+
+ sanitize_response_headers(&mut headers);
+
+ assert_eq!(names(&headers), ["content-type"]);
+}
+
+#[test]
+fn secrets_do_not_print() {
+ let session = SessionToken::new("header.payload.signature");
+ let bearer = BearerToken::new("dd-oauth-token");
+ let basic = UpstreamCredential::Basic {
+ username: "x-access-token".to_owned(),
+ secret: "ghs-installation-token".to_owned(),
+ };
+
+ assert_eq!(format!("{session:?}"), "SessionToken([REDACTED])");
+ assert_eq!(format!("{bearer:?}"), "BearerToken([REDACTED])");
+ assert_eq!(
+ format!("{:?}", UpstreamCredential::Bearer(bearer)),
+ "Bearer([REDACTED])"
+ );
+ assert_eq!(format!("{basic:?}"), "Basic(x-access-token, [REDACTED])");
+}
+
+/// git's credential helper has no way to carry a bearer, so GitHub's git
+/// endpoints take the installation token as a Basic *password*.
+#[test]
+fn a_basic_credential_renders_as_github_expects() {
+ let value = UpstreamCredential::Basic {
+ username: "x-access-token".to_owned(),
+ secret: "ghs-installation-token".to_owned(),
+ }
+ .header_value()
+ .expect("header value");
+
+ assert!(value.is_sensitive());
+ assert_eq!(
+ value.to_str().expect("ascii"),
+ format!(
+ "Basic {}",
+ BASE64.encode("x-access-token:ghs-installation-token")
+ )
+ );
+}
+
+#[test]
+fn a_repo_slug_rejects_rather_than_repairs() {
+ let slug = RepoSlug::parse("Macro-Inc", "wolf.1_x").expect("slug");
+ assert_eq!(slug.owner(), "Macro-Inc");
+ assert_eq!(slug.name(), "wolf.1_x");
+ assert_eq!(slug.to_string(), "Macro-Inc/wolf.1_x");
+
+ for (owner, name) in [
+ ("", "repo"),
+ ("owner", ""),
+ ("..", "repo"),
+ ("owner", ".."),
+ ("owner", "."),
+ ("owner/other", "repo"),
+ ("owner", "re po"),
+ ("owner", "repo%2f.."),
+ ] {
+ assert_eq!(
+ RepoSlug::parse(owner, name),
+ None,
+ "accepted {owner}/{name}"
+ );
+ }
+}
+
+/// The allowlist is the whole point: anything not one of the three smart-HTTP
+/// routes - the dumb protocol's object endpoints most of all - is not a target
+/// this crate can name.
+#[test]
+fn git_endpoints_are_an_allowlist() {
+ assert_eq!(
+ GitEndpoint::parse("info/refs", Some("service=git-upload-pack")),
+ Some(GitEndpoint::InfoRefs {
+ service: GitService::UploadPack
+ })
+ );
+ assert_eq!(
+ GitEndpoint::parse("git-receive-pack", None),
+ Some(GitEndpoint::ReceivePack)
+ );
+
+ for (path, query) in [
+ ("info/refs", None),
+ ("info/refs", Some("service=git-fetch-pack")),
+ ("info/packs", None),
+ ("objects/info/alternates", None),
+ ("objects/ab/cdef0123456789", None),
+ ("HEAD", None),
+ ("", None),
+ ] {
+ assert_eq!(
+ GitEndpoint::parse(path, query),
+ None,
+ "accepted {path} {query:?}"
+ );
+ }
+}
+
+#[test]
+fn a_git_endpoint_round_trips_to_its_path() {
+ for endpoint in [
+ GitEndpoint::InfoRefs {
+ service: GitService::UploadPack,
+ },
+ GitEndpoint::InfoRefs {
+ service: GitService::ReceivePack,
+ },
+ GitEndpoint::UploadPack,
+ GitEndpoint::ReceivePack,
+ ] {
+ let rendered = endpoint.path_and_query();
+ let (path, query) = match rendered.split_once('?') {
+ Some((path, query)) => (path, Some(query)),
+ None => (rendered.as_str(), None),
+ };
+ assert_eq!(GitEndpoint::parse(path, query), Some(endpoint));
+ }
+}
+
+/// `HeaderValue` marks the credential sensitive, which is what keeps it out
+/// of the http stack's own `Debug` output - a hand-rolled `String` header
+/// could not say this at all.
+#[test]
+fn the_stamped_credential_is_marked_sensitive() {
+ let value = UpstreamCredential::Bearer(BearerToken::new("dd-oauth-token"))
+ .header_value()
+ .expect("header value");
+
+ assert!(value.is_sensitive());
+ assert_eq!(value.to_str().expect("ascii"), "Bearer dd-oauth-token");
+ assert_eq!(format!("{value:?}"), "Sensitive");
+}
+
+/// A credential that could carry a newline could inject a header of its own
+/// choosing into the upstream request. `HeaderValue` refuses it.
+#[test]
+fn a_credential_that_could_inject_a_header_is_refused() {
+ let error = UpstreamCredential::Bearer(BearerToken::new("token\r\nx-injected: yes"))
+ .header_value()
+ .expect_err("refused");
+
+ assert!(matches!(error, EgressError::Internal(_)));
+}
+
+/// `authorization` is not a response header, which is precisely why it is on
+/// the response strip list: an upstream that echoes back what it received
+/// would hand the owner's credential to the sandbox.
+#[test]
+fn an_echoed_credential_never_reaches_the_sandbox() {
+ let mut headers = header_map(&[
+ ("authorization", "Bearer dd-oauth-token"),
+ ("proxy-authorization", "Basic c2VjcmV0"),
+ ("content-type", "application/json"),
+ ]);
+
+ sanitize_response_headers(&mut headers);
+
+ assert_eq!(names(&headers), ["content-type"]);
+}
+
+/// The staff gate is an exact match on the parsed domain part, and the
+/// parser behind `MacroUserIdStr` is what makes the lookalikes
+/// unrepresentable - a suffixed domain is a different domain, a second `@`
+/// or a trailing dot is not an email, and casing normalizes before the
+/// compare rather than defeating it.
+#[test]
+fn the_staff_gate_admits_exactly_the_macro_domain() {
+ let owner = MacroUserIdStr::try_from_email(staff).expect(staff);
+ assert!(is_macro_staff(&owner), "refused {staff}");
+ }
+
+ for visitor in [
+ ] {
+ let owner = MacroUserIdStr::try_from_email(visitor).expect(visitor);
+ assert!(!is_macro_staff(&owner), "admitted {visitor}");
+ }
+
+ for not_an_email in [
+ "[email protected]@evil.com",
+ "wolf@macro com",
+ "wolf@macrо.com", // Cyrillic 'о': non-ASCII labels are not emails here.
+ "not-an-email",
+ ] {
+ assert!(
+ MacroUserIdStr::try_from_email(not_an_email).is_err(),
+ "parsed {not_an_email}"
+ );
+ }
+}
+
+/// A repeated `service=` cannot smuggle a second verb: the first pair decides,
+/// and the upstream query is rebuilt from the parsed endpoint, never echoed.
+#[test]
+fn a_repeated_git_service_parameter_does_not_escalate() {
+ assert_eq!(
+ GitEndpoint::parse(
+ "info/refs",
+ Some("service=git-upload-pack&service=git-receive-pack")
+ ),
+ Some(GitEndpoint::InfoRefs {
+ service: GitService::UploadPack
+ })
+ );
+}
diff --git a/crates/agent_egress/src/domain/ports.rs b/crates/agent_egress/src/domain/ports.rs
new file mode 100644
index 0000000000..0be3100fa1
--- /dev/null
+++ b/crates/agent_egress/src/domain/ports.rs
@@ -0,0 +1,84 @@
+//! The capabilities the service needs from the outside.
+//!
+//! Four, and the split is deliberate. [`SessionAuthority`] answers "may this
+//! request happen at all", [`McpCredentials`] and [`GithubTokens`] answer
+//! "with whose credential, to where" for the two kinds of upstream, and
+//! [`Forwarder`] does the one thing that is genuinely transport work. Only the
+//! last touches a socket, which is what lets the decisions above it be tested
+//! exhaustively without one.
+
+use crate::domain::error::EgressError;
+use crate::domain::model::{
+ McpDestination, ProxyRequest, ProxyResponse, RepoSlug, SessionGrant, SessionToken, UpstreamCall,
+};
+use macro_user_id::user_id::MacroUserIdStr;
+
+/// Turn a sandbox's session token into what it is allowed to spend.
+///
+/// Implementations verify the token *and* confirm the session is still open:
+/// closing a session is how a person revokes its egress, and a token that
+/// outlived its session must stop working the moment the session ends rather
+/// than when it expires.
+pub trait SessionAuthority: Send + Sync {
+ /// Verify `token`, or say why it does not entitle anyone to anything.
+ fn authorize(
+ &self,
+ token: &SessionToken,
+ ) -> impl Future<Output = Result<SessionGrant, EgressError>> + Send;
+}
+
+/// Resolve an MCP destination to a live upstream call.
+///
+/// Implementations own token freshness: a returned [`UpstreamCall`] carries a
+/// credential good now, refreshing and persisting the owner's stored grant if
+/// that is what it took. The service above deliberately knows nothing about
+/// OAuth.
+pub trait McpCredentials: Send + Sync {
+ /// The upstream and credential for `destination`, on behalf of `owner`.
+ ///
+ /// Resolution is scoped to `owner`: a slug that names somebody else's
+ /// server is [`EgressError::UnknownServer`], not somebody else's server.
+ fn resolve(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ destination: &McpDestination,
+ ) -> impl Future<Output = Result<UpstreamCall, EgressError>> + Send;
+}
+
+/// Mint a credential for git access to one repository.
+///
+/// Implementations own both the minting and the "may this owner touch this
+/// repository at all" question, because only they can see the GitHub App's
+/// installations. The returned [`UpstreamCall`] addresses the repository's git
+/// base and must end in a `/` so the endpoint appends rather than replaces the
+/// last segment; the service appends the endpoint, so an implementation cannot
+/// widen what the sandbox reaches beyond the allowlist.
+pub trait GithubTokens: Send + Sync {
+ /// A credential for `repo`, valid because `owner` may reach it.
+ ///
+ /// Refusing with [`EgressError::RepoUnavailable`] is the answer when the
+ /// App's installation for `repo` does not belong to `owner` or one of
+ /// their teams. Without that check any session could be configured with any
+ /// repository the App happens to be installed on and be handed write
+ /// access to it.
+ fn resolve(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ repo: &RepoSlug,
+ ) -> impl Future<Output = Result<UpstreamCall, EgressError>> + Send;
+}
+
+/// Execute a request and stream the answer back.
+///
+/// The only port that speaks to the network, and deliberately the dumbest:
+/// by the time a request reaches here it is already addressed at its
+/// upstream and stamped with the right credential, so an implementation has
+/// no decision left to make. It sends what it is given and passes the status
+/// and body back without interpreting either.
+pub trait Forwarder: Send + Sync {
+ /// Send `request` wherever its URI points, streaming both directions.
+ fn forward(
+ &self,
+ request: ProxyRequest,
+ ) -> impl Future<Output = Result<ProxyResponse, EgressError>> + Send;
+}
diff --git a/crates/agent_egress/src/domain/service.rs b/crates/agent_egress/src/domain/service.rs
new file mode 100644
index 0000000000..2523b6411f
--- /dev/null
+++ b/crates/agent_egress/src/domain/service.rs
@@ -0,0 +1,166 @@
+//! The service itself: verify, resolve, stamp, forward.
+
+use http::Uri;
+use http::header::AUTHORIZATION;
+
+use crate::domain::error::EgressError;
+use crate::domain::model::{
+ EgressTarget, ProxyRequest, ProxyResponse, SessionToken, ensure_method_allowed, is_macro_staff,
+ sanitize_request_headers, sanitize_response_headers,
+};
+use crate::domain::ports::{Forwarder, GithubTokens, McpCredentials, SessionAuthority};
+
+#[cfg(test)]
+mod test;
+
+/// Proxy one request on a sandbox's behalf.
+pub trait EgressService: Send + Sync {
+ /// Verify `token`, resolve `target` against the session owner's own
+ /// connections, and pass `request` through with the upstream credential
+ /// stamped on in place of the sandbox's.
+ fn proxy(
+ &self,
+ token: &SessionToken,
+ target: EgressTarget,
+ request: ProxyRequest,
+ ) -> impl Future<Output = Result<ProxyResponse, EgressError>> + Send;
+}
+
+/// The service, over its four ports.
+pub struct EgressServiceImpl<Sessions, Credentials, Tokens, Forward> {
+ sessions: Sessions,
+ credentials: Credentials,
+ tokens: Tokens,
+ forward: Forward,
+}
+
+impl<Sessions, Credentials, Tokens, Forward>
+ EgressServiceImpl<Sessions, Credentials, Tokens, Forward>
+where
+ Sessions: SessionAuthority,
+ Credentials: McpCredentials,
+ Tokens: GithubTokens,
+ Forward: Forwarder,
+{
+ /// Build the service over its adapters.
+ pub fn new(
+ sessions: Sessions,
+ credentials: Credentials,
+ tokens: Tokens,
+ forward: Forward,
+ ) -> Self {
+ Self {
+ sessions,
+ credentials,
+ tokens,
+ forward,
+ }
+ }
+}
+
+impl<Sessions, Credentials, Tokens, Forward> EgressService
+ for EgressServiceImpl<Sessions, Credentials, Tokens, Forward>
+where
+ Sessions: SessionAuthority,
+ Credentials: McpCredentials,
+ Tokens: GithubTokens,
+ Forward: Forwarder,
+{
+ #[tracing::instrument(skip_all, err, fields(
+ destination = ?target,
+ method = %request.method(),
+ session = tracing::field::Empty,
+ owner = tracing::field::Empty,
+ upstream_status = tracing::field::Empty,
+ ))]
+ async fn proxy(
+ &self,
+ token: &SessionToken,
+ target: EgressTarget,
+ mut request: ProxyRequest,
+ ) -> Result<ProxyResponse, EgressError> {
+ ensure_method_allowed(request.method())?;
+
+ // Authorize before resolving: resolution reads the owner's connected
+ // servers, and an unverified token must not be able to probe which
+ // of those exist.
+ let grant = self.sessions.authorize(token).await?;
+ let span = tracing::Span::current();
+ span.record("session", tracing::field::display(&grant.session));
+ span.record("owner", tracing::field::display(&grant.owner));
+
+ // Staff-only for now, checked here so every target - git, connected
+ // MCP servers, Macro's own - passes one gate. The refusal names
+ // itself ("not Macro staff") so the sandbox can report an actionable
+ // reason; the reason is our own static wording, never the request's.
+ if !is_macro_staff(&grant.owner) {
+ tracing::warn!(owner = %grant.owner, "refusing egress for a session owned outside macro.com");
+ return Err(EgressError::Unauthenticated(
+ "the session owner is not Macro staff",
+ ));
+ }
+
+ let call = match &target {
+ EgressTarget::McpServer(destination) => {
+ self.credentials.resolve(&grant.owner, destination).await?
+ }
+ EgressTarget::GitHubGit { endpoint } => {
+ // The repository is the grant's, never the request's: a
+ // session works on exactly one, and the sandbox has no way to
+ // name another because there is no place in the route to put
+ // one.
+ let base = self.tokens.resolve(&grant.owner, &grant.repo).await?;
+
+ // The endpoint comes from the allowlist, not from the port, so
+ // no credential adapter can widen what the sandbox reaches.
+ let url = base
+ .url()
+ .join(&endpoint.path_and_query())
+ .map_err(|error| {
+ EgressError::Internal(rootcause::report!(
+ "git endpoint is not a url: {error}"
+ ))
+ })?;
+ base.redirected_to(url)?
+ }
+ };
+
+ tracing::info!(
+ session = %grant.session,
+ owner = %grant.owner,
+ upstream = %target.name(),
+ method = %request.method(),
+ "proxying",
+ );
+
+ *request.uri_mut() = call.url().as_str().parse::<Uri>().map_err(|error| {
+ EgressError::Internal(rootcause::report!("upstream url is not a uri: {error}"))
+ })?;
+
+ // Strip first, stamp second, and never the other way round: the
+ // sandbox's own `Authorization` is this session's token, and the
+ // strip list contains `authorization` precisely so that no request
+ // can carry it upstream. Doing it in this order means the header the
+ // upstream sees is the one resolved for the owner, whatever the
+ // sandbox sent.
+ sanitize_request_headers(request.headers_mut());
+ request
+ .headers_mut()
+ .insert(AUTHORIZATION, call.authorization().header_value()?);
+ // Scoping headers are half of the credential - for Pipedream they are
+ // what says whose account the bearer spends - so they get the same
+ // treatment: stamped from the resolved call after the strip, never
+ // taken from the request.
+ for (name, value) in call.scope_headers() {
+ request.headers_mut().insert(name.clone(), value.clone());
+ }
+
+ let mut response = self.forward.forward(request).await?;
+ sanitize_response_headers(response.headers_mut());
+
+ tracing::Span::current().record("upstream_status", response.status().as_u16());
+ tracing::debug!(status = %response.status(), "upstream answered");
+
+ Ok(response)
+ }
+}
diff --git a/crates/agent_egress/src/domain/service/test.rs b/crates/agent_egress/src/domain/service/test.rs
new file mode 100644
index 0000000000..10f545853f
--- /dev/null
+++ b/crates/agent_egress/src/domain/service/test.rs
@@ -0,0 +1,700 @@
+use super::*;
+use crate::domain::model::{
+ AgentSessionId, BearerToken, GitEndpoint, GitService, McpDestination, McpServerSlug, ProxyBody,
+ RepoSlug, SessionGrant, UpstreamCall, UpstreamCredential,
+};
+use http::header::{AUTHORIZATION, HeaderMap, HeaderName, HeaderValue};
+use http::{Method, StatusCode};
+use http_body_util::{BodyExt, Empty};
+use macro_user_id::user_id::MacroUserIdStr;
+use std::sync::Mutex;
+use url::Url;
+
+fn owner() -> MacroUserIdStr<'static> {
+ MacroUserIdStr::try_from_email("[email protected]").expect("a valid user id")
+}
+
+fn empty_body() -> ProxyBody {
+ Empty::new().map_err(|never| match never {}).boxed_unsync()
+}
+
+fn header_map(pairs: &[(&str, &str)]) -> HeaderMap {
+ let mut headers = HeaderMap::new();
+ for (name, value) in pairs {
+ headers.append(
+ HeaderName::from_bytes(name.as_bytes()).expect("header name"),
+ HeaderValue::from_str(value).expect("header value"),
+ );
+ }
+ headers
+}
+
+fn names(headers: &HeaderMap) -> Vec<&str> {
+ headers.keys().map(HeaderName::as_str).collect()
+}
+
+fn session_repo() -> RepoSlug {
+ RepoSlug::parse("macro", "wolf").expect("slug")
+}
+
+/// Verifies whatever token it is given, unless built to refuse.
+struct StubSessions(Result<SessionGrant, ()>);
+
+impl StubSessions {
+ fn granting() -> Self {
+ Self(Ok(SessionGrant {
+ session: AgentSessionId::new(),
+ owner: owner(),
+ repo: session_repo(),
+ }))
+ }
+
+ fn refusing() -> Self {
+ Self(Err(()))
+ }
+}
+
+impl SessionAuthority for StubSessions {
+ async fn authorize(&self, _token: &SessionToken) -> Result<SessionGrant, EgressError> {
+ self.0
+ .clone()
+ .map_err(|()| EgressError::Unauthenticated("unknown session token"))
+ }
+}
+
+/// Records who it was asked about, and answers with a fixed upstream.
+struct SpyCredentials {
+ asked: Mutex<Vec<(String, String)>>,
+ known: bool,
+ url: String,
+ scope: HeaderMap,
+}
+
+impl SpyCredentials {
+ fn knowing() -> Self {
+ Self::at("https://mcp.example.com/mcp")
+ }
+
+ /// A server whose stored URL is whatever the owner typed in.
+ fn at(url: &str) -> Self {
+ Self {
+ asked: Mutex::default(),
+ known: true,
+ url: url.to_owned(),
+ scope: HeaderMap::new(),
+ }
+ }
+
+ /// A resolution that scopes its credential with extra headers, the way
+ /// the Pipedream adapter does.
+ fn scoped(scope: &[(&str, &str)]) -> Self {
+ let mut headers = HeaderMap::new();
+ for (name, value) in scope {
+ headers.insert(
+ HeaderName::from_bytes(name.as_bytes()).expect("a header name"),
+ HeaderValue::from_str(value).expect("a header value"),
+ );
+ }
+ Self {
+ scope: headers,
+ ..Self::knowing()
+ }
+ }
+
+ fn empty() -> Self {
+ Self {
+ asked: Mutex::default(),
+ known: false,
+ url: String::new(),
+ scope: HeaderMap::new(),
+ }
+ }
+}
+
+impl McpCredentials for SpyCredentials {
+ async fn resolve(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ destination: &McpDestination,
+ ) -> Result<UpstreamCall, EgressError> {
+ let McpDestination::Connected(slug) = destination else {
+ unreachable!("these tests only dial connected servers");
+ };
+ self.asked
+ .lock()
+ .expect("lock")
+ .push((owner.to_string(), slug.to_string()));
+
+ if !self.known {
+ return Err(EgressError::UnknownServer(slug.clone()));
+ }
+
+ Ok(UpstreamCall::bearer(
+ Url::parse(&self.url).expect("url"),
+ BearerToken::new("upstream-token"),
+ )?
+ .scoped_by(self.scope.clone()))
+ }
+}
+
+/// Records which repository it was asked to mint for.
+struct SpyGithubTokens {
+ asked: Mutex<Vec<(String, String)>>,
+ url: String,
+}
+
+impl Default for SpyGithubTokens {
+ fn default() -> Self {
+ Self::at("https://github.com/macro/wolf.git/")
+ }
+}
+
+impl SpyGithubTokens {
+ /// A minting adapter that answers with whatever base it was built with,
+ /// including one it has no business answering with.
+ fn at(url: &str) -> Self {
+ Self {
+ asked: Mutex::default(),
+ url: url.to_owned(),
+ }
+ }
+}
+
+impl GithubTokens for SpyGithubTokens {
+ async fn resolve(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ repo: &RepoSlug,
+ ) -> Result<UpstreamCall, EgressError> {
+ self.asked
+ .lock()
+ .expect("lock")
+ .push((owner.to_string(), repo.to_string()));
+
+ UpstreamCall::basic(
+ Url::parse(&self.url).expect("url"),
+ "x-access-token",
+ "ghs-installation-token",
+ )
+ }
+}
+
+/// Records the request it was handed, and answers with a fixed response.
+struct SpyForwarder {
+ seen: Mutex<Option<http::request::Parts>>,
+ response_headers: HeaderMap,
+}
+
+impl SpyForwarder {
+ fn answering(response_headers: &[(&str, &str)]) -> Self {
+ Self {
+ seen: Mutex::default(),
+ response_headers: header_map(response_headers),
+ }
+ }
+
+ fn was_called(&self) -> bool {
+ self.seen.lock().expect("lock").is_some()
+ }
+
+ fn forwarded<T>(&self, read: impl Fn(&http::request::Parts) -> T) -> T {
+ read(
+ self.seen
+ .lock()
+ .expect("lock")
+ .as_ref()
+ .expect("forwarder was called"),
+ )
+ }
+}
+
+impl Forwarder for SpyForwarder {
+ async fn forward(&self, request: ProxyRequest) -> Result<ProxyResponse, EgressError> {
+ let (parts, _body) = request.into_parts();
+ *self.seen.lock().expect("lock") = Some(parts);
+
+ let mut response = http::Response::new(empty_body());
+ *response.status_mut() = StatusCode::ACCEPTED;
+ *response.headers_mut() = self.response_headers.clone();
+ Ok(response)
+ }
+}
+
+fn request(method: Method, header_pairs: &[(&str, &str)]) -> ProxyRequest {
+ let mut request = http::Request::new(empty_body());
+ *request.method_mut() = method;
+ *request.headers_mut() = header_map(header_pairs);
+ request
+}
+
+fn datadog() -> EgressTarget {
+ EgressTarget::McpServer(McpDestination::Connected(
+ McpServerSlug::parse("datadog").expect("slug"),
+ ))
+}
+
+#[tokio::test]
+async fn addresses_the_request_at_the_resolved_upstream_and_passes_the_status_back() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ let response = service
+ .proxy(
+ &SessionToken::new("token"),
+ datadog(),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect("proxied");
+
+ assert_eq!(response.status(), StatusCode::ACCEPTED);
+ assert_eq!(
+ service.forward.forwarded(|parts| parts.uri.to_string()),
+ "https://mcp.example.com/mcp"
+ );
+}
+
+/// The whole point of the service: the sandbox's credential for us must not
+/// reach a third-party server, which would let that server spend this
+/// session's egress. What arrives upstream is the owner's credential, and
+/// only that.
+#[tokio::test]
+async fn replaces_the_sandboxs_token_with_the_owners() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ service
+ .proxy(
+ &SessionToken::new("session-token"),
+ datadog(),
+ request(
+ Method::POST,
+ &[
+ ("authorization", "Bearer session-token"),
+ ("mcp-session-id", "abc123"),
+ ],
+ ),
+ )
+ .await
+ .expect("proxied");
+
+ let stamped = service.forward.forwarded(|parts| {
+ parts
+ .headers
+ .get_all(AUTHORIZATION)
+ .iter()
+ .map(|value| value.to_str().expect("ascii").to_owned())
+ .collect::<Vec<_>>()
+ });
+
+ assert_eq!(stamped, ["Bearer upstream-token"], "exactly one credential");
+ assert_eq!(
+ service.forward.forwarded(|parts| names(&parts.headers)
+ .into_iter()
+ .map(str::to_owned)
+ .collect::<Vec<_>>()),
+ ["mcp-session-id", "authorization"]
+ );
+}
+
+/// Pipedream reads *whose* connected account to spend off
+/// `x-pd-external-user-id`, so those headers are part of the credential: the
+/// stamped values must come from resolution, and a sandbox that sends its own
+/// must not be able to act as anybody else.
+#[tokio::test]
+async fn stamps_the_resolved_scope_over_whatever_the_sandbox_claimed() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::scoped(&[
+ ("x-pd-external-user-id", "the-owner"),
+ ("x-pd-app-slug", "datadog"),
+ ]),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ service
+ .proxy(
+ &SessionToken::new("session-token"),
+ datadog(),
+ request(
+ Method::POST,
+ &[
+ ("authorization", "Bearer session-token"),
+ // The sandbox claiming to be somebody else, and a scoping
+ // header resolution never stamps at all.
+ ("x-pd-external-user-id", "somebody-else"),
+ ("x-pd-tool-mode", "full-config"),
+ ],
+ ),
+ )
+ .await
+ .expect("proxied");
+
+ // Sorted, because a `HeaderMap` decides its own iteration order.
+ let mut scope = service.forward.forwarded(|parts| {
+ parts
+ .headers
+ .iter()
+ .filter(|(name, _)| name.as_str().starts_with("x-pd-"))
+ .map(|(name, value)| {
+ (
+ name.as_str().to_owned(),
+ value.to_str().expect("ascii").to_owned(),
+ )
+ })
+ .collect::<Vec<_>>()
+ });
+ scope.sort();
+
+ assert_eq!(
+ scope,
+ [
+ ("x-pd-app-slug".to_owned(), "datadog".to_owned()),
+ ("x-pd-external-user-id".to_owned(), "the-owner".to_owned()),
+ ],
+ "exactly the resolved scope, nothing the sandbox sent"
+ );
+}
+
+#[tokio::test]
+async fn strips_hop_by_hop_headers_from_the_response() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[
+ ("mcp-session-id", "abc123"),
+ ("set-cookie", "upstream=1"),
+ ("transfer-encoding", "chunked"),
+ ]),
+ );
+
+ let response = service
+ .proxy(
+ &SessionToken::new("token"),
+ datadog(),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect("proxied");
+
+ assert_eq!(names(response.headers()), ["mcp-session-id"]);
+}
+
+/// The proxy is staff-only for now: a session owned outside macro.com gets
+/// nothing, whatever its token says - told only, in our words, that staff
+/// membership is what it lacks.
+#[tokio::test]
+async fn a_session_owned_outside_macro_gets_nothing() {
+ let service = EgressServiceImpl::new(
+ StubSessions(Ok(SessionGrant {
+ session: AgentSessionId::new(),
+ owner: MacroUserIdStr::try_from_email("[email protected]").expect("a valid user id"),
+ repo: session_repo(),
+ })),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ let refusal = service
+ .proxy(
+ &SessionToken::new("token"),
+ datadog(),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect_err("refused");
+
+ assert!(
+ matches!(refusal, EgressError::Unauthenticated(_)),
+ "{refusal}"
+ );
+ assert!(
+ service.credentials.asked.lock().expect("lock").is_empty(),
+ "an outside owner must never reach credential resolution"
+ );
+ assert!(!service.forward.was_called());
+}
+
+/// Resolution reads the owner's connected servers, so an unverified token
+/// must not get that far - otherwise a bad token is still an oracle for which
+/// servers somebody has connected.
+#[tokio::test]
+async fn an_unverified_token_never_reaches_credential_resolution() {
+ let service = EgressServiceImpl::new(
+ StubSessions::refusing(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ let error = service
+ .proxy(
+ &SessionToken::new("forged"),
+ datadog(),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect_err("refused");
+
+ assert!(matches!(error, EgressError::Unauthenticated(_)));
+ assert!(service.credentials.asked.lock().expect("lock").is_empty());
+ assert!(!service.forward.was_called());
+}
+
+#[tokio::test]
+async fn resolves_only_against_the_session_owner() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ service
+ .proxy(
+ &SessionToken::new("token"),
+ datadog(),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect("proxied");
+
+ assert_eq!(
+ *service.credentials.asked.lock().expect("lock"),
+ vec![(owner().to_string(), "datadog".to_owned())]
+ );
+}
+
+#[tokio::test]
+async fn an_unknown_server_is_refused_before_anything_is_forwarded() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::empty(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ let error = service
+ .proxy(
+ &SessionToken::new("token"),
+ datadog(),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect_err("refused");
+
+ assert!(matches!(error, EgressError::UnknownServer(slug) if slug.as_str() == "datadog"));
+ assert!(!service.forward.was_called());
+}
+
+/// A verb outside the allowlist is refused before the token is even looked
+/// at, so an unsupported method cannot be used to probe anything.
+#[tokio::test]
+async fn a_disallowed_method_is_refused_up_front() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ let error = service
+ .proxy(
+ &SessionToken::new("token"),
+ datadog(),
+ request(Method::PUT, &[]),
+ )
+ .await
+ .expect_err("refused");
+
+ assert!(matches!(error, EgressError::MethodNotAllowed(method) if method == Method::PUT));
+ assert!(service.credentials.asked.lock().expect("lock").is_empty());
+ assert!(!service.forward.was_called());
+}
+
+fn git(endpoint: GitEndpoint) -> EgressTarget {
+ EgressTarget::GitHubGit { endpoint }
+}
+
+/// The endpoint comes from the allowlist and is appended to whatever the
+/// credential adapter addressed, so no adapter can widen the reachable set.
+#[tokio::test]
+async fn addresses_a_git_request_at_the_repositorys_endpoint() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ service
+ .proxy(
+ &SessionToken::new("token"),
+ git(GitEndpoint::InfoRefs {
+ service: GitService::UploadPack,
+ }),
+ request(Method::GET, &[]),
+ )
+ .await
+ .expect("proxied");
+
+ assert_eq!(
+ service.forward.forwarded(|parts| parts.uri.to_string()),
+ "https://github.com/macro/wolf.git/info/refs?service=git-upload-pack"
+ );
+}
+
+/// git talks to us through a credential helper, so the session token arrives
+/// as a Basic password. It must still be replaced, not accompanied - and the
+/// replacement is the installation token, also as a Basic password.
+#[tokio::test]
+async fn replaces_the_sandboxs_basic_credential_on_a_git_request() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ service
+ .proxy(
+ &SessionToken::new("session-token"),
+ git(GitEndpoint::UploadPack),
+ request(
+ Method::POST,
+ &[("authorization", "Basic bWFjcm86c2Vzc2lvbi10b2tlbg==")],
+ ),
+ )
+ .await
+ .expect("proxied");
+
+ let stamped = service.forward.forwarded(|parts| {
+ parts
+ .headers
+ .get_all(AUTHORIZATION)
+ .iter()
+ .map(|value| value.to_str().expect("ascii").to_owned())
+ .collect::<Vec<_>>()
+ });
+
+ assert_eq!(
+ stamped,
+ [UpstreamCredential::Basic {
+ username: "x-access-token".to_owned(),
+ secret: "ghs-installation-token".to_owned(),
+ }
+ .header_value()
+ .expect("header value")
+ .to_str()
+ .expect("ascii")],
+ "exactly one credential",
+ );
+}
+
+#[tokio::test]
+async fn an_unverified_token_never_reaches_git_token_minting() {
+ let service = EgressServiceImpl::new(
+ StubSessions::refusing(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ let error = service
+ .proxy(
+ &SessionToken::new("forged"),
+ git(GitEndpoint::UploadPack),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect_err("refused");
+
+ assert!(matches!(error, EgressError::Unauthenticated(_)));
+ assert!(service.tokens.asked.lock().expect("lock").is_empty());
+ assert!(!service.forward.was_called());
+}
+
+/// The sandbox has no way to name a repository - the git route has no place
+/// to put one - so what gets minted is always the grant's.
+#[tokio::test]
+async fn mints_for_the_grants_repository_and_owner() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ service
+ .proxy(
+ &SessionToken::new("token"),
+ git(GitEndpoint::UploadPack),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect("proxied");
+
+ assert_eq!(
+ *service.tokens.asked.lock().expect("lock"),
+ vec![(owner().to_string(), "macro/wolf".to_owned())]
+ );
+ assert!(service.credentials.asked.lock().expect("lock").is_empty());
+}
+
+/// `mcp_servers.url` is typed in by a person. A cleartext one would put the
+/// owner's OAuth token on the wire for anyone on the path, so it never gets
+/// stamped at all.
+#[tokio::test]
+async fn a_cleartext_mcp_server_never_receives_the_owners_token() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::at("http://mcp.example.com/mcp"),
+ SpyGithubTokens::default(),
+ SpyForwarder::answering(&[]),
+ );
+
+ let error = service
+ .proxy(
+ &SessionToken::new("token"),
+ datadog(),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect_err("refused");
+
+ assert!(matches!(error, EgressError::InsecureUpstream(_)));
+ assert!(!service.forward.was_called());
+}
+
+#[tokio::test]
+async fn a_cleartext_git_base_is_refused_too() {
+ let service = EgressServiceImpl::new(
+ StubSessions::granting(),
+ SpyCredentials::knowing(),
+ SpyGithubTokens::at("http://github.com/macro/wolf.git/"),
+ SpyForwarder::answering(&[]),
+ );
+
+ let error = service
+ .proxy(
+ &SessionToken::new("token"),
+ git(GitEndpoint::UploadPack),
+ request(Method::POST, &[]),
+ )
+ .await
+ .expect_err("refused");
+
+ assert!(matches!(error, EgressError::InsecureUpstream(_)));
+ assert!(!service.forward.was_called());
+}
diff --git a/crates/agent_egress/src/inbound/axum_router.rs b/crates/agent_egress/src/inbound/axum_router.rs
new file mode 100644
index 0000000000..fbd9039a7f
--- /dev/null
+++ b/crates/agent_egress/src/inbound/axum_router.rs
@@ -0,0 +1,281 @@
+//! The sandbox-facing HTTP surface.
+//!
+//! Deliberately thin. It reads the session token off the request, turns a path
+//! into an [`EgressTarget`], and converts in both directions; every decision
+//! about whether the call may happen belongs to
+//! [`crate::domain::service::EgressService`]. Nothing here touches a database
+//! or a network.
+
+use axum::Router;
+use axum::body::Body;
+use axum::extract::{Path, Request, State};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{any, get};
+use axum_extra::headers::authorization::{Basic, Bearer};
+use axum_extra::headers::{Authorization, HeaderMapExt};
+use http::{HeaderMap, StatusCode};
+use http_body_util::BodyExt;
+use std::sync::Arc;
+
+use crate::domain::error::EgressError;
+use crate::domain::model::{
+ BoxError, EgressTarget, GitEndpoint, McpDestination, McpServerSlug, ProxyRequest,
+ ProxyResponse, SessionToken,
+};
+use crate::domain::service::EgressService;
+
+#[cfg(test)]
+mod test;
+
+/// What the routes need: the service, and nothing else.
+///
+/// An `Arc` because axum clones state per request and the service holds
+/// connection pools that must not be cloned with it.
+pub struct EgressRouterState<Service> {
+ service: Arc<Service>,
+}
+
+impl<Service> EgressRouterState<Service> {
+ /// Wrap the service the routes call.
+ pub fn new(service: Arc<Service>) -> Self {
+ Self { service }
+ }
+}
+
+// Derived `Clone` would demand `Service: Clone`, which the service is not.
+impl<Service> Clone for EgressRouterState<Service> {
+ fn clone(&self) -> Self {
+ Self {
+ service: Arc::clone(&self.service),
+ }
+ }
+}
+
+/// The egress routes.
+///
+/// `/mcp` takes any method because the streamable transport uses three, and
+/// which are acceptable is the domain's allowlist to enforce, not this
+/// router's. `/git` is narrower only because axum needs a method filter to
+/// build a route at all.
+pub fn egress_router<Service>(state: EgressRouterState<Service>) -> Router
+where
+ Service: EgressService + 'static,
+{
+ Router::new()
+ .route("/health", get(health))
+ .route("/mcp/{slug}", any(mcp_handler::<Service>))
+ .route("/mcp-macro", any(macro_mcp_handler::<Service>))
+ .route(
+ "/git/{*path}",
+ get(git_handler::<Service>).post(git_handler::<Service>),
+ )
+ .with_state(state)
+}
+
+async fn health() -> &'static str {
+ "ok"
+}
+
+// `skip_all` on every handler is load-bearing: the request's headers carry the
+// sandbox's session token, and an instrument attribute that Debug-formatted
+// `request` would put it in the trace.
+#[tracing::instrument(skip_all, err, fields(%slug))]
+async fn mcp_handler<Service>(
+ State(state): State<EgressRouterState<Service>>,
+ Path(slug): Path<String>,
+ request: Request,
+) -> Result<Response, EgressError>
+where
+ Service: EgressService,
+{
+ // A slug that does not parse names no server, and that is the same answer
+ // as a slug naming nobody's server: not found, with nothing said about
+ // which of the two it was.
+ let slug = McpServerSlug::parse(&slug)
+ .ok_or_else(|| EgressError::Unroutable(format!("{slug} is not a server name")))?;
+
+ mcp_proxy(state, McpDestination::Connected(slug), request).await
+}
+
+/// Macro's own MCP server, on its own route rather than under `/mcp/{slug}`:
+/// with no name shared between the built-in server and the owner's connected
+/// apps, no connected app can collide with it.
+#[tracing::instrument(skip_all, err)]
+async fn macro_mcp_handler<Service>(
+ State(state): State<EgressRouterState<Service>>,
+ request: Request,
+) -> Result<Response, EgressError>
+where
+ Service: EgressService,
+{
+ mcp_proxy(state, McpDestination::Macro, request).await
+}
+
+/// One MCP request through the proxy, whichever destination its route named.
+async fn mcp_proxy<Service>(
+ state: EgressRouterState<Service>,
+ destination: McpDestination,
+ request: Request,
+) -> Result<Response, EgressError>
+where
+ Service: EgressService,
+{
+ let token = session_token(request.headers())?;
+ dispatch(state, token, EgressTarget::McpServer(destination), request).await
+}
+
+/// The whole git route: no repository in the path, because the session has
+/// exactly one and the service reads it from the grant. The sandbox's remote
+/// is just `<egress>/git`, and git appends these suffixes itself.
+async fn git_handler<Service>(
+ State(state): State<EgressRouterState<Service>>,
+ Path(path): Path<String>,
+ request: Request,
+) -> Result<Response, GitRefusal>
+where
+ Service: EgressService,
+{
+ git_proxy(state, path, request).await.map_err(GitRefusal)
+}
+
+/// One git smart-HTTP request through the proxy.
+#[tracing::instrument(skip_all, err, fields(%path))]
+async fn git_proxy<Service>(
+ state: EgressRouterState<Service>,
+ path: String,
+ request: Request,
+) -> Result<Response, EgressError>
+where
+ Service: EgressService,
+{
+ let token = session_token(request.headers())?;
+
+ let endpoint = GitEndpoint::parse(&path, request.uri().query()).ok_or_else(|| {
+ EgressError::Unroutable(format!("git endpoint {path} is not served here"))
+ })?;
+
+ dispatch(state, token, EgressTarget::GitHubGit { endpoint }, request).await
+}
+
+/// A refusal on the git route, which renders like any other except that an
+/// unauthenticated one advertises Basic.
+///
+/// The advertisement is load-bearing, and only on this route. git does not
+/// send a credential up front: it makes the request bare, and only reaches for
+/// its credential helper once the server asks. Asking is this header - libcurl
+/// picks an auth scheme from it, and with no header there is no scheme to
+/// pick, so git holds a perfectly good token it never sends and the clone
+/// fails as "Authentication failed" with nothing to point at the cause.
+///
+/// Not on `/mcp`, where the credential is a bearer token the client already
+/// sends up front, and where advertising Basic would only invite an MCP client
+/// to prompt somebody for a password that does not exist.
+struct GitRefusal(EgressError);
+
+impl IntoResponse for GitRefusal {
+ fn into_response(self) -> Response {
+ let unauthenticated = matches!(self.0, EgressError::Unauthenticated(_));
+ let mut response = self.0.into_response();
+ if unauthenticated {
+ response.headers_mut().insert(
+ http::header::WWW_AUTHENTICATE,
+ http::HeaderValue::from_static(r#"Basic realm="Macro egress", charset="UTF-8""#),
+ );
+ }
+ response
+ }
+}
+
+/// The shared tail of both proxies: hand the request to the domain service,
+/// converting the body types in both directions.
+async fn dispatch<Service>(
+ state: EgressRouterState<Service>,
+ token: SessionToken,
+ target: EgressTarget,
+ request: Request,
+) -> Result<Response, EgressError>
+where
+ Service: EgressService,
+{
+ let response = state
+ .service
+ .proxy(&token, target, into_proxy_request(request))
+ .await?;
+
+ Ok(from_proxy_response(response))
+}
+
+/// Read the session token off a request.
+///
+/// Both schemes are accepted because git cannot manage the first: it only
+/// knows how to hand a credential helper's username and password to Basic
+/// auth, so the token arrives as the password. The username half is whatever
+/// the helper chose and carries no meaning here.
+fn session_token(headers: &HeaderMap) -> Result<SessionToken, EgressError> {
+ if let Some(Authorization(bearer)) = headers.typed_get::<Authorization<Bearer>>() {
+ return Ok(SessionToken::new(bearer.token()));
+ }
+
+ headers
+ .typed_get::<Authorization<Basic>>()
+ .map(|Authorization(basic)| SessionToken::new(basic.password()))
+ .ok_or(EgressError::Unauthenticated("no session token presented"))
+}
+
+/// axum's body is already an `http_body::Body`, so this is an error-type
+/// change and a box, not a copy. Collecting instead would break both things
+/// this proxy carries: event streams that stay open for a tool call, and
+/// packfiles the size of a repository.
+fn into_proxy_request(request: Request) -> ProxyRequest {
+ let (parts, body) = request.into_parts();
+ ProxyRequest::from_parts(
+ parts,
+ body.map_err(|error| Box::new(error) as BoxError)
+ .boxed_unsync(),
+ )
+}
+
+fn from_proxy_response(response: ProxyResponse) -> Response {
+ let (parts, body) = response.into_parts();
+ Response::from_parts(parts, Body::new(body))
+}
+
+impl IntoResponse for EgressError {
+ fn into_response(self) -> Response {
+ let status = match &self {
+ Self::Unauthenticated(_) | Self::SessionClosed => StatusCode::UNAUTHORIZED,
+ Self::UnknownServer(_) | Self::Unroutable(_) => StatusCode::NOT_FOUND,
+ Self::RepoUnavailable(_) => StatusCode::FORBIDDEN,
+ Self::MethodNotAllowed(_) => StatusCode::METHOD_NOT_ALLOWED,
+ // The named upstream is unusable as configured. Someone has to
+ // fix the URL; the agent cannot.
+ Self::InsecureUpstream(_) => StatusCode::BAD_GATEWAY,
+ Self::Upstream(_) => StatusCode::BAD_GATEWAY,
+ Self::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,
+ };
+
+ // Fixed text, never the error's own `Display`. An `EgressError`
+ // carries a `rootcause::Report`, a reqwest failure, or an upstream URL,
+ // and any of those can quote the request that produced it - which is a
+ // request we had just stamped the owner's credential onto. Detail goes
+ // to `tracing`, where the person debugging can see it and the model
+ // cannot.
+ let body = match &self {
+ Self::Unauthenticated(reason) => {
+ return (status, format!("Not authorized: {reason}.")).into_response();
+ }
+ Self::SessionClosed => "This session is no longer open.",
+ Self::Unroutable(_) => "Nothing is served at that path.",
+ Self::UnknownServer(_) => "No such connected MCP server.",
+ Self::RepoUnavailable(_) => {
+ "This session's repository is not reachable with Macro's GitHub App."
+ }
+ Self::MethodNotAllowed(_) => "That method is not allowed here.",
+ Self::InsecureUpstream(_) => "That upstream is misconfigured and cannot be reached.",
+ Self::Upstream(_) => "The upstream could not be reached.",
+ Self::Internal(_) => "Egress failed.",
+ };
+
+ (status, body).into_response()
+ }
+}
diff --git a/crates/agent_egress/src/inbound/axum_router/test.rs b/crates/agent_egress/src/inbound/axum_router/test.rs
new file mode 100644
index 0000000000..24c50d35a9
--- /dev/null
+++ b/crates/agent_egress/src/inbound/axum_router/test.rs
@@ -0,0 +1,275 @@
+use super::*;
+use crate::domain::model::{GitService, ProxyBody, RepoSlug};
+use axum::body::to_bytes;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use http::Method;
+use http::header::AUTHORIZATION;
+use http_body_util::Empty;
+use std::sync::Mutex;
+use tower::ServiceExt;
+
+/// Records what the router decided, and answers however it was built to.
+struct SpyService {
+ seen: Mutex<Vec<(String, EgressTarget)>>,
+ answer: Option<EgressError>,
+}
+
+impl SpyService {
+ fn accepting() -> Arc<Self> {
+ Arc::new(Self {
+ seen: Mutex::default(),
+ answer: None,
+ })
+ }
+
+ fn refusing(answer: EgressError) -> Arc<Self> {
+ Arc::new(Self {
+ seen: Mutex::default(),
+ answer: Some(answer),
+ })
+ }
+
+ fn targets(&self) -> Vec<EgressTarget> {
+ self.seen
+ .lock()
+ .expect("lock")
+ .iter()
+ .map(|(_token, target)| target.clone())
+ .collect()
+ }
+
+ fn tokens(&self) -> Vec<String> {
+ self.seen
+ .lock()
+ .expect("lock")
+ .iter()
+ .map(|(token, _target)| token.clone())
+ .collect()
+ }
+}
+
+impl EgressService for SpyService {
+ async fn proxy(
+ &self,
+ token: &SessionToken,
+ target: EgressTarget,
+ _request: ProxyRequest,
+ ) -> Result<ProxyResponse, EgressError> {
+ self.seen
+ .lock()
+ .expect("lock")
+ .push((token.as_str().to_owned(), target));
+
+ match &self.answer {
+ None => {
+ let body: ProxyBody = Empty::new().map_err(|never| match never {}).boxed_unsync();
+ let mut response = http::Response::new(body);
+ *response.status_mut() = StatusCode::ACCEPTED;
+ Ok(response)
+ }
+ Some(EgressError::RepoUnavailable(repo)) => {
+ Err(EgressError::RepoUnavailable(repo.clone()))
+ }
+ Some(EgressError::MethodNotAllowed(method)) => {
+ Err(EgressError::MethodNotAllowed(method.clone()))
+ }
+ Some(EgressError::SessionClosed) => Err(EgressError::SessionClosed),
+ Some(EgressError::Upstream(_)) => {
+ Err(EgressError::Upstream(rootcause::report!("unreachable")))
+ }
+ Some(_) => Err(EgressError::Unauthenticated("refused by the spy")),
+ }
+ }
+}
+
+async fn call(service: &Arc<SpyService>, request: Request) -> Response {
+ egress_router(EgressRouterState::new(Arc::clone(service)))
+ .oneshot(request)
+ .await
+ .expect("infallible")
+}
+
+fn get(uri: &str, authorization: Option<&str>) -> Request {
+ let mut builder = Request::builder().method(Method::GET).uri(uri);
+ if let Some(value) = authorization {
+ builder = builder.header(AUTHORIZATION, value);
+ }
+ builder.body(Body::empty()).expect("request")
+}
+
+async fn body_text(response: Response) -> String {
+ let bytes = to_bytes(response.into_body(), 64 * 1024)
+ .await
+ .expect("body");
+ String::from_utf8(bytes.to_vec()).expect("utf8")
+}
+
+#[tokio::test]
+async fn serves_health_without_a_token() {
+ let service = SpyService::accepting();
+ let response = call(&service, get("/health", None)).await;
+
+ assert_eq!(response.status(), StatusCode::OK);
+ assert_eq!(body_text(response).await, "ok");
+}
+
+#[tokio::test]
+async fn routes_a_slug_to_an_mcp_target() {
+ let service = SpyService::accepting();
+ let response = call(&service, get("/mcp/datadog", Some("Bearer session"))).await;
+
+ assert_eq!(response.status(), StatusCode::ACCEPTED);
+ assert_eq!(
+ service.targets(),
+ [EgressTarget::McpServer(McpDestination::Connected(
+ McpServerSlug::parse("datadog").expect("slug")
+ ))]
+ );
+}
+
+/// git speaks to us through a credential helper, which can only present a
+/// token as a Basic password. Both spellings have to reach the same session.
+#[tokio::test]
+async fn accepts_the_token_as_a_bearer_or_as_a_basic_password() {
+ let service = SpyService::accepting();
+
+ call(&service, get("/mcp/datadog", Some("Bearer the-token"))).await;
+ let basic = format!("Basic {}", BASE64.encode("x-access-token:the-token"));
+ call(&service, get("/mcp/datadog", Some(&basic))).await;
+
+ assert_eq!(service.tokens(), ["the-token", "the-token"]);
+}
+
+#[tokio::test]
+async fn a_request_without_a_token_never_reaches_the_service() {
+ let service = SpyService::accepting();
+ let response = call(&service, get("/mcp/datadog", None)).await;
+
+ assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+ assert!(service.targets().is_empty());
+}
+
+/// The sandbox's remote is just `<egress>/git`; git appends the smart-HTTP
+/// suffix itself, and there is nowhere in the route for it to name a
+/// repository.
+#[tokio::test]
+async fn routes_a_git_path_to_an_allowlisted_endpoint() {
+ let service = SpyService::accepting();
+ let response = call(
+ &service,
+ get(
+ "/git/info/refs?service=git-upload-pack",
+ Some("Bearer session"),
+ ),
+ )
+ .await;
+
+ assert_eq!(response.status(), StatusCode::ACCEPTED);
+ assert_eq!(
+ service.targets(),
+ [EgressTarget::GitHubGit {
+ endpoint: GitEndpoint::InfoRefs {
+ service: GitService::UploadPack
+ },
+ }]
+ );
+}
+
+/// The dumb-HTTP object endpoints are not in the allowlist, so they are not
+/// routed - the service never sees them and no credential is minted.
+#[tokio::test]
+async fn a_git_path_outside_the_allowlist_is_not_routed() {
+ let service = SpyService::accepting();
+ let response = call(
+ &service,
+ get("/git/objects/ab/cdef0123456789", Some("Bearer session")),
+ )
+ .await;
+
+ assert_eq!(response.status(), StatusCode::NOT_FOUND);
+ assert!(service.targets().is_empty());
+}
+
+#[tokio::test]
+async fn maps_each_refusal_to_the_status_that_tells_the_agent_what_to_do() {
+ for (error, expected) in [
+ (
+ EgressError::Unauthenticated("unknown session token"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (EgressError::SessionClosed, StatusCode::UNAUTHORIZED),
+ (
+ EgressError::RepoUnavailable(RepoSlug::parse("other", "repo").expect("slug")),
+ StatusCode::FORBIDDEN,
+ ),
+ (
+ EgressError::MethodNotAllowed(Method::PUT),
+ StatusCode::METHOD_NOT_ALLOWED,
+ ),
+ (
+ EgressError::Upstream(rootcause::report!("nope")),
+ StatusCode::BAD_GATEWAY,
+ ),
+ ] {
+ let service = SpyService::refusing(error);
+ let response = call(&service, get("/mcp/datadog", Some("Bearer session"))).await;
+ assert_eq!(response.status(), expected);
+ }
+}
+
+/// The sandbox runs model-authored code, so a response body is something the
+/// model reads. An upstream or transport failure whose `Display` quotes the
+/// request it failed on would be quoting a request we had just stamped a
+/// credential onto.
+#[tokio::test]
+async fn an_error_body_never_carries_internal_detail() {
+ let service = SpyService::refusing(EgressError::Upstream(rootcause::report!(
+ "POST https://mcp.example.com/mcp failed: authorization: Bearer dd-oauth-token"
+ )));
+ let response = call(&service, get("/mcp/datadog", Some("Bearer session"))).await;
+
+ let body = body_text(response).await;
+ assert!(!body.contains("dd-oauth-token"), "{body}");
+ assert!(!body.contains("mcp.example.com"), "{body}");
+ assert_eq!(body, "The upstream could not be reached.");
+}
+
+/// git makes its first request bare and only consults its credential helper
+/// once the server asks for authentication. Asking is this header: without it
+/// libcurl has no auth scheme to choose, so git never sends the token it
+/// already holds and the clone dies as "Authentication failed".
+#[tokio::test]
+async fn an_unauthenticated_git_request_is_told_to_use_basic() {
+ let service = SpyService::accepting();
+ let response = call(
+ &service,
+ get("/git/info/refs?service=git-upload-pack", None),
+ )
+ .await;
+
+ assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+ assert_eq!(
+ response
+ .headers()
+ .get(http::header::WWW_AUTHENTICATE)
+ .and_then(|value| value.to_str().ok()),
+ Some(r#"Basic realm="Macro egress", charset="UTF-8""#)
+ );
+}
+
+/// Only git needs the challenge. An MCP client sends its bearer token up
+/// front, and advertising Basic would invite it to prompt for a password that
+/// does not exist.
+#[tokio::test]
+async fn an_unauthenticated_mcp_request_is_not_told_to_use_basic() {
+ let service = SpyService::accepting();
+ let response = call(&service, get("/mcp/datadog", None)).await;
+
+ assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+ assert!(
+ !response
+ .headers()
+ .contains_key(http::header::WWW_AUTHENTICATE)
+ );
+}
diff --git a/crates/agent_egress/src/inbound/mod.rs b/crates/agent_egress/src/inbound/mod.rs
new file mode 100644
index 0000000000..1be7677c36
--- /dev/null
+++ b/crates/agent_egress/src/inbound/mod.rs
@@ -0,0 +1,4 @@
+//! Adapters the sandbox reaches this crate through.
+
+/// The sandbox-facing HTTP routes.
+pub mod axum_router;
diff --git a/crates/agent_egress/src/lib.rs b/crates/agent_egress/src/lib.rs
new file mode 100644
index 0000000000..34c8130034
--- /dev/null
+++ b/crates/agent_egress/src/lib.rs
@@ -0,0 +1,56 @@
+#![deny(missing_docs)]
+//! Credential-stamping egress for agent sandboxes.
+//!
+//! An agent session runs in a sandbox executing model-authored code with
+//! every permission allowed. Anything handed to that sandbox has been handed
+//! to the model, so the sandbox holds exactly one secret: a short-lived
+//! session token minted by the harness. Every upstream credential - the
+//! Pipedream project token that spends the owner's connected apps, GitHub
+//! App installation tokens - stays here, and is stamped onto requests as
+//! they pass through.
+//!
+//! That is the whole point of the indirection. A proxy that only forwarded
+//! bytes would be pointless; this one is the single place where "which
+//! upstream, on whose behalf, with which credential" is decided, and so also
+//! the single place where it can be scoped, refused, and logged.
+//!
+//! One request, end to end:
+//!
+//! 1. the sandbox calls the proxy, presenting its session token
+//! 2. [`ports::SessionAuthority`] turns that token into a
+//! [`model::SessionGrant`] - which session, and whose credentials it may
+//! spend - or refuses it because the token is bad, expired, or the session
+//! has since closed
+//! 3. one of two credential ports resolves the destination:
+//! [`ports::McpCredentials`] finds the named app among *that owner's*
+//! Pipedream connections and produces our project bearer plus the
+//! `x-pd-*` headers that pin it to that owner and app, or
+//! [`ports::GithubTokens`] mints an installation token scoped to the
+//! session's own repository
+//! 4. the service strips the sandbox's own credentials from the request and
+//! hands it to [`ports::Forwarder`] with the upstream one stamped on
+//!
+//! Steps 2 and 3 are the substance and live in
+//! [`service::EgressServiceImpl`]. Step 4's byte-shovelling is deliberately a
+//! port: forwarding is transport mechanics, and keeping it outside lets the
+//! decisions be tested without a socket.
+//!
+//! The sandbox never names a destination, and that is the property everything
+//! else rests on. For MCP it names an app slug, which resolves only through
+//! the owner's own rows, so it cannot ask to act as anyone its owner is not -
+//! which matters doubly here, because the Pipedream bearer alone could act as
+//! anyone, and the header saying *who* is stamped from the session's grant.
+//! For git it names nothing at all: the repository comes from the session's
+//! grant, and the endpoint from a three-entry allowlist.
+
+/// Domain models, ports, errors, and the service that decides what gets
+/// stamped onto which upstream.
+pub mod domain;
+
+/// Adapters the sandbox reaches this crate through.
+pub mod inbound;
+
+/// Adapters this crate reaches the rest of the world through.
+pub mod outbound;
+
+pub use domain::{error, model, ports, service};
diff --git a/crates/agent_egress/src/outbound/forwarder.rs b/crates/agent_egress/src/outbound/forwarder.rs
new file mode 100644
index 0000000000..eb36e07074
--- /dev/null
+++ b/crates/agent_egress/src/outbound/forwarder.rs
@@ -0,0 +1,78 @@
+//! Executing a request that has already been decided.
+//!
+//! The dumbest adapter in the crate, deliberately. By the time a request
+//! arrives here it is addressed at its upstream and stamped with the right
+//! credential, so there is nothing left to decide and nothing here should look
+//! like a decision.
+
+use http_body_util::{BodyDataStream, BodyExt};
+use reqwest::redirect;
+
+use crate::domain::error::EgressError;
+use crate::domain::model::{BoxError, ProxyRequest, ProxyResponse};
+use crate::domain::ports::Forwarder;
+
+/// Forwards over a shared reqwest client.
+pub struct ReqwestForwarder {
+ client: reqwest::Client,
+}
+
+impl ReqwestForwarder {
+ /// Build the forwarder.
+ ///
+ /// Two settings are load-bearing:
+ ///
+ /// - `redirect::Policy::none()`. reqwest follows up to ten redirects by
+ /// default, which would replay a request - stamped credential and all -
+ /// at whatever host the response named. A redirect is the upstream's
+ /// answer and belongs to the caller, who can decide about it.
+ /// - no timeout. `Client::timeout` bounds the *whole* request including the
+ /// response body, and both bodies here are long-lived by design: an MCP
+ /// event stream stays open for a tool call, a packfile takes as long as
+ /// the repository is big.
+ pub fn new() -> Result<Self, EgressError> {
+ let client = reqwest::Client::builder()
+ .redirect(redirect::Policy::none())
+ .build()
+ .map_err(|error| {
+ EgressError::Internal(rootcause::report!(
+ "could not build the egress http client: {error}"
+ ))
+ })?;
+
+ Ok(Self { client })
+ }
+}
+
+impl Forwarder for ReqwestForwarder {
+ #[tracing::instrument(skip_all, err, fields(
+ method = %request.method(),
+ host = request.uri().host(),
+ status = tracing::field::Empty,
+ ))]
+ async fn forward(&self, request: ProxyRequest) -> Result<ProxyResponse, EgressError> {
+ // Streamed both ways. `wrap_stream` rather than `Body::wrap` because
+ // the latter wants a `Sync` body and a request body arriving off a
+ // socket is not one; the cost is trailers, which neither MCP nor git
+ // sends.
+ let request = request.map(|body| reqwest::Body::wrap_stream(BodyDataStream::new(body)));
+ let request = reqwest::Request::try_from(request).map_err(|error| {
+ EgressError::Internal(rootcause::report!("request is not sendable: {error}"))
+ })?;
+
+ let response = self.client.execute(request).await.map_err(|error| {
+ EgressError::Upstream(rootcause::report!("upstream did not answer: {error}"))
+ })?;
+ tracing::Span::current().record("status", response.status().as_u16());
+
+ // Statuses pass through untouched, including failures: MCP and git both
+ // use them semantically, and swallowing a 401 into an error of our own
+ // is how a caller ends up with an unexplained hang.
+ let response: http::Response<reqwest::Body> = response.into();
+
+ Ok(response.map(|body| {
+ body.map_err(|error| Box::new(error) as BoxError)
+ .boxed_unsync()
+ }))
+ }
+}
diff --git a/crates/agent_egress/src/outbound/github_tokens.rs b/crates/agent_egress/src/outbound/github_tokens.rs
new file mode 100644
index 0000000000..5f1f6c082d
--- /dev/null
+++ b/crates/agent_egress/src/outbound/github_tokens.rs
@@ -0,0 +1,183 @@
+//! Git credentials for the session's repository.
+//!
+//! The minting itself - proving we are the App, finding the installation,
+//! checking it belongs to the session's owner, cutting the token down to one
+//! repository - belongs to the `github` crate, which owns everything else we
+//! know about GitHub. This adapter asks for a token, says which permissions a
+//! coding agent needs, and turns the answer into something the proxy can stamp.
+//!
+//! What it adds on top is a cache. A token is good for an hour and a clone can
+//! be issued many times over a session's life, so re-minting per request would
+//! spend rate limit for nothing.
+
+use chrono::{DateTime, Duration as ChronoDuration, Utc};
+use github::domain::models::GithubError;
+use github::domain::ports::{GithubSyncClient, GithubSyncRepo};
+use github::domain::service::InstallationTokenService;
+use lru::LruCache;
+use macro_user_id::user_id::MacroUserIdStr;
+use std::num::NonZeroUsize;
+use std::sync::Mutex;
+use url::Url;
+
+use crate::domain::error::EgressError;
+use crate::domain::model::{RepoSlug, UpstreamCall};
+use crate::domain::ports::GithubTokens;
+
+#[cfg(test)]
+mod test;
+
+/// The git base every repository URL is built from.
+///
+/// A hardcoded constant, and that is load-bearing rather than incidental. The
+/// repository comes from `grant.repo`, which comes from claims we signed
+/// ourselves, and `RepoSlug::parse` excludes every character that could rewrite
+/// a URL's host or path. Together with this constant, the destination of a
+/// stamped git request cannot be anything but the session's own repository on
+/// GitHub - which is why there is no separate check that it is.
+///
+/// Do not make this configuration. Moving it into an env var moves the
+/// guarantee above into whatever sets that env var.
+const GITHUB_GIT_BASE: &str = "https://github.com";
+
+/// The username half of git's Basic auth. GitHub ignores it, but git's
+/// credential protocol has nowhere to put a token except the password, so
+/// something has to go here; this is the value GitHub documents.
+const GIT_BASIC_USERNAME: &str = "x-access-token";
+
+/// What a coding agent working a pull request needs, and no more: read and
+/// write the code, open and comment on pull requests, read the repository's own
+/// metadata. Notably absent is anything that changes repository settings.
+const AGENT_PERMISSIONS: &[(&str, &str)] = &[
+ ("contents", "write"),
+ ("pull_requests", "write"),
+ ("metadata", "read"),
+];
+
+/// How long before expiry a cached token stops being handed out.
+///
+/// A packfile transfer can take minutes, and a token that expires mid-transfer
+/// fails the whole clone.
+const EXPIRY_MARGIN_MINUTES: i64 = 5;
+
+/// How many (owner, repository) tokens are kept at once. Far past any real
+/// concurrency; the bound exists so entries for owners who never come back
+/// are eventually evicted instead of holding expired credentials forever.
+const CACHE_CAPACITY: usize = 1024;
+
+/// Hands out git credentials, caching each until it is nearly stale.
+pub struct GithubAppTokens<Installations, Client> {
+ tokens: InstallationTokenService<Installations, Client>,
+ /// Keyed by repository *and* owner: a cached token must never stand in for
+ /// an ownership check that did not happen for this user. Bounded, so the
+ /// map cannot grow with every owner ever seen; freshness still comes from
+ /// each token's own expiry, never from cache residency.
+ cached: Mutex<LruCache<(MacroUserIdStr<'static>, RepoSlug), CachedToken>>,
+}
+
+#[derive(Clone)]
+struct CachedToken {
+ token: String,
+ expires_at: DateTime<Utc>,
+}
+
+impl<Installations, Client> GithubAppTokens<Installations, Client>
+where
+ Installations: GithubSyncRepo,
+ Client: GithubSyncClient,
+{
+ /// Wrap the `github` crate's minting service with a cache.
+ pub fn new(tokens: InstallationTokenService<Installations, Client>) -> Self {
+ Self {
+ tokens,
+ cached: Mutex::new(LruCache::new(
+ NonZeroUsize::new(CACHE_CAPACITY).expect("a nonzero capacity"),
+ )),
+ }
+ }
+
+ async fn token(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ repo: &RepoSlug,
+ ) -> Result<String, EgressError> {
+ let key = (owner.clone(), repo.clone());
+
+ {
+ let mut cached = self.cached.lock().expect("token cache poisoned");
+ match usable(cached.get(&key).cloned()) {
+ Some(live) => {
+ tracing::debug!(%owner, %repo, "github token cache hit");
+ return Ok(live.token);
+ }
+ // A stale entry is evicted now rather than on capacity
+ // pressure: there is no reason to keep a dead credential.
+ None => {
+ let expired = cached.pop(&key).is_some();
+ tracing::debug!(%owner, %repo, expired, "github token cache miss; minting");
+ }
+ }
+ }
+
+ let minted = self
+ .tokens
+ .for_repository(owner, repo.owner(), repo.name(), AGENT_PERMISSIONS)
+ .await
+ .map_err(|error| match error {
+ GithubError::RepositoryUnavailable => EgressError::RepoUnavailable(repo.clone()),
+ other => EgressError::Upstream(rootcause::report!(
+ "could not mint a github token: {other}"
+ )),
+ })?;
+
+ let expires_at = minted
+ .expires_at()
+ .map_err(|error| EgressError::Upstream(rootcause::report!("{error}")))?;
+
+ self.cached.lock().expect("token cache poisoned").put(
+ key,
+ CachedToken {
+ token: minted.token.clone(),
+ expires_at,
+ },
+ );
+
+ Ok(minted.token)
+ }
+}
+
+impl<Installations, Client> GithubTokens for GithubAppTokens<Installations, Client>
+where
+ Installations: GithubSyncRepo,
+ Client: GithubSyncClient,
+{
+ #[tracing::instrument(skip_all, err, fields(%owner, %repo))]
+ async fn resolve(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ repo: &RepoSlug,
+ ) -> Result<UpstreamCall, EgressError> {
+ let token = self.token(owner, repo).await?;
+
+ // Trailing slash: the domain appends the git endpoint to this, and a
+ // URL join replaces the last segment rather than extending it without
+ // one.
+ let url = Url::parse(&format!(
+ "{GITHUB_GIT_BASE}/{}/{}.git/",
+ repo.owner(),
+ repo.name()
+ ))
+ .map_err(|error| {
+ EgressError::Internal(rootcause::report!("repository url is not a url: {error}"))
+ })?;
+
+ UpstreamCall::basic(url, GIT_BASIC_USERNAME, token)
+ }
+}
+
+/// A cached token, if it will still be valid long enough to be worth using.
+fn usable(cached: Option<CachedToken>) -> Option<CachedToken> {
+ let cached = cached?;
+ let deadline = Utc::now() + ChronoDuration::minutes(EXPIRY_MARGIN_MINUTES);
+ (cached.expires_at > deadline).then_some(cached)
+}
diff --git a/crates/agent_egress/src/outbound/github_tokens/test.rs b/crates/agent_egress/src/outbound/github_tokens/test.rs
new file mode 100644
index 0000000000..34a0227444
--- /dev/null
+++ b/crates/agent_egress/src/outbound/github_tokens/test.rs
@@ -0,0 +1,18 @@
+use super::*;
+
+fn cached(expires_in_minutes: i64) -> CachedToken {
+ CachedToken {
+ token: "ghs-token".to_owned(),
+ expires_at: Utc::now() + ChronoDuration::minutes(expires_in_minutes),
+ }
+}
+
+/// A clone can take minutes, so a token that is about to expire is worse than
+/// no token: it fails halfway through a packfile instead of at the start.
+#[test]
+fn a_nearly_expired_cached_token_is_not_reused() {
+ assert!(usable(None).is_none());
+ assert!(usable(Some(cached(-1))).is_none());
+ assert!(usable(Some(cached(EXPIRY_MARGIN_MINUTES - 1))).is_none());
+ assert!(usable(Some(cached(EXPIRY_MARGIN_MINUTES + 1))).is_some());
+}
diff --git a/crates/agent_egress/src/outbound/macro_mcp.rs b/crates/agent_egress/src/outbound/macro_mcp.rs
new file mode 100644
index 0000000000..6c1d2dedca
--- /dev/null
+++ b/crates/agent_egress/src/outbound/macro_mcp.rs
@@ -0,0 +1,294 @@
+//! Macro's own MCP server, answered on its own route.
+//!
+//! Unlike the owner's connected apps, this destination is not resolved from
+//! their rows - every session gets it, because every session's owner is a
+//! Macro user. What has to be resolved per owner is the credential:
+//! `mcp_service` authenticates a *user*, so the proxy exchanges the session
+//! owner's identity for a short-lived Macro API token and stamps that.
+//!
+//! The exchange is local signing with the same RS256 key
+//! `authentication_service` uses - this process holds a key that can
+//! impersonate any user at every service accepting Macro API tokens. That
+//! custody is the cost of not putting a mint-for-anyone endpoint on the
+//! network; what limits the blast radius is that every token minted here is
+//! single-user, scoped to the session's owner, and minutes from expiry.
+
+use chrono::{DateTime, Duration as ChronoDuration, TimeZone, Utc};
+use lru::LruCache;
+use macro_auth::macro_api_token::{EncodeMacroApiTokenArgs, encode_macro_api_token};
+use macro_user_id::user_id::MacroUserIdStr;
+use std::num::NonZeroUsize;
+use std::sync::Mutex;
+use url::Url;
+
+use crate::domain::error::EgressError;
+use crate::domain::model::{BearerToken, McpDestination, UpstreamCall};
+use crate::domain::ports::McpCredentials;
+
+#[cfg(test)]
+mod test;
+
+/// How long before expiry a cached token stops being handed out. A tool call
+/// can stream for a while, and a token that expires mid-call fails it.
+const EXPIRY_MARGIN_MINUTES: i64 = 5;
+
+/// Exchange a session owner's identity for a short-lived Macro API token.
+///
+/// Implementations own the whole exchange - including finding whatever else
+/// the minting side needs to know about the owner beyond their id.
+pub trait MacroApiTokens: Send + Sync {
+ /// A token that acts as `owner`, and nobody else.
+ fn mint(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ ) -> impl Future<Output = Result<String, EgressError>> + Send;
+}
+
+/// Layers Macro's own MCP destination over another resolver.
+///
+/// [`McpDestination::Macro`] is answered here; everything else passes
+/// straight through to `Inner`. The two destinations arrive from different
+/// routes, so there is no name for a connected app to collide with.
+pub struct WithMacroMcp<Inner, Tokens> {
+ inner: Inner,
+ tokens: Tokens,
+ url: Url,
+ /// Whether [`UpstreamCall::bearer_over_local_cleartext`] is permitted.
+ /// Set only by a composition root that has checked `ENVIRONMENT=local`.
+ local_cleartext: bool,
+ /// Keyed by owner: the token *is* the owner's identity, so a cache hit
+ /// for one owner can never answer for another. Bounded, so the map cannot
+ /// grow with every owner ever seen; freshness still comes from each
+ /// token's own expiry, never from cache residency.
+ cached: Mutex<LruCache<MacroUserIdStr<'static>, CachedToken>>,
+}
+
+/// How many owners' tokens are kept at once. Far past any real concurrency;
+/// the bound exists so entries for owners who never come back are eventually
+/// evicted instead of holding expired credentials forever.
+const CACHE_CAPACITY: usize = 1024;
+
+#[derive(Clone)]
+struct CachedToken {
+ token: String,
+ expires_at: DateTime<Utc>,
+}
+
+impl<Inner, Tokens> WithMacroMcp<Inner, Tokens>
+where
+ Inner: McpCredentials,
+ Tokens: MacroApiTokens,
+{
+ /// Wrap `inner`, answering [`McpDestination::Macro`] at `url` with tokens
+ /// from `tokens`.
+ ///
+ /// `local_cleartext` permits an `http` URL, and the caller must gate it on
+ /// `ENVIRONMENT=local` - it exists for the one destination that never
+ /// leaves the machine, the local stack's own `mcp-service` across the
+ /// compose bridge. Refused here, at boot, rather than at the first tool
+ /// call: a deployed environment with a cleartext URL is misconfigured,
+ /// not unlucky.
+ pub fn new(
+ inner: Inner,
+ tokens: Tokens,
+ url: Url,
+ local_cleartext: bool,
+ ) -> Result<Self, EgressError> {
+ if url.scheme() != "https" && !local_cleartext {
+ return Err(EgressError::InsecureUpstream(url));
+ }
+
+ Ok(Self {
+ inner,
+ tokens,
+ url,
+ local_cleartext,
+ cached: Mutex::new(LruCache::new(
+ NonZeroUsize::new(CACHE_CAPACITY).expect("a nonzero capacity"),
+ )),
+ })
+ }
+
+ async fn token(&self, owner: &MacroUserIdStr<'static>) -> Result<String, EgressError> {
+ {
+ let mut cached = self.cached.lock().expect("token cache poisoned");
+ match usable(cached.get(owner).cloned()) {
+ Some(live) => {
+ tracing::debug!(%owner, "macro api token cache hit");
+ return Ok(live.token);
+ }
+ // A stale entry is evicted now rather than on capacity
+ // pressure: there is no reason to keep a dead credential.
+ None => {
+ let expired = cached.pop(owner).is_some();
+ tracing::debug!(%owner, expired, "macro api token cache miss; minting");
+ }
+ }
+ }
+
+ let token = self.tokens.mint(owner).await?;
+ let expires_at = token_expiry(&token)?;
+ self.cached.lock().expect("token cache poisoned").put(
+ owner.clone(),
+ CachedToken {
+ token: token.clone(),
+ expires_at,
+ },
+ );
+
+ Ok(token)
+ }
+}
+
+impl<Inner, Tokens> McpCredentials for WithMacroMcp<Inner, Tokens>
+where
+ Inner: McpCredentials,
+ Tokens: MacroApiTokens,
+{
+ #[tracing::instrument(skip_all, err, fields(%owner, ?destination))]
+ async fn resolve(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ destination: &McpDestination,
+ ) -> Result<UpstreamCall, EgressError> {
+ if *destination != McpDestination::Macro {
+ return self.inner.resolve(owner, destination).await;
+ }
+
+ let token = BearerToken::new(self.token(owner).await?);
+ if self.local_cleartext && self.url.scheme() != "https" {
+ Ok(UpstreamCall::bearer_over_local_cleartext(
+ self.url.clone(),
+ token,
+ ))
+ } else {
+ UpstreamCall::bearer(self.url.clone(), token)
+ }
+ }
+}
+
+/// A cached token, if it will still be valid long enough to be worth using.
+fn usable(cached: Option<CachedToken>) -> Option<CachedToken> {
+ let cached = cached?;
+ let deadline = Utc::now() + ChronoDuration::minutes(EXPIRY_MARGIN_MINUTES);
+ (cached.expires_at > deadline).then_some(cached)
+}
+
+/// When a freshly minted token expires, read off its own `exp` claim.
+///
+/// Read *unverified*, deliberately: this process signed the token itself
+/// moments ago, and it only needs the timestamp to schedule a re-mint -
+/// `mcp_service` is what verifies the signature before anything acts on the
+/// token.
+fn token_expiry(token: &str) -> Result<DateTime<Utc>, EgressError> {
+ use base64::Engine;
+
+ let unreadable = |detail: &str| {
+ EgressError::Upstream(rootcause::report!(
+ "minted Macro API token is unreadable: {detail}"
+ ))
+ };
+
+ let payload = token
+ .split('.')
+ .nth(1)
+ .ok_or_else(|| unreadable("not a three-part JWT"))?;
+ let payload = base64::engine::general_purpose::URL_SAFE_NO_PAD
+ .decode(payload)
+ .map_err(|_| unreadable("payload is not base64url"))?;
+
+ #[derive(serde::Deserialize)]
+ struct Claims {
+ exp: i64,
+ }
+ let claims: Claims =
+ serde_json::from_slice(&payload).map_err(|_| unreadable("payload has no exp claim"))?;
+
+ Utc.timestamp_opt(claims.exp, 0)
+ .single()
+ .ok_or_else(|| unreadable("exp is not a timestamp"))
+}
+
+/// Mints tokens by signing them here, with the same key
+/// `authentication_service` signs with.
+///
+/// Inline rather than a call to the auth service's mint endpoint: minting is
+/// one signature over facts this process can read itself, the shared
+/// `macro_auth` vocabulary exists exactly so key-holders sign locally (the
+/// document-permission JWT follows the same pattern), and this process is
+/// already the credential concentrator - it holds the GitHub App key and the
+/// Pipedream project token on the same terms. The key can act as any user
+/// wherever Macro API tokens are accepted, which is why everything minted
+/// here is short-lived and names only the one owner the grant did.
+pub struct MacroApiTokenSigner {
+ pool: sqlx::PgPool,
+ issuer: String,
+ private_key: String,
+}
+
+/// How long a minted token lives. Short on purpose - the cache re-mints
+/// freely - so a token that leaks out of a response somewhere is stale before
+/// anyone can do much with it.
+const MINTED_TOKEN_LIFETIME_SECONDS: usize = 900;
+
+impl MacroApiTokenSigner {
+ /// Build the signer over the database holding user rows, the token
+ /// issuer, and the RSA signing key.
+ pub fn new(
+ pool: sqlx::PgPool,
+ issuer: impl Into<String>,
+ private_key: impl Into<String>,
+ ) -> Self {
+ Self {
+ pool,
+ issuer: issuer.into(),
+ private_key: private_key.into(),
+ }
+ }
+}
+
+impl MacroApiTokens for MacroApiTokenSigner {
+ #[tracing::instrument(skip_all, err, fields(%owner))]
+ async fn mint(&self, owner: &MacroUserIdStr<'static>) -> Result<String, EgressError> {
+ // The claims name the owner three ways - the FusionAuth root id, the
+ // Macro user id, and their organization - and the session row only
+ // carries the second, so the rest is read off their `User` row. An
+ // owner with no row is a session created wrong, which is ours to fix,
+ // not something the sandbox can retry its way out of.
+ let (fusion_root_id, macro_user_id) =
+ macro_db_client::user::get::get_user_macro_user_id_and_id_by_email(
+ &self.pool,
+ owner.email_str(),
+ )
+ .await
+ .map_err(|error| {
+ EgressError::Internal(rootcause::report!(
+ "session owner has no user row to mint a token for: {error}"
+ ))
+ })?;
+ let organization_id = macro_db_client::user::get_user_organization::get_user_organization(
+ self.pool.clone(),
+ &macro_user_id,
+ )
+ .await
+ .map_err(|error| {
+ EgressError::Internal(rootcause::report!(
+ "could not read the session owner's organization: {error}"
+ ))
+ })?;
+
+ encode_macro_api_token(EncodeMacroApiTokenArgs {
+ fusionauth_id: fusion_root_id.to_string(),
+ macro_user_id,
+ organization_id,
+ issuer: self.issuer.clone(),
+ private_key: self.private_key.clone(),
+ expiry_seconds: MINTED_TOKEN_LIFETIME_SECONDS,
+ })
+ .map_err(|error| {
+ EgressError::Internal(rootcause::report!(
+ "could not sign a Macro API token: {error}"
+ ))
+ })
+ }
+}
diff --git a/crates/agent_egress/src/outbound/macro_mcp/test.rs b/crates/agent_egress/src/outbound/macro_mcp/test.rs
new file mode 100644
index 0000000000..8cb4e88557
--- /dev/null
+++ b/crates/agent_egress/src/outbound/macro_mcp/test.rs
@@ -0,0 +1,183 @@
+use super::*;
+use crate::domain::model::McpServerSlug;
+use std::sync::Mutex;
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+fn owner() -> MacroUserIdStr<'static> {
+ MacroUserIdStr::try_from_email("[email protected]").expect("a valid user id")
+}
+
+fn connected(slug: &str) -> McpDestination {
+ McpDestination::Connected(McpServerSlug::parse(slug).expect("a valid slug"))
+}
+
+/// A syntactically valid JWT whose payload carries `exp`, and nothing else
+/// real - `token_expiry` reads without verifying.
+fn jwt_expiring_at(exp: i64) -> String {
+ use base64::Engine;
+ let encode = |bytes: &[u8]| base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes);
+ format!(
+ "{}.{}.{}",
+ encode(br#"{"alg":"RS256","kid":"macro"}"#),
+ encode(format!(r#"{{"exp":{exp}}}"#).as_bytes()),
+ encode(b"unverified"),
+ )
+}
+
+/// Counts mints and answers with a fixed-expiry token.
+struct CountingTokens {
+ minted: AtomicUsize,
+ expires_at: DateTime<Utc>,
+}
+
+impl CountingTokens {
+ fn expiring_at(expires_at: DateTime<Utc>) -> Self {
+ Self {
+ minted: AtomicUsize::new(0),
+ expires_at,
+ }
+ }
+
+ fn fresh() -> Self {
+ Self::expiring_at(Utc::now() + ChronoDuration::hours(1))
+ }
+}
+
+impl MacroApiTokens for &CountingTokens {
+ async fn mint(&self, _owner: &MacroUserIdStr<'static>) -> Result<String, EgressError> {
+ let count = self.minted.fetch_add(1, Ordering::SeqCst) + 1;
+ Ok(format!(
+ "{}#{count}",
+ jwt_expiring_at(self.expires_at.timestamp())
+ ))
+ }
+}
+
+/// Records what reached it; the tests only care that delegation happened.
+#[derive(Default)]
+struct SpyInner {
+ asked: Mutex<Vec<String>>,
+}
+
+impl McpCredentials for &SpyInner {
+ async fn resolve(
+ &self,
+ _owner: &MacroUserIdStr<'static>,
+ destination: &McpDestination,
+ ) -> Result<UpstreamCall, EgressError> {
+ let McpDestination::Connected(slug) = destination else {
+ unreachable!("the decorator answers Macro's own destination itself");
+ };
+ self.asked.lock().expect("lock").push(slug.to_string());
+ Err(EgressError::UnknownServer(slug.clone()))
+ }
+}
+
+fn macro_url() -> Url {
+ Url::parse("https://mcp.macro.com/mcp").expect("url")
+}
+
+#[tokio::test]
+async fn answers_macros_own_destination_with_a_minted_token() {
+ let tokens = CountingTokens::fresh();
+ let inner = SpyInner::default();
+ let credentials = WithMacroMcp::new(&inner, &tokens, macro_url(), false).expect("constructed");
+
+ let call = credentials
+ .resolve(&owner(), &McpDestination::Macro)
+ .await
+ .expect("resolved");
+
+ assert_eq!(call.url().as_str(), "https://mcp.macro.com/mcp");
+ assert!(
+ inner.asked.lock().expect("lock").is_empty(),
+ "Macro's own destination must never consult the owner's rows"
+ );
+}
+
+/// The token is the owner's identity for its whole lifetime; re-minting per
+/// request would spend an exchange round trip on every tool call.
+#[tokio::test]
+async fn reuses_a_token_until_it_nears_expiry() {
+ let tokens = CountingTokens::fresh();
+ let inner = SpyInner::default();
+ let credentials = WithMacroMcp::new(&inner, &tokens, macro_url(), false).expect("constructed");
+
+ for _ in 0..3 {
+ credentials
+ .resolve(&owner(), &McpDestination::Macro)
+ .await
+ .expect("resolved");
+ }
+
+ assert_eq!(tokens.minted.load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn a_token_about_to_expire_is_replaced() {
+ // Inside the margin from the start, so every resolve re-mints.
+ let tokens = CountingTokens::expiring_at(Utc::now() + ChronoDuration::minutes(1));
+ let inner = SpyInner::default();
+ let credentials = WithMacroMcp::new(&inner, &tokens, macro_url(), false).expect("constructed");
+
+ for _ in 0..2 {
+ credentials
+ .resolve(&owner(), &McpDestination::Macro)
+ .await
+ .expect("resolved");
+ }
+
+ assert_eq!(tokens.minted.load(Ordering::SeqCst), 2);
+}
+
+#[tokio::test]
+async fn every_other_slug_delegates_to_the_inner_resolver() {
+ let tokens = CountingTokens::fresh();
+ let inner = SpyInner::default();
+ let credentials = WithMacroMcp::new(&inner, &tokens, macro_url(), false).expect("constructed");
+
+ let refusal = credentials
+ .resolve(&owner(), &connected("linear"))
+ .await
+ .expect_err("the spy refuses everything");
+
+ assert!(matches!(refusal, EgressError::UnknownServer(_)));
+ assert_eq!(*inner.asked.lock().expect("lock"), ["linear"]);
+ assert_eq!(tokens.minted.load(Ordering::SeqCst), 0);
+}
+
+/// A deployed environment pointing Macro's own MCP server at cleartext is
+/// misconfigured; it must fail at boot, not at the first tool call.
+#[tokio::test]
+async fn refuses_a_cleartext_url_unless_local_dev_permits_it() {
+ let tokens = CountingTokens::fresh();
+ let url = Url::parse("http://mcp-service:8080/mcp").expect("url");
+
+ let refusal = WithMacroMcp::new(&SpyInner::default(), &tokens, url.clone(), false)
+ .err()
+ .expect("refused");
+ assert!(matches!(refusal, EgressError::InsecureUpstream(_)));
+
+ let inner = SpyInner::default();
+ let permitted = WithMacroMcp::new(&inner, &tokens, url, true).expect("constructed");
+ let call = permitted
+ .resolve(&owner(), &McpDestination::Macro)
+ .await
+ .expect("resolved");
+ assert_eq!(call.url().as_str(), "http://mcp-service:8080/mcp");
+}
+
+#[test]
+fn reads_the_expiry_off_a_minted_token() {
+ let expires = Utc::now().timestamp() + 900;
+ let expiry = token_expiry(&jwt_expiring_at(expires)).expect("readable");
+ assert_eq!(expiry.timestamp(), expires);
+}
+
+#[test]
+fn an_unreadable_token_is_an_upstream_error() {
+ for garbage in ["", "not-a-jwt", "a.b.c", "a.!!!.c"] {
+ let refusal = token_expiry(garbage).expect_err(garbage);
+ assert!(matches!(refusal, EgressError::Upstream(_)), "{garbage}");
+ }
+}
diff --git a/crates/agent_egress/src/outbound/mcp_credentials.rs b/crates/agent_egress/src/outbound/mcp_credentials.rs
new file mode 100644
index 0000000000..b616b6869c
--- /dev/null
+++ b/crates/agent_egress/src/outbound/mcp_credentials.rs
@@ -0,0 +1,119 @@
+//! Resolving a slug to one of the owner's Pipedream-connected apps.
+//!
+//! There is no OAuth here to manage. Pipedream owns every user grant - the
+//! consent flow, the stored tokens, the refresh - and its remote MCP server
+//! injects the account's credentials server-side. What a request needs from
+//! us is our own project-level API token and the `x-pd-*` headers that say
+//! which user and app to act as, and *that* pair is exactly why this traffic
+//! must flow through the proxy: the bearer is project-wide, so whoever holds
+//! it picks the user. The sandbox never does; the user id is stamped from the
+//! session's grant.
+//!
+//! Both halves come from `pipedream_mcp`'s own ports - the same rows the chat
+//! tool path reads, the same client that dials Pipedream for it - so an app
+//! connected in Macro is an app the sandbox can reach, with nothing to keep
+//! in sync.
+
+use macro_user_id::user_id::MacroUserIdStr;
+use pipedream_mcp::domain::models::PipedreamConnection;
+use pipedream_mcp::domain::ports::ConnectionStore;
+use pipedream_mcp::outbound::api::McpUpstream;
+use std::sync::Arc;
+
+use crate::domain::error::EgressError;
+use crate::domain::model::{BearerToken, McpDestination, McpServerSlug, UpstreamCall};
+use crate::domain::ports::McpCredentials;
+
+#[cfg(test)]
+mod test;
+
+/// Resolves MCP slugs against an owner's Pipedream connections.
+pub struct PipedreamMcpCredentials<Connections, Upstream> {
+ connections: Arc<Connections>,
+ upstream: Upstream,
+}
+
+impl<Connections, Upstream> PipedreamMcpCredentials<Connections, Upstream>
+where
+ Connections: ConnectionStore,
+ Upstream: McpUpstream,
+{
+ /// Build the adapter over the store holding the owner's connections and
+ /// the client that addresses Pipedream's MCP server.
+ pub fn new(connections: Arc<Connections>, upstream: Upstream) -> Self {
+ Self {
+ connections,
+ upstream,
+ }
+ }
+
+ /// The owner's enabled connection whose `app_slug` is exactly `slug`.
+ ///
+ /// Scoped to the owner by the store call itself, and filtered to `enabled`
+ /// here because the store does not: a disabled connector is one the owner
+ /// turned off, and turning it off has to take the sandbox's access with it.
+ async fn connection(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ slug: &McpServerSlug,
+ ) -> Result<PipedreamConnection, EgressError> {
+ self.connections
+ .list(owner)
+ .await
+ .map_err(|error| {
+ EgressError::Internal(rootcause::report!(
+ "could not list Pipedream connections: {error:?}"
+ ))
+ })?
+ .into_iter()
+ .filter(|record| record.enabled)
+ // `app_slug`, not `server_name`: the app slug is Pipedream's
+ // stable identifier, and the display name is the user's to
+ // rename. The provisioner advertises the same value, and equality
+ // is the whole match - nothing is derived at either end.
+ .find(|record| record.app_slug == slug.as_str())
+ .ok_or_else(|| EgressError::UnknownServer(slug.clone()))
+ }
+}
+
+impl<Connections, Upstream> McpCredentials for PipedreamMcpCredentials<Connections, Upstream>
+where
+ Connections: ConnectionStore,
+ Upstream: McpUpstream,
+{
+ #[tracing::instrument(skip_all, err, fields(%owner, ?destination))]
+ async fn resolve(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ destination: &McpDestination,
+ ) -> Result<UpstreamCall, EgressError> {
+ // Macro's own server is the composition root's to layer on with
+ // [`crate::outbound::macro_mcp::WithMacroMcp`]; these rows can never
+ // answer for it.
+ let McpDestination::Connected(slug) = destination else {
+ return Err(EgressError::Internal(rootcause::report!(
+ "the Pipedream resolver was asked for Macro's own MCP server; \
+ the composition root did not layer WithMacroMcp"
+ )));
+ };
+ let record = self.connection(owner, slug).await?;
+
+ // A dead grant is Pipedream's to notice, not ours: we hold no
+ // refresh token to fail on. If the account behind this connection has
+ // gone unhealthy, Pipedream answers the forwarded call with its own
+ // error and the status passes through to the agent.
+ let call = self.upstream.upstream(&record).await.map_err(|error| {
+ EgressError::Upstream(rootcause::report!(
+ "could not address Pipedream for {slug}: {error:?}"
+ ))
+ })?;
+
+ // Typed at the source, but not yet vetted: `UpstreamCall`'s
+ // constructor is what refuses a non-https endpoint, and it is the
+ // only way to pair this URL with a credential.
+ Ok(
+ UpstreamCall::bearer(call.url, BearerToken::new(call.bearer_token))?
+ .scoped_by(call.headers),
+ )
+ }
+}
diff --git a/crates/agent_egress/src/outbound/mcp_credentials/test.rs b/crates/agent_egress/src/outbound/mcp_credentials/test.rs
new file mode 100644
index 0000000000..07bd96dbaa
--- /dev/null
+++ b/crates/agent_egress/src/outbound/mcp_credentials/test.rs
@@ -0,0 +1,205 @@
+use super::*;
+use crate::domain::model::McpDestination;
+use http::header::{HeaderMap, HeaderValue};
+use pipedream_mcp::outbound::api::McpUpstreamCall;
+use std::sync::Mutex;
+use url::Url;
+
+fn owner() -> MacroUserIdStr<'static> {
+ MacroUserIdStr::try_from_email("[email protected]").expect("a valid user id")
+}
+
+fn connection(app_slug: &str, enabled: bool) -> PipedreamConnection {
+ PipedreamConnection {
+ user_id: owner(),
+ app_slug: app_slug.to_owned(),
+ server_name: format!("{app_slug} display name"),
+ account_id: format!("apn_{app_slug}"),
+ enabled,
+ }
+}
+
+struct FixedConnections(Vec<PipedreamConnection>);
+
+impl ConnectionStore for FixedConnections {
+ type Err = std::convert::Infallible;
+
+ async fn save(&self, _record: &PipedreamConnection) -> Result<(), Self::Err> {
+ unreachable!("resolution never writes")
+ }
+
+ async fn load(
+ &self,
+ _user_id: &MacroUserIdStr<'static>,
+ _app_slug: &str,
+ ) -> Result<Option<PipedreamConnection>, Self::Err> {
+ unreachable!("resolution lists, never loads one")
+ }
+
+ async fn delete(
+ &self,
+ _user_id: &MacroUserIdStr<'static>,
+ _app_slug: &str,
+ ) -> Result<(), Self::Err> {
+ unreachable!("resolution never deletes")
+ }
+
+ async fn list(
+ &self,
+ _user_id: &MacroUserIdStr<'static>,
+ ) -> Result<Vec<PipedreamConnection>, Self::Err> {
+ Ok(self.0.clone())
+ }
+}
+
+/// Records which connection it was asked to address, and answers with a fixed
+/// upstream shaped like the real client's. Cloning shares one record.
+#[derive(Clone)]
+struct SpyUpstream {
+ url: &'static str,
+ asked_for: Arc<Mutex<Vec<PipedreamConnection>>>,
+}
+
+impl SpyUpstream {
+ fn at(url: &'static str) -> Self {
+ Self {
+ url,
+ asked_for: Arc::new(Mutex::new(Vec::new())),
+ }
+ }
+}
+
+impl McpUpstream for SpyUpstream {
+ async fn upstream(&self, record: &PipedreamConnection) -> anyhow::Result<McpUpstreamCall> {
+ self.asked_for
+ .lock()
+ .expect("spy lock should not be poisoned")
+ .push(record.clone());
+ let mut headers = HeaderMap::new();
+ headers.insert(
+ "x-pd-external-user-id",
+ HeaderValue::from_str(&record.user_id.to_string()).expect("a header value"),
+ );
+ headers.insert(
+ "x-pd-app-slug",
+ HeaderValue::from_str(&record.app_slug).expect("a header value"),
+ );
+ Ok(McpUpstreamCall {
+ url: Url::parse(self.url).expect("a url"),
+ bearer_token: "project-token".to_owned(),
+ headers,
+ })
+ }
+}
+
+fn connected(slug: &str) -> McpDestination {
+ McpDestination::Connected(McpServerSlug::parse(slug).expect("a valid slug"))
+}
+
+/// The slug a sandbox dials is Pipedream's `app_slug`, byte for byte -
+/// nothing is derived at either end, so the docs' spelling is the dialable
+/// spelling.
+#[tokio::test]
+async fn resolves_an_app_slug_verbatim() {
+ let upstream = SpyUpstream::at("https://remote.mcp.pipedream.net");
+ let credentials = PipedreamMcpCredentials::new(
+ Arc::new(FixedConnections(vec![connection("google_sheets", true)])),
+ upstream.clone(),
+ );
+
+ let call = credentials
+ .resolve(&owner(), &connected("google_sheets"))
+ .await
+ .expect("resolved");
+
+ assert_eq!(call.url().as_str(), "https://remote.mcp.pipedream.net/");
+ let asked = upstream.asked_for.lock().expect("spy lock");
+ assert_eq!(asked.len(), 1);
+ assert_eq!(asked[0].app_slug, "google_sheets");
+}
+
+#[tokio::test]
+async fn carries_the_scoping_headers_next_to_the_bearer() {
+ let upstream = SpyUpstream::at("https://remote.mcp.pipedream.net");
+ let credentials = PipedreamMcpCredentials::new(
+ Arc::new(FixedConnections(vec![connection("linear", true)])),
+ upstream.clone(),
+ );
+
+ let call = credentials
+ .resolve(&owner(), &connected("linear"))
+ .await
+ .expect("resolved");
+
+ let scope: Vec<(&str, &str)> = call
+ .scope_headers()
+ .iter()
+ .map(|(name, value)| (name.as_str(), value.to_str().expect("ascii")))
+ .collect();
+ assert!(scope.contains(&("x-pd-app-slug", "linear")), "{scope:?}");
+ assert!(
+ scope
+ .iter()
+ .any(|(name, _)| *name == "x-pd-external-user-id"),
+ "{scope:?}"
+ );
+}
+
+#[tokio::test]
+async fn a_disabled_connection_is_an_unknown_server() {
+ let upstream = SpyUpstream::at("https://remote.mcp.pipedream.net");
+ let credentials = PipedreamMcpCredentials::new(
+ Arc::new(FixedConnections(vec![connection("linear", false)])),
+ upstream.clone(),
+ );
+
+ let refusal = credentials
+ .resolve(&owner(), &connected("linear"))
+ .await
+ .expect_err("refused");
+
+ assert!(
+ matches!(refusal, EgressError::UnknownServer(_)),
+ "{refusal}"
+ );
+ assert!(
+ upstream.asked_for.lock().expect("spy lock").is_empty(),
+ "a disabled connection must never reach Pipedream"
+ );
+}
+
+#[tokio::test]
+async fn a_slug_nobody_connected_is_an_unknown_server() {
+ let upstream = SpyUpstream::at("https://remote.mcp.pipedream.net");
+ let credentials =
+ PipedreamMcpCredentials::new(Arc::new(FixedConnections(Vec::new())), upstream.clone());
+
+ let refusal = credentials
+ .resolve(&owner(), &connected("linear"))
+ .await
+ .expect_err("refused");
+
+ assert!(
+ matches!(refusal, EgressError::UnknownServer(_)),
+ "{refusal}"
+ );
+}
+
+#[tokio::test]
+async fn refuses_a_cleartext_upstream() {
+ let upstream = SpyUpstream::at("http://remote.mcp.pipedream.net");
+ let credentials = PipedreamMcpCredentials::new(
+ Arc::new(FixedConnections(vec![connection("linear", true)])),
+ upstream.clone(),
+ );
+
+ let refusal = credentials
+ .resolve(&owner(), &connected("linear"))
+ .await
+ .expect_err("refused");
+
+ assert!(
+ matches!(refusal, EgressError::InsecureUpstream(_)),
+ "{refusal}"
+ );
+}
diff --git a/crates/agent_egress/src/outbound/mod.rs b/crates/agent_egress/src/outbound/mod.rs
new file mode 100644
index 0000000000..e4491a4ef9
--- /dev/null
+++ b/crates/agent_egress/src/outbound/mod.rs
@@ -0,0 +1,16 @@
+//! Adapters this crate reaches the rest of the world through.
+
+/// Minting a scoped GitHub App installation credential.
+pub mod github_tokens;
+
+/// Answering the reserved `macro` slug with Macro's own MCP server.
+pub mod macro_mcp;
+
+/// Resolving an owner's Pipedream-connected apps to scoped upstream calls.
+pub mod mcp_credentials;
+
+/// Resolving a sandbox's session token to the session it stands for.
+pub mod session_authority;
+
+/// Executing an already-addressed, already-stamped request.
+pub mod forwarder;
diff --git a/crates/agent_egress/src/outbound/session_authority.rs b/crates/agent_egress/src/outbound/session_authority.rs
new file mode 100644
index 0000000000..a754d6af5d
--- /dev/null
+++ b/crates/agent_egress/src/outbound/session_authority.rs
@@ -0,0 +1,108 @@
+//! Turning the token a sandbox presents into the session row it stands for.
+//!
+//! One lookup, and it is the whole check. The token asserts nothing on its own
+//! - it is 256 bits of randomness - so what a request may do is read off the
+//! row it is stored against rather than out of the token: the owner whose
+//! credentials it spends, the repository its git traffic is pinned to, and
+//! whether the session is still open.
+//!
+//! That is what makes revocation real. A signed token has to be outlived or
+//! denied by a second check; a token that is only a key into a table stops
+//! working the moment the row does.
+//!
+//! What is stored is the token's SHA-256 digest, never the token, so a database
+//! dump yields nothing that can be presented. Looking the row up *by* that
+//! digest also keeps the comparison in the index rather than in a Rust `==`
+//! over secret-derived bytes.
+
+use agent_runtime_protocol::domain::schema::v0::SystemEvent;
+use agent_session::domain::model::SessionStatus;
+use agent_session::domain::ports::AgentSessionRepo;
+
+use crate::domain::error::EgressError;
+use crate::domain::model::{RepoSlug, SessionGrant, SessionToken};
+use crate::domain::ports::SessionAuthority;
+
+/// Resolves a presented session token to its session by the digest stored
+/// against that session, then checks the session is still open.
+pub struct StoredTokenSessionAuthority<Sessions> {
+ sessions: Sessions,
+}
+
+impl<Sessions> StoredTokenSessionAuthority<Sessions>
+where
+ Sessions: AgentSessionRepo,
+{
+ /// Build the authority over the session repository.
+ pub fn new(sessions: Sessions) -> Self {
+ Self { sessions }
+ }
+}
+
+impl<Sessions> SessionAuthority for StoredTokenSessionAuthority<Sessions>
+where
+ Sessions: AgentSessionRepo,
+{
+ #[tracing::instrument(skip_all, err)]
+ async fn authorize(&self, token: &SessionToken) -> Result<SessionGrant, EgressError> {
+ // A lookup that failed is a refusal too - this decides whether a
+ // credential gets spent, and the safe answer when we cannot tell is no
+ // - but a refusal of a different kind from a token we do not know, and
+ // the sandbox should retry one and not the other.
+ let session = self
+ .sessions
+ .find_by_egress_token_hash(&token.hash())
+ .await
+ .inspect_err(|error| {
+ tracing::error!(error = ?error, "could not look up a session by its token");
+ })
+ .map_err(|error| {
+ EgressError::Internal(rootcause::report!(
+ "could not look up a session by its token: {error}"
+ ))
+ })?
+ // No row is the ordinary refusal: a token we never minted, or one
+ // whose session has since been deleted. Both are the same fact
+ // from here, and neither is worth telling the sandbox apart.
+ .ok_or(EgressError::Unauthenticated("unknown session token"))?;
+
+ // `SessionStatus` has no "closed" of its own; a disconnected transport
+ // is what a closed session looks like from the row. Anything else -
+ // including an event name this build does not know - is a running
+ // session, because a session that has not been told to stop is one
+ // whose sandbox may still be mid-tool-call.
+ if matches!(
+ session.status,
+ SessionStatus::Disconnected | SessionStatus::Event(SystemEvent::Disconnected)
+ ) {
+ return Err(EgressError::SessionClosed);
+ }
+
+ // Our own configuration, not sandbox input - but it is interpolated
+ // into a GitHub URL downstream, so it is parsed rather than trusted. A
+ // row that does not name a repository is a session that was created
+ // wrong, which is ours to fix and not something the sandbox can retry
+ // its way out of.
+ //
+ // `repo_url` is nullable because an external session names no
+ // repository, but such a session is never issued an egress token, so
+ // reaching here without one is that same "created wrong" - not a
+ // refusal the sandbox could act on.
+ let repo = session
+ .repo_url
+ .as_deref()
+ .and_then(RepoSlug::parse_github_url)
+ .ok_or_else(|| {
+ EgressError::Internal(rootcause::report!(
+ "session {} has no repo_url naming a github repository",
+ session.id
+ ))
+ })?;
+
+ Ok(SessionGrant {
+ session: session.id,
+ owner: session.owner_id,
+ repo,
+ })
+ }
+}
diff --git a/crates/agent_harness/Cargo.toml b/crates/agent_harness/Cargo.toml
index 393fbd312b..a0aae9de6a 100644
--- a/crates/agent_harness/Cargo.toml
+++ b/crates/agent_harness/Cargo.toml
@@ -6,6 +6,9 @@ version = "0.1.0"
[dependencies]
agent-client-protocol = { workspace = true }
+# The session-token claim shape and its signing, so the harness and the proxy
+# cannot disagree about what a token says.
+agent_egress = { path = "../agent_egress" }
agent_runtime_protocol = { path = "../agent_runtime_protocol" }
agent_session = { path = "../agent_session" }
agent_trigger = { path = "../agent_trigger" }
@@ -24,6 +27,7 @@ dashmap = { workspace = true }
futures = { workspace = true }
kafka_util = { path = "../kafka_util" }
macro_env_var = { path = "../macro_env_var" }
+pipedream_mcp = { path = "../pipedream_mcp" }
macro_event_broker = { path = "../macro_event_broker", features = ["outbound"] }
macro_authorization = { path = "../macro_authorization", features = ["axum"] }
macro_tower_layers = { path = "../macro_tower_layers" }
diff --git a/crates/agent_harness/container/ensure_ready.sh b/crates/agent_harness/container/ensure_ready.sh
index 0f8b14ff78..87cea8d68d 100644
--- a/crates/agent_harness/container/ensure_ready.sh
+++ b/crates/agent_harness/container/ensure_ready.sh
@@ -11,28 +11,30 @@
# has to dial the sidecar afterwards - `provision::SIDECAR_PORT` mirrors it and
# a test asserts the two agree.
#
-# REPO_URL and GITHUB_TOKEN come from the sandbox environment, set at creation.
-# They are never interpolated into this script.
+# MACRO_EGRESS_URL and MACRO_SESSION_TOKEN come from the sandbox environment.
+# Git presents the latter only to the Macro egress origin; the proxy selects the
+# repository from the session and exchanges it for a scoped GitHub App token.
set -e
workspace_dir=/workspace
sidecar_port=8700
-# Macro dev shell baked into the image at build time; absent on images built
-# without the github_token secret.
+# Macro dev shell baked into the image at build time, so a sandbox skips
+# realizing it. Sourced only if present, so an image built without that layer
+# still starts.
repo_env_file=/env/repo-dev-env.sh
sidecar_log=/tmp/acp-sidecar.log
-# 1. Credentials, so the clone below can read a private repo.
-gh auth setup-git --hostname github.com --force
-
-# 2. The repo, unless it is already cloned.
+# 1. The repo, unless it is already cloned. Scope the helper to Macro egress so
+# an agent cannot redirect the session token to another host.
if [ ! -d "$workspace_dir/.git" ]; then
- git clone --depth 1 "$REPO_URL" "$workspace_dir"
+ egress_git_url="${MACRO_EGRESS_URL%/}/git"
+ git config --global "credential.${MACRO_EGRESS_URL}.helper" \
+ '!f() { echo username=x-access-token; echo "password=$MACRO_SESSION_TOKEN"; }; f'
+ git clone --depth 1 "$egress_git_url" "$workspace_dir"
fi
-# 3. The sidecar, unless it is already answering. The baked dev shell goes
-# first on PATH, with the image's own tools (opencode, gh) still reachable
-# behind it.
+# 2. The sidecar, unless it is already answering. The baked dev shell goes
+# first on PATH, with the image's own tools still reachable behind it.
#
# Checked explicitly because `nohup ... &` backgrounds the process, so its
# failure is invisible to `set -e` - a missing binary would otherwise show up
diff --git a/crates/agent_harness/container/flake.nix b/crates/agent_harness/container/flake.nix
index d89ced7d83..08a28ce3cf 100644
--- a/crates/agent_harness/container/flake.nix
+++ b/crates/agent_harness/container/flake.nix
@@ -15,7 +15,7 @@
let pkgs = nixpkgs.legacyPackages.${system};
in {
default = pkgs.mkShell {
- packages = [ pkgs.nodejs pkgs.git pkgs.gh pkgs.opencode pkgs.github-mcp-server ];
+ packages = [ pkgs.nodejs pkgs.git pkgs.opencode ];
};
});
};
diff --git a/crates/agent_harness/container/opencode.json b/crates/agent_harness/container/opencode.json
index 20f7216465..a4aa6e582c 100644
--- a/crates/agent_harness/container/opencode.json
+++ b/crates/agent_harness/container/opencode.json
@@ -10,20 +10,5 @@
"permission": {
"*": "allow",
"external_directory": "deny"
- },
- "mcp": {
- "github": {
- "type": "local",
- "command": [
- "github-mcp-server",
- "stdio",
- "--toolsets",
- "issues,pull_requests"
- ],
- "environment": {
- "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
- },
- "enabled": true
- }
}
}
diff --git a/crates/agent_harness/justfile b/crates/agent_harness/justfile
index 68489b2ec4..1fde25a6fb 100644
--- a/crates/agent_harness/justfile
+++ b/crates/agent_harness/justfile
@@ -1,7 +1,7 @@
-# Two recipes, one per sandbox provider. Each publishes `container/` in
-# whatever form its provider wants, then boots an agent in it with a prompt -
-# so both exercise our image, not a stock one. `.env` next to this justfile (or
-# any parent) can supply DAYTONA_API_KEY / NSC_TOKEN / GITHUB_TOKEN.
+# Publishing `container/` in whatever form a sandbox provider wants, then
+# booting an agent in it with a prompt - so what runs is our image, not a stock
+# one. `.env` next to this justfile (or any parent) can supply
+# DAYTONA_API_KEY.
#
# Override the prompt with `just boot-daytona "your prompt"`.
#
@@ -15,12 +15,10 @@
# All recipes skip the image build when the image already exists, which is
# wrong whenever `container/` has changed - a stale image is reused silently and
# the failure shows up much later, inside the sandbox. Use `just rebuild-daytona`
-# / `rebuild-namespace` / `build-local --force` after touching the Dockerfile
-# or the sidecar.
+# / `build-local --force` after touching the Dockerfile or the sidecar.
set dotenv-load := true
-# What the image is called on both providers: a Daytona snapshot, and a
-# repository in Namespace's nscr.io workspace registry.
+# What the image is called: a Daytona snapshot, and a local Docker tag.
image_name := env_var_or_default("AGENT_HARNESS_IMAGE", "macro-agent-harness")
# Snapshot bake size from sandbox_sizes.json. Override with DAYTONA_SNAPSHOT_*.
@@ -102,40 +100,6 @@ rebuild-daytona prompt=default_prompt:
fi
just boot-daytona {{ quote(prompt) }}
-# Push the image to nscr.io if needed, then boot an agent in an instance
-boot-namespace prompt=default_prompt:
- #!/usr/bin/env bash
- set -euo pipefail
- # Namespace bearer tokens expire, so unlike the Daytona key this is minted
- # per run unless the environment already carries one.
- if [ -n "${NSC_TOKEN:-}" ]; then
- echo "using NSC_TOKEN from the environment"
- else
- echo "minting a dev token (run 'nsc login' first if this fails)"
- NSC_TOKEN="$(nsc auth generate-dev-token)"
- export NSC_TOKEN
- fi
- # Namespace pulls an ordinary OCI reference, so container/ is built by a
- # Namespace remote builder and pushed to the workspace registry. Set
- # NAMESPACE_IMAGE_REF to skip the build and boot an already-pushed image.
- if [ -z "${NAMESPACE_IMAGE_REF:-}" ]; then
- echo "building container/ in a Namespace remote builder and pushing to nscr.io"
- build_log="$(mktemp)"
- trap 'rm -f "$build_log"' EXIT
- nsc build container --name {{image_name}} --push 2>&1 | tee "$build_log"
- # nsc reports the pushed reference in its output; scraping it beats
- # reassembling nscr.io/<workspace>/<name>:<tag> by hand.
- NAMESPACE_IMAGE_REF="$(grep -oE 'nscr\.io/[^[:space:]]+' "$build_log" | tail -1)"
- if [ -z "$NAMESPACE_IMAGE_REF" ]; then
- echo "could not find the pushed nscr.io reference in the build output;" >&2
- echo "set NAMESPACE_IMAGE_REF to it and re-run" >&2
- exit 1
- fi
- export NAMESPACE_IMAGE_REF
- fi
- echo "booting $NAMESPACE_IMAGE_REF"
- cargo run -p agent_harness --bin boot_agent -- namespace {{ quote(prompt) }}
-
# Build the image for the local Docker provider if missing
build-local force="":
#!/usr/bin/env bash
diff --git a/crates/agent_harness/src/domain/error.rs b/crates/agent_harness/src/domain/error.rs
index 5a893f3504..7cc90717a3 100644
--- a/crates/agent_harness/src/domain/error.rs
+++ b/crates/agent_harness/src/domain/error.rs
@@ -50,6 +50,10 @@ pub enum HarnessError {
/// A session command worker stopped before reporting its result.
#[error("agent session {0} command worker stopped")]
CommandWorkerStopped(AgentSessionId),
+ /// The sandbox's egress environment could not be prepared: no signing
+ /// key, no repository, or the owner's connected servers could not be read.
+ #[error("failed to provision sandbox egress: {0}")]
+ Egress(rootcause::Report),
/// The session link could not be posted back to the mention's thread.
#[error("failed to announce the agent session: {0}")]
Announce(rootcause::Report),
diff --git a/crates/agent_harness/src/domain/model.rs b/crates/agent_harness/src/domain/model.rs
index 11c74bfdf7..de909e948b 100644
--- a/crates/agent_harness/src/domain/model.rs
+++ b/crates/agent_harness/src/domain/model.rs
@@ -1,10 +1,11 @@
//! Commands and values used by the harness domain.
+use agent_client_protocol::schema::v1::{HttpHeader, McpServer as AcpMcpServer, McpServerHttp};
+use agent_egress::domain::model::McpServerSlug;
use agent_runtime_protocol::domain::action::{AgentAction, AgentActionId};
use agent_session::domain::model::{AgentSessionId, MessageId, SandboxSize};
use agent_session::domain::ports::ControlEvent;
use bot_id::BotId;
-use macro_user_id::email::ReadEmailParts;
use macro_user_id::user_id::MacroUserIdStr;
use macro_uuid::Uuid;
/// Where a mention happened.
@@ -87,10 +88,10 @@ impl AgentKind {
}
}
-/// Whether a user belongs to the Macro staff domain.
-pub(crate) fn is_macro_staff(user: &MacroUserIdStr<'_>) -> bool {
- user.email_part().domain_part() == "macro.com"
-}
+/// Whether a user belongs to the Macro staff domain - the egress crate's
+/// predicate, reused so the harness's staff gates and the proxy's can never
+/// disagree about who staff is.
+pub(crate) use agent_egress::domain::model::is_macro_staff;
/// Where a prompt came from, when it came from somewhere the session should
/// answer back into.
@@ -230,10 +231,149 @@ pub struct SpawnContainer {
/// thing spawn ever consumed the bot for; resume and teardown re-derive
/// the same kind from the session row's bot.
pub kind: AgentKind,
- /// Repository cloned into the container workspace.
- pub repo_url: String,
/// Compute tier to request from the provider.
pub size: SandboxSize,
+ /// How the sandbox reaches anything outside itself.
+ ///
+ /// Carries the repository implicitly: the sandbox clones from the proxy,
+ /// which reads the repository off the session's own grant, so no provider
+ /// needs to be told what it is.
+ pub egress: SandboxEgress,
+}
+
+/// Everything a sandbox needs to make an authenticated outbound call, and
+/// nothing more.
+///
+/// The sandbox runs model-authored code with every permission allowed, so
+/// whatever is in here has been handed to the model. That is why it is one
+/// short-lived session token and a URL rather than any upstream credential:
+/// the credentials stay in the egress proxy, which stamps them on as requests
+/// pass through.
+///
+/// The MCP servers are carried as data rather than any provider's rendered
+/// config, because two consumers speak two dialects of it: an ACP agent gets
+/// them in `session/new` through [`SandboxEgress::acp_servers`], and a Cursor
+/// cloud agent gets the same servers through Cursor's own API. One source,
+/// two renderings, nothing to drift.
+#[derive(Clone)]
+pub struct SandboxEgress {
+ /// Base URL of the egress proxy, as the sandbox should dial it.
+ pub base_url: String,
+ /// The session token, presented on every proxied call.
+ pub session_token: String,
+ /// The owner's connected MCP servers, by the slug the proxy resolves.
+ /// Macro's own server is not listed: every session has it, on its own
+ /// route.
+ pub mcp_servers: Vec<McpServerSlug>,
+}
+
+/// Where the sandbox finds the egress proxy.
+///
+/// Named here rather than written inline because the name is shared knowledge
+/// with the container: `container/ensure_ready.sh` reads it to build the git
+/// remote it clones from. Like `provision::SIDECAR_PORT`, the agreement between
+/// the two is held by a test rather than by comment.
+pub const EGRESS_URL_VARIABLE: &str = "MACRO_EGRESS_URL";
+
+/// The session token the sandbox presents on every proxied call. Shared with
+/// `container/ensure_ready.sh` on the same terms as [`EGRESS_URL_VARIABLE`].
+pub const SESSION_TOKEN_VARIABLE: &str = "MACRO_SESSION_TOKEN";
+
+/// The name every session's server list gives Macro's own MCP server.
+///
+/// Purely a display name now - resolution happens by route, not by name - but
+/// kept short and stable because agents namespace tool names under it.
+pub const MACRO_MCP_NAME: &str = "macro";
+
+impl SandboxEgress {
+ /// Where the proxy serves `slug` - the URL a client dials to reach that
+ /// server, whichever client it is.
+ pub fn mcp_url(&self, slug: &McpServerSlug) -> String {
+ format!("{}/mcp/{slug}", self.base_url)
+ }
+
+ /// Where the proxy serves Macro's own MCP server: its own route, so no
+ /// connected app's slug can ever name it.
+ pub fn macro_mcp_url(&self) -> String {
+ format!("{}/mcp-macro", self.base_url)
+ }
+
+ /// The `Authorization` value presented on every proxied call.
+ pub fn authorization_header(&self) -> String {
+ format!("Bearer {}", self.session_token)
+ }
+
+ /// The sandbox environment this becomes.
+ ///
+ /// Unsized on purpose: a third variable should be one more line here and
+ /// nothing at any call site.
+ pub fn environment(&self) -> impl IntoIterator<Item = (String, String)> {
+ [
+ (EGRESS_URL_VARIABLE.to_owned(), self.base_url.clone()),
+ (
+ SESSION_TOKEN_VARIABLE.to_owned(),
+ self.session_token.clone(),
+ ),
+ ]
+ }
+
+ /// Every server the session may dial, as `(name, url)` pairs: Macro's own
+ /// server first, then the owner's connected apps under their Pipedream
+ /// slugs.
+ ///
+ /// The one enumeration behind both renderings - [`Self::acp_servers`] and
+ /// the Cursor API's - so the two can never advertise different sets.
+ pub fn server_entries(&self) -> impl Iterator<Item = (String, String)> + '_ {
+ std::iter::once((MACRO_MCP_NAME.to_owned(), self.macro_mcp_url())).chain(
+ self.mcp_servers
+ .iter()
+ .map(|slug| (slug.as_str().to_owned(), self.mcp_url(slug))),
+ )
+ }
+
+ /// The MCP servers an ACP agent is handed in `session/new`, `session/load`
+ /// and `session/resume`.
+ ///
+ /// Every server is HTTP transport pointed at the egress proxy, never at
+ /// the server itself, and carries the session token - the sandbox holds
+ /// no upstream credential to point anywhere with.
+ pub fn acp_servers(&self) -> Vec<AcpMcpServer> {
+ self.server_entries()
+ .map(|(name, url)| {
+ AcpMcpServer::Http(McpServerHttp::new(name, url).headers(vec![HttpHeader::new(
+ "Authorization",
+ self.authorization_header(),
+ )]))
+ })
+ .collect()
+ }
+}
+
+/// A minted egress environment and the hash that has to be stored for it to
+/// work.
+///
+/// The two halves go to different places and must not be confused: the raw
+/// token in [`ProvisionedEgress::sandbox`] is handed to the container, and
+/// [`ProvisionedEgress::session_token_hash`] is what the session row keeps so
+/// the proxy can recognize it. Returned together because the row has to be
+/// written before the container that holds the token exists.
+#[derive(Debug, Clone)]
+pub struct ProvisionedEgress {
+ /// SHA-256 hex of the session token, for the session row.
+ pub session_token_hash: String,
+ /// The environment the sandbox is spawned with, carrying the raw token.
+ pub sandbox: SandboxEgress,
+}
+
+impl std::fmt::Debug for SandboxEgress {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ formatter
+ .debug_struct("SandboxEgress")
+ .field("base_url", &self.base_url)
+ .field("session_token", &"[REDACTED]")
+ .field("mcp_servers", &self.mcp_servers)
+ .finish()
+ }
}
/// Session-row values that remain deployment configuration for now.
diff --git a/crates/agent_harness/src/domain/ports.rs b/crates/agent_harness/src/domain/ports.rs
index eab8bae7fa..864f299fda 100644
--- a/crates/agent_harness/src/domain/ports.rs
+++ b/crates/agent_harness/src/domain/ports.rs
@@ -5,8 +5,12 @@ use agent_session::domain::model::{AgentSessionId, SandboxSize};
use agent_session::domain::ports::AgentConnector;
use bot_id::BotId;
+use macro_user_id::user_id::MacroUserIdStr;
+
use super::error::Result;
-use super::model::{PriorChannelMessage, SessionAnnouncement, SpawnContainer};
+use super::model::{
+ PriorChannelMessage, ProvisionedEgress, SandboxEgress, SessionAnnouncement, SpawnContainer,
+};
use super::sandbox::SandboxResizeEffect;
#[cfg(test)]
@@ -75,6 +79,36 @@ pub trait RuntimeConnections: Send + Sync + 'static {
) -> impl Future<Output = Option<RuntimeAttachment<Self::Connector>>> + Send;
}
+/// Mints the one secret a sandbox is given, and the config that points it at
+/// the egress proxy.
+///
+/// A port rather than domain code because both halves are adapter work the
+/// domain has no business knowing: signing a JWT needs a key, and enumerating
+/// the owner's MCP servers needs their rows. What the domain keeps is *when* -
+/// once, at spawn, for the session's own owner.
+pub trait SandboxEgressProvisioner: Send + Sync + 'static {
+ /// The egress environment for one session, on behalf of `owner`, and the
+ /// hash its session row must carry for that environment to mean anything.
+ fn provision(
+ &self,
+ session: AgentSessionId,
+ owner: &MacroUserIdStr<'static>,
+ repo_url: &str,
+ ) -> impl Future<Output = Result<ProvisionedEgress>> + Send;
+
+ /// The egress environment rebuilt around a token that already exists.
+ ///
+ /// For reattaching to a sandbox that was spawned earlier: the sandbox
+ /// still holds its raw token (the row holds only the hash), so nothing is
+ /// minted - but the owner's connected servers are listed fresh, so an app
+ /// connected since the spawn is advertised on the next attach.
+ fn restore(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ session_token: String,
+ ) -> impl Future<Output = Result<SandboxEgress>> + Send;
+}
+
/// Provisions the container transports agent sessions run through.
pub trait ContainerManager: Send + Sync + 'static {
/// Transport returned by this provider.
@@ -111,6 +145,21 @@ pub trait ContainerManager: Send + Sync + 'static {
session: AgentSessionId,
) -> impl Future<Output = Result<Self::Transport>> + Send;
+ /// The raw egress session token the session's container holds, if this
+ /// provider's containers hold one.
+ ///
+ /// The harness keeps only the token's hash, so on a reattach the running
+ /// container is the one place the raw token still exists - it was handed
+ /// exactly one, at spawn, in its environment. Providers whose sessions
+ /// carry no egress environment (the in-process agent, Cursor's cloud)
+ /// answer `None`.
+ ///
+ /// Only meaningful for a running container; call it after [`Self::resume`].
+ fn session_token(
+ &self,
+ session: AgentSessionId,
+ ) -> impl Future<Output = Result<Option<String>>> + Send;
+
/// Destroy a session's container for good.
///
/// Unlike the idle reaper, which stops a sandbox so it can be resumed,
diff --git a/crates/agent_harness/src/domain/ports/test.rs b/crates/agent_harness/src/domain/ports/test.rs
index 79e9458d77..64ed30c510 100644
--- a/crates/agent_harness/src/domain/ports/test.rs
+++ b/crates/agent_harness/src/domain/ports/test.rs
@@ -18,6 +18,7 @@ use macro_user_id::user_id::MacroUserIdStr;
use super::ContainerManager;
use crate::domain::model::{AgentKind, SpawnContainer};
use crate::testing::helpers::containers::{ContainerMock, MockContainerManager};
+use crate::testing::helpers::egress::test_egress;
fn owner() -> MacroUserIdStr<'static> {
MacroUserIdStr::try_from_email("[email protected]").unwrap()
@@ -35,6 +36,7 @@ fn params(id: AgentSessionId) -> CreateAgentSessionParams {
repo_url: Some("https://github.com/macro/macro".to_owned()),
workspace: "/workspace".to_owned(),
sandbox_size: agent_session::domain::model::SandboxSize::Default,
+ egress_token_hash: None,
}
}
@@ -64,8 +66,8 @@ async fn container_session_runs_and_logs_end_to_end() {
.spawn(SpawnContainer {
session_id: id,
kind: AgentKind::SandboxedCoder,
- repo_url: "https://github.com/macro/macro".to_owned(),
size: agent_session::domain::model::SandboxSize::Default,
+ egress: test_egress(),
})
.await
.unwrap();
diff --git a/crates/agent_harness/src/domain/service.rs b/crates/agent_harness/src/domain/service.rs
index 8ae92e5177..9478d23df3 100644
--- a/crates/agent_harness/src/domain/service.rs
+++ b/crates/agent_harness/src/domain/service.rs
@@ -26,7 +26,7 @@ use crate::domain::model::{
};
use crate::domain::ports::{
AgentPromptComposer, ChannelPromptContext, ContainerManager, RuntimeConnections,
- SessionAnnouncer,
+ SandboxEgressProvisioner, SessionAnnouncer,
};
use crate::domain::sandbox::SandboxResizeEffect;
@@ -40,13 +40,22 @@ struct QueuedCommand {
span: tracing::Span,
}
-struct AgentHarnessInner<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer> {
+struct AgentHarnessInner<
+ Sessions,
+ Containers,
+ Announcer,
+ Runtimes,
+ PromptContext,
+ PromptComposer,
+ Egress,
+> {
sessions: Sessions,
containers: Containers,
announcer: Announcer,
runtimes: Runtimes,
prompt_context: PromptContext,
prompt_composer: PromptComposer,
+ egress: Egress,
defaults: HarnessDefaults,
}
@@ -58,15 +67,32 @@ pub struct AgentHarnessService<
Runtimes,
PromptContext,
PromptComposer,
+ Egress,
> {
inner: Arc<
- AgentHarnessInner<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>,
+ AgentHarnessInner<
+ Sessions,
+ Containers,
+ Announcer,
+ Runtimes,
+ PromptContext,
+ PromptComposer,
+ Egress,
+ >,
>,
workers: Arc<SessionWorkers>,
}
-impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>
- AgentHarnessService<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>
+impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer, Egress>
+ AgentHarnessService<
+ Sessions,
+ Containers,
+ Announcer,
+ Runtimes,
+ PromptContext,
+ PromptComposer,
+ Egress,
+ >
where
Sessions: AgentSessionService,
Containers: ContainerManager,
@@ -74,8 +100,13 @@ where
Runtimes: RuntimeConnections,
PromptContext: ChannelPromptContext,
PromptComposer: AgentPromptComposer,
+ Egress: SandboxEgressProvisioner,
{
/// Build the orchestrator from its ports.
+ ///
+ /// One argument per port, however many ports there are: bundling some of
+ /// them into a struct would only move the same list one level down.
+ #[allow(clippy::too_many_arguments)]
pub fn new(
sessions: Sessions,
containers: Containers,
@@ -83,6 +114,7 @@ where
runtimes: Runtimes,
prompt_context: PromptContext,
prompt_composer: PromptComposer,
+ egress: Egress,
defaults: impl Into<HarnessDefaults>,
) -> Self {
Self {
@@ -93,6 +125,7 @@ where
runtimes,
prompt_context,
prompt_composer,
+ egress,
defaults: defaults.into(),
}),
workers: Arc::new(DashMap::new()),
@@ -209,7 +242,7 @@ where
/// control routes notify. Both operations go through the per-session queue, so
/// a teardown cannot land in the middle of an open and a model change cannot
/// overtake the prompt it was meant to follow.
-impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>
+impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer, Egress>
AgentSessionNotificationRecipient
for AgentHarnessService<
Sessions,
@@ -218,6 +251,7 @@ impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>
Runtimes,
PromptContext,
PromptComposer,
+ Egress,
>
where
Sessions: AgentSessionService,
@@ -226,6 +260,7 @@ where
Runtimes: RuntimeConnections,
PromptContext: ChannelPromptContext,
PromptComposer: AgentPromptComposer,
+ Egress: SandboxEgressProvisioner,
{
async fn session_deleted(
&self,
@@ -269,7 +304,7 @@ where
/// The announcement is best-effort: a session a runtime is about to serve
/// must not die because the courtesy post failed, most plainly when the bot
/// cannot post in the claimed channel.
-impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>
+impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer, Egress>
agent_session::domain::ports::SessionOpener
for AgentHarnessService<
Sessions,
@@ -278,6 +313,7 @@ impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>
Runtimes,
PromptContext,
PromptComposer,
+ Egress,
>
where
Sessions: AgentSessionService,
@@ -286,6 +322,7 @@ where
Runtimes: RuntimeConnections,
PromptContext: ChannelPromptContext,
PromptComposer: AgentPromptComposer,
+ Egress: SandboxEgressProvisioner,
{
async fn open_external_session(
&self,
@@ -306,6 +343,9 @@ where
repo_url: request.repo_url,
workspace: request.workspace,
sandbox_size: SandboxSize::Default,
+ // No sandbox: the runtime dials in and reaches the network on
+ // its operator's own terms, so there is no egress token.
+ egress_token_hash: None,
// The thread linkage is the caller's claim, not an observed
// mention; it must not grant the channel anything.
})
@@ -366,11 +406,21 @@ where
.sessions
.user_sandbox_size(&request.owner)
.await?;
+ let session_id = AgentSessionId::new();
+ // Same ordering as the trigger path's open: the token has to be minted
+ // before the row, because the row is what carries the hash that makes
+ // it mean anything.
+ let egress = self
+ .inner
+ .egress
+ .provision(session_id, &request.owner, &defaults.repo_url)
+ .await
+ .map_err(into_session_error)?;
let session = self
.inner
.sessions
.create_session(CreateAgentSessionParams {
- id: AgentSessionId::new(),
+ id: session_id,
owner_id: request.owner.clone(),
bot_id: defaults.bot_id,
thread_id: None,
@@ -381,17 +431,19 @@ where
// Managed sandboxes run in the path baked into their image.
workspace: agent_session::MANAGED_CONTAINER_WORKSPACE.to_owned(),
sandbox_size,
+ egress_token_hash: Some(egress.session_token_hash),
})
.await?;
+ let mcp_servers = egress.sandbox.acp_servers();
let container = match self
.inner
.containers
.spawn(SpawnContainer {
session_id: session.id,
kind: AgentKind::of(session.bot_id),
- repo_url: defaults.repo_url.clone(),
size: sandbox_size,
+ egress: egress.sandbox,
})
.await
{
@@ -417,7 +469,10 @@ where
};
self.inner
.sessions
- .attach_session(session.id, RuntimeAttachment::solo(container))
+ .attach_session(
+ session.id,
+ RuntimeAttachment::solo(container).mcp_servers(mcp_servers),
+ )
.await?;
if let Some(prompt) = initial_prompt {
@@ -465,8 +520,16 @@ fn into_session_error(error: HarnessError) -> AgentSessionError {
}
}
-impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>
- AgentHarnessInner<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>
+impl<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer, Egress>
+ AgentHarnessInner<
+ Sessions,
+ Containers,
+ Announcer,
+ Runtimes,
+ PromptContext,
+ PromptComposer,
+ Egress,
+ >
where
Sessions: AgentSessionService,
Containers: ContainerManager,
@@ -474,6 +537,7 @@ where
Runtimes: RuntimeConnections,
PromptContext: ChannelPromptContext,
PromptComposer: AgentPromptComposer,
+ Egress: SandboxEgressProvisioner,
{
async fn execute(&self, session_id: AgentSessionId, command: HarnessCommand) -> Result<()> {
match &command {
@@ -504,6 +568,31 @@ where
}
}
+ /// The MCP servers to advertise when reattaching to an existing container.
+ ///
+ /// The raw session token exists in exactly one place after spawn - the
+ /// container's own environment - so it is read back from there and wrapped
+ /// in a fresh listing of the owner's connected servers. A container that
+ /// holds no token (a provider whose sessions carry no egress environment,
+ /// or a sandbox from before tokens existed) gets no servers, which is
+ /// also everything it could do with them.
+ #[tracing::instrument(err, skip(self, owner), fields(%session_id, %owner))]
+ async fn resumed_mcp_servers(
+ &self,
+ session_id: AgentSessionId,
+ owner: &MacroUserIdStr<'static>,
+ ) -> Result<Vec<agent_client_protocol::schema::v1::McpServer>> {
+ let Some(session_token) = self.containers.session_token(session_id).await? else {
+ tracing::debug!("container holds no egress token; restoring no MCP servers");
+ return Ok(Vec::new());
+ };
+ Ok(self
+ .egress
+ .restore(owner, session_token)
+ .await?
+ .acp_servers())
+ }
+
/// Release everything the session holds, then delete it.
///
/// The durable delete goes last on purpose. Crashing between the two
@@ -543,8 +632,14 @@ where
self.containers.resize(session_id, size).await?;
if effect == SandboxResizeEffect::Restart {
let container = self.containers.resume(session_id).await?;
+ let mcp_servers = self
+ .resumed_mcp_servers(session_id, &session.owner_id)
+ .await?;
self.sessions
- .attach_session(session_id, RuntimeAttachment::solo(container))
+ .attach_session(
+ session_id,
+ RuntimeAttachment::solo(container).mcp_servers(mcp_servers),
+ )
.await?;
}
}
@@ -578,6 +673,16 @@ where
.compose(&origin.content, Some(&prior_messages))
.await?;
+ // Provisioned before the session exists, because the row is what makes
+ // the token mean anything: it carries the hash the proxy recognises.
+ // Minted here, where the session's owner is in hand, and only here -
+ // the token is scoped to this session and spends this person's
+ // credentials, so there is nowhere else it could correctly come from.
+ let egress = self
+ .egress
+ .provision(session_id, &origin.sender, &repo_url)
+ .await?;
+
self.sessions
.create_session(CreateAgentSessionParams {
id: session_id,
@@ -591,6 +696,7 @@ where
// Managed sandboxes run in the path baked into their image.
workspace: agent_session::MANAGED_CONTAINER_WORKSPACE.to_owned(),
sandbox_size,
+ egress_token_hash: Some(egress.session_token_hash),
// This open came from the trigger pipeline seeing the mention.
})
.await?;
@@ -607,13 +713,14 @@ where
})
.await?;
+ let mcp_servers = egress.sandbox.acp_servers();
let container = match self
.containers
.spawn(SpawnContainer {
session_id,
kind: AgentKind::of(bot_id),
- repo_url,
size: sandbox_size,
+ egress: egress.sandbox,
})
.await
{
@@ -634,7 +741,10 @@ where
}
};
self.sessions
- .attach_session(session_id, RuntimeAttachment::solo(container))
+ .attach_session(
+ session_id,
+ RuntimeAttachment::solo(container).mcp_servers(mcp_servers),
+ )
.await?;
let mut action = AgentAction::prompt(composed_prompt);
let AgentAction::Prompt(prompt) = &mut action else {
@@ -709,8 +819,14 @@ where
let session = self.sessions.get_session(session_id).await?;
if AgentKind::of(session.bot_id).is_managed() {
let container = self.containers.resume(session_id).await?;
+ let mcp_servers = self
+ .resumed_mcp_servers(session_id, &session.owner_id)
+ .await?;
self.sessions
- .attach_session(session_id, RuntimeAttachment::solo(container))
+ .attach_session(
+ session_id,
+ RuntimeAttachment::solo(container).mcp_servers(mcp_servers),
+ )
.await?;
} else {
// An external runtime is not ours to start - only its
@@ -809,10 +925,19 @@ async fn run_session_worker<
Runtimes,
PromptContext,
PromptComposer,
+ Egress,
>(
session_id: AgentSessionId,
inner: Arc<
- AgentHarnessInner<Sessions, Containers, Announcer, Runtimes, PromptContext, PromptComposer>,
+ AgentHarnessInner<
+ Sessions,
+ Containers,
+ Announcer,
+ Runtimes,
+ PromptContext,
+ PromptComposer,
+ Egress,
+ >,
>,
mut receiver: mpsc::UnboundedReceiver<QueuedCommand>,
) where
@@ -822,6 +947,7 @@ async fn run_session_worker<
Runtimes: RuntimeConnections,
PromptContext: ChannelPromptContext,
PromptComposer: AgentPromptComposer,
+ Egress: SandboxEgressProvisioner,
{
while let Some(queued) = receiver.recv().await {
let QueuedCommand {
diff --git a/crates/agent_harness/src/domain/service/test.rs b/crates/agent_harness/src/domain/service/test.rs
index f49b52f28d..c2c364b160 100644
--- a/crates/agent_harness/src/domain/service/test.rs
+++ b/crates/agent_harness/src/domain/service/test.rs
@@ -40,6 +40,7 @@ use crate::outbound::runtime_registry::RuntimeRegistry;
use crate::testing::helpers::agent::FakeAgent;
use crate::testing::helpers::announcer::AnnouncerMock;
use crate::testing::helpers::containers::{ContainerMock, ContainerSender, MockContainerManager};
+use crate::testing::helpers::egress::{EgressProvisionerMock, test_egress};
use agent_session::domain::error::AgentSessionError;
use agent_session::domain::ports::{
OpenExternalAgentSession, OpenManagedSession, SessionOpener as _,
@@ -180,6 +181,7 @@ type TestHarness = AgentHarnessService<
Arc<RuntimeRegistry<ContainerSender>>,
PromptContextMock,
PromptComposerMock,
+ EgressProvisionerMock,
>;
fn harness_with_edges(
@@ -207,6 +209,7 @@ fn harness_with_edges(
Arc::clone(&runtimes),
prompt_context,
prompt_composer,
+ EgressProvisionerMock::new(),
SessionDefaults {
bot_id: BotId::TEST_A,
model: "claude".to_owned(),
@@ -312,6 +315,7 @@ async fn disconnected_session(
repo_url: Some("https://github.com/macro-inc/macro".to_owned()),
workspace: "/workspace".to_owned(),
sandbox_size: agent_session::domain::model::SandboxSize::Default,
+ egress_token_hash: None,
},
)
.await
@@ -323,8 +327,8 @@ async fn disconnected_session(
.spawn(SpawnContainer {
session_id: id,
kind: AgentKind::SandboxedCoder,
- repo_url: "https://github.com/macro-inc/macro".to_owned(),
size: agent_session::domain::model::SandboxSize::Default,
+ egress: test_egress(),
})
.await
.expect("the original sandbox should exist");
@@ -1409,6 +1413,7 @@ async fn a_managed_session_opens_as_the_managed_default_bot() {
RuntimeRegistry::<ContainerSender>::new(),
PromptContextMock::default(),
PromptComposerMock::default(),
+ EgressProvisionerMock::new(),
HarnessDefaults::new(SessionDefaults {
bot_id: BotId::TEST_A,
model: "claude".to_owned(),
diff --git a/crates/agent_harness/src/outbound/containers.rs b/crates/agent_harness/src/outbound/containers.rs
index 7a538bf1ab..ea55e80058 100644
--- a/crates/agent_harness/src/outbound/containers.rs
+++ b/crates/agent_harness/src/outbound/containers.rs
@@ -80,6 +80,13 @@ impl ContainerManager for HarnessContainers {
}
}
+ async fn session_token(&self, session: AgentSessionId) -> Result<Option<String>> {
+ match self {
+ Self::Daytona(manager) => manager.session_token(session).await,
+ Self::Local(manager) => manager.session_token(session).await,
+ }
+ }
+
async fn teardown(&self, session: AgentSessionId) -> Result<()> {
match self {
Self::Daytona(manager) => manager.teardown(session).await,
diff --git a/crates/agent_harness/src/outbound/cursor/manager.rs b/crates/agent_harness/src/outbound/cursor/manager.rs
index d7ca271765..320b6bcb42 100644
--- a/crates/agent_harness/src/outbound/cursor/manager.rs
+++ b/crates/agent_harness/src/outbound/cursor/manager.rs
@@ -279,6 +279,10 @@ where
// ignored me" into a sentence they can act on.
let session = AgentSessionRepo::get(&self.sessions, command.session_id).await?;
let (client, default_model_id) = self.client_for(&session).await?;
+ // No MCP servers pass through here: they ride the ACP protocol
+ // itself. The harness's session actor names them in `session/new`,
+ // and the in-process adapter forwards them to Cursor's API - the same
+ // rail every other transport uses.
Ok(self.serve_session(client, default_model_id, command.session_id, None))
}
@@ -311,9 +315,23 @@ where
}
None => None,
};
+ // No MCP servers on resume, deliberately. Cursor fixes an agent's MCP
+ // config when the agent is created, so a session that prompted before
+ // the restart keeps its servers on cursor.com regardless of what is
+ // passed here - and the session token needed to mint fresh entries
+ // died with the process (only its hash is persisted). The one session
+ // this loses servers for is one restored before its first prompt ever
+ // landed, which then creates its agent bare rather than not at all.
Ok(self.serve_session(client, default_model_id, session, restore))
}
+ /// A Cursor session has no container of ours to hold a token: the raw
+ /// token went to Cursor's cloud at agent creation and is not readable
+ /// back.
+ async fn session_token(&self, _session: AgentSessionId) -> Result<Option<String>> {
+ Ok(None)
+ }
+
async fn teardown(&self, session: AgentSessionId) -> Result<()> {
// Archive, never delete: the agent and its work belong to the Cursor
// account's owner, and archiving is reversible on cursor.com while
@@ -379,6 +397,10 @@ impl<Sessions> CursorAgents for RecordingCursor<Sessions>
where
Sessions: ExternalSessionRepo + Clone,
{
+ #[tracing::instrument(skip_all, err, fields(
+ session = %self.session_id,
+ mcp_servers = mcp_servers.len(),
+ ))]
async fn create_agent(
&self,
prompt: &str,
diff --git a/crates/agent_harness/src/outbound/cursor/manager/test.rs b/crates/agent_harness/src/outbound/cursor/manager/test.rs
index 2e88dfe561..9df6169e11 100644
--- a/crates/agent_harness/src/outbound/cursor/manager/test.rs
+++ b/crates/agent_harness/src/outbound/cursor/manager/test.rs
@@ -1,6 +1,7 @@
use super::super::keys::ResolvedCursorConfig;
use super::*;
use crate::domain::model::AgentKind;
+use crate::testing::helpers::egress::test_egress;
use agent_client_protocol::schema::v1::SessionId;
use agent_runtime_protocol::domain::ports::{Transport as _, TransportSender as _};
use agent_runtime_protocol::domain::schema::v0::{AcpMessage, ToRuntimeMessage, ToServerMessage};
@@ -53,6 +54,13 @@ impl AgentSessionRepo for StubSessions {
unimplemented!("the manager never creates sessions")
}
+ async fn find_by_egress_token_hash(
+ &self,
+ _egress_token_hash: &str,
+ ) -> SessionResult<Option<AgentSession>> {
+ unimplemented!("the manager never looks sessions up by egress token")
+ }
+
async fn get(&self, id: AgentSessionId) -> SessionResult<AgentSession> {
Ok(AgentSession {
id,
@@ -369,8 +377,8 @@ async fn spawning_and_prompting_records_the_minted_agent() {
.spawn(SpawnContainer {
session_id,
kind: AgentKind::Cursor,
- repo_url: "https://github.com/macro-inc/macro".to_owned(),
size: SandboxSize::Default,
+ egress: test_egress(),
})
.await
.expect("spawn");
@@ -447,8 +455,8 @@ async fn spawn_uses_the_owners_default_model() {
.spawn(SpawnContainer {
session_id,
kind: AgentKind::Cursor,
- repo_url: "https://github.com/macro-inc/macro".to_owned(),
size: SandboxSize::Default,
+ egress: crate::testing::helpers::egress::test_egress(),
})
.await
.expect("spawn");
@@ -493,6 +501,92 @@ async fn spawn_uses_the_owners_default_model() {
);
}
+/// MCP servers ride the ACP protocol itself: whatever the client names in
+/// `session/new` reaches the agent Cursor mints - which is how the harness's
+/// egress-proxied servers arrive, on the same rail as every other transport.
+#[tokio::test]
+async fn session_new_mcp_servers_reach_the_created_agent() {
+ let (base_url, _, created) = fake_cursor_api().await;
+ let sessions = StubSessions::default();
+ let session_id = AgentSessionId::new();
+ let manager = manager(base_url, sessions);
+
+ let transport = manager
+ .spawn(SpawnContainer {
+ session_id,
+ kind: AgentKind::Cursor,
+ size: SandboxSize::Default,
+ egress: test_egress(),
+ })
+ .await
+ .expect("spawn");
+ let (sender, mut receiver) = transport.split();
+
+ send_acp(
+ &sender,
+ serde_json::json!({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}),
+ )
+ .await;
+ next_acp(&mut receiver).await;
+ send_acp(
+ &sender,
+ serde_json::json!({"jsonrpc":"2.0","id":2,"method":"session/new","params":{
+ "cwd":"/workspace",
+ "mcpServers":[
+ {
+ "type": "http",
+ "name": "macro",
+ "url": "https://egress.test/mcp-macro",
+ "headers": [{"name": "Authorization", "value": "Bearer test-session-token"}],
+ },
+ {
+ "type": "http",
+ "name": "google_sheets",
+ "url": "https://egress.test/mcp/google_sheets",
+ "headers": [{"name": "Authorization", "value": "Bearer test-session-token"}],
+ },
+ ],
+ }}),
+ )
+ .await;
+ let acp_session = next_acp(&mut receiver).await["result"]["sessionId"]
+ .as_str()
+ .expect("a session id")
+ .to_owned();
+ send_acp(
+ &sender,
+ serde_json::json!({"jsonrpc":"2.0","id":3,"method":"session/prompt","params":{
+ "sessionId": acp_session,
+ "prompt": [{"type":"text","text":"go"}],
+ }}),
+ )
+ .await;
+ loop {
+ if next_acp(&mut receiver).await["id"] == 3 {
+ break;
+ }
+ }
+
+ let body = created.lock().expect("create log poisoned")[0].clone();
+ assert_eq!(
+ body["mcpServers"],
+ serde_json::json!([
+ {
+ "name": "macro",
+ "type": "http",
+ "url": "https://egress.test/mcp-macro",
+ "headers": { "Authorization": "Bearer test-session-token" },
+ },
+ {
+ "name": "google_sheets",
+ "type": "http",
+ "url": "https://egress.test/mcp/google_sheets",
+ "headers": { "Authorization": "Bearer test-session-token" },
+ },
+ ])
+ );
+}
+
/// Resume restores the persisted identity: the harness's `session/load` is
/// answered, and the next prompt is a follow-up run on the restored agent —
/// not a fresh agent.
@@ -604,8 +698,8 @@ async fn an_idle_pipe_is_shut_down() {
.spawn(SpawnContainer {
session_id: AgentSessionId::new(),
kind: AgentKind::Cursor,
- repo_url: "https://github.com/macro-inc/macro".to_owned(),
size: SandboxSize::Default,
+ egress: test_egress(),
})
.await
.expect("spawn");
@@ -672,8 +766,8 @@ async fn spawning_without_a_registered_key_says_so() {
.spawn(SpawnContainer {
session_id: AgentSessionId::new(),
kind: AgentKind::Cursor,
- repo_url: "https://github.com/macro-inc/macro".to_owned(),
size: SandboxSize::Default,
+ egress: test_egress(),
})
.await
// `err()` rather than `expect_err`: the success type is a live
diff --git a/crates/agent_harness/src/outbound/daytona/manager.rs b/crates/agent_harness/src/outbound/daytona/manager.rs
index a717f926fa..95284fc979 100644
--- a/crates/agent_harness/src/outbound/daytona/manager.rs
+++ b/crates/agent_harness/src/outbound/daytona/manager.rs
@@ -12,9 +12,7 @@ use tracing::Instrument as _;
use super::client::DaytonaClient;
use super::errors::DaytonaError;
-use super::types::{
- AnthropicApiKey, DaytonaSettings, Env, GithubToken, Labels, PortPreview, Snapshot,
-};
+use super::types::{AnthropicApiKey, DaytonaSettings, Env, Labels, PortPreview, Snapshot};
use crate::domain::error::{HarnessError, Result};
use crate::domain::model::SpawnContainer;
use crate::domain::ports::ContainerManager;
@@ -26,6 +24,7 @@ use crate::outbound::provision::{self, SESSION_LABEL};
use crate::outbound::sidecar::SidecarTransport;
const LOG_FETCH_TIMEOUT: Duration = Duration::from_secs(15);
+const EXEC_TIMEOUT: Duration = Duration::from_secs(15);
const IDLE_TIMEOUT: Duration = Duration::from_secs(5 * 60);
const REAP_INTERVAL: Duration = Duration::from_secs(1);
const STOP_TIMEOUT: Duration = Duration::from_secs(30);
@@ -86,7 +85,6 @@ impl DaytonaContainerManagerState {
pub struct DaytonaContainerManager {
client: DaytonaClient,
snapshot: Snapshot,
- github_token: GithubToken,
anthropic_api_key: AnthropicApiKey,
managed: Arc<DaytonaContainerManagerState>,
}
@@ -99,7 +97,6 @@ impl DaytonaContainerManager {
api_url,
api_key,
snapshot,
- github_token,
anthropic_api_key,
} = settings;
let client = DaytonaClient::new(api_url, api_key);
@@ -110,7 +107,6 @@ impl DaytonaContainerManager {
Self {
client,
snapshot,
- github_token,
anthropic_api_key,
managed,
}
@@ -361,33 +357,21 @@ impl ContainerManager for DaytonaContainerManager {
async fn spawn(&self, command: SpawnContainer) -> Result<DaytonaContainer> {
let SpawnContainer {
session_id,
- // Routing already consumed the kind; every spawn that reaches
- // Daytona is a sandbox spawn.
- kind: _,
- repo_url,
size,
+ egress,
+ ..
} = command;
- // `GITHUB_TOKEN` is here for `gh auth setup-git` and the github MCP
- // server. It is also the env var opencode's `github-copilot` provider
- // activates on, so its mere presence makes opencode advertise every
- // Copilot model - and a plain PAT is not a Copilot credential, so each
- // one fails at prompt time with "Authorization header is badly
- // formatted". `container/opencode.json` pins `enabled_providers` to
- // keep that list honest; do not drop that pin while this var is set.
// `ANTHROPIC_API_KEY` is what activates opencode's `anthropic`
// provider — with `enabled_providers` pinned in
// `container/opencode.json`, it is the sandbox's only model source.
- let env = Env::from(HashMap::from([
- ("REPO_URL".to_owned(), repo_url),
- (
- "GITHUB_TOKEN".to_owned(),
- self.github_token.expose().to_owned(),
- ),
- (
- "ANTHROPIC_API_KEY".to_owned(),
- self.anthropic_api_key.expose().to_owned(),
- ),
- ]));
+ // Nothing else goes in: the repository and its credential now reach
+ // the sandbox through the egress proxy.
+ let mut env = HashMap::from([(
+ "ANTHROPIC_API_KEY".to_owned(),
+ self.anthropic_api_key.expose().to_owned(),
+ )]);
+ env.extend(egress.environment());
+ let env = Env::from(env);
let labels = Labels::from(HashMap::from([(
SESSION_LABEL.to_owned(),
session_id.to_string(),
@@ -509,6 +493,29 @@ impl ContainerManager for DaytonaContainerManager {
}
}
+ #[tracing::instrument(err, skip(self))]
+ async fn session_token(&self, session: AgentSessionId) -> Result<Option<String>> {
+ let Some(id) = self
+ .client
+ .find_by_label(SESSION_LABEL, &session.to_string())
+ .await
+ .map_err(unavailable)?
+ .map(DaytonaSandboxId::new)
+ else {
+ return Ok(None);
+ };
+ let output = self
+ .client
+ .exec(
+ id.as_str(),
+ &provision::session_token_command(),
+ EXEC_TIMEOUT,
+ )
+ .await
+ .map_err(unavailable)?;
+ Ok(provision::parse_session_token(&output))
+ }
+
#[tracing::instrument(err, skip(self))]
async fn teardown(&self, session: AgentSessionId) -> Result<()> {
let Some(id) = self
diff --git a/crates/agent_harness/src/outbound/daytona/mod.rs b/crates/agent_harness/src/outbound/daytona/mod.rs
index be18314b12..3b9c867f1a 100644
--- a/crates/agent_harness/src/outbound/daytona/mod.rs
+++ b/crates/agent_harness/src/outbound/daytona/mod.rs
@@ -9,6 +9,5 @@ pub use client::DaytonaClient;
pub use errors::DaytonaError;
pub use manager::{DaytonaContainer, DaytonaContainerManager};
pub use types::{
- AnthropicApiKey, DaytonaApiKey, DaytonaSettings, Env, GithubToken, Labels, PortPreview,
- Snapshot,
+ AnthropicApiKey, DaytonaApiKey, DaytonaSettings, Env, Labels, PortPreview, Snapshot,
};
diff --git a/crates/agent_harness/src/outbound/daytona/types.rs b/crates/agent_harness/src/outbound/daytona/types.rs
index 341fad61ce..843190dd5e 100644
--- a/crates/agent_harness/src/outbound/daytona/types.rs
+++ b/crates/agent_harness/src/outbound/daytona/types.rs
@@ -49,10 +49,6 @@ pub struct PortPreview {
#[derive(Clone)]
pub struct DaytonaApiKey(String);
-/// Token with read access to the repository cloned into sandboxes.
-#[derive(Clone)]
-pub struct GithubToken(String);
-
impl DaytonaApiKey {
/// Wrap a Daytona API credential.
#[must_use]
@@ -65,25 +61,13 @@ impl DaytonaApiKey {
}
}
-impl GithubToken {
- /// Wrap a GitHub credential.
- #[must_use]
- pub fn new(value: String) -> Self {
- Self(value)
- }
-
- pub(crate) fn expose(&self) -> &str {
- &self.0
- }
-}
-
/// API key sandboxes use to run Anthropic models.
///
/// opencode activates its `anthropic` provider on this variable's value —
-/// empty behaves like absent — so, like [`GithubToken`], it wraps a possibly
-/// empty string and is always injected. Empty means the sandbox has no model
-/// provider at all (`container/opencode.json` enables only `anthropic`), so
-/// managed sessions advertise no models and cannot prompt.
+/// empty behaves like absent — so it wraps a possibly empty string and is
+/// always injected. Empty means the sandbox has no model provider at all
+/// (`container/opencode.json` enables only `anthropic`), so managed sessions
+/// advertise no models and cannot prompt.
#[derive(Clone)]
pub struct AnthropicApiKey(String);
@@ -107,8 +91,6 @@ pub struct DaytonaSettings {
pub api_key: DaytonaApiKey,
/// Prebuilt snapshot used to create sandboxes.
pub snapshot: Snapshot,
- /// Token with read access to the repository cloned into sandboxes.
- pub github_token: GithubToken,
/// Key sandboxes run Anthropic models with.
pub anthropic_api_key: AnthropicApiKey,
}
diff --git a/crates/agent_harness/src/outbound/egress.rs b/crates/agent_harness/src/outbound/egress.rs
new file mode 100644
index 0000000000..797ab5e4b0
--- /dev/null
+++ b/crates/agent_harness/src/outbound/egress.rs
@@ -0,0 +1,163 @@
+//! Handing a sandbox its one secret, and telling opencode where to spend it.
+//!
+//! Two adapter concerns the domain has no business with: minting a token, and
+//! listing the owner's Pipedream-connected apps, which needs their rows.
+//!
+//! Both the minting and the hashing are `agent_egress`'s, not a second
+//! implementation of either. The two ends of this token are written in
+//! different crates and read months apart, and a hash computed differently at
+//! each end reads at runtime as "every request from every sandbox is
+//! unauthenticated".
+
+use agent_egress::domain::model::{McpServerSlug, RepoSlug, SessionToken};
+use macro_user_id::user_id::MacroUserIdStr;
+use pipedream_mcp::domain::ports::ConnectionStore;
+use std::sync::Arc;
+use url::Url;
+
+use crate::domain::error::{HarnessError, Result};
+use crate::domain::model::{ProvisionedEgress, SandboxEgress};
+use crate::domain::ports::SandboxEgressProvisioner;
+use agent_session::domain::model::AgentSessionId;
+
+#[cfg(test)]
+mod test;
+
+/// The only host a configured repository URL may name. Validating the
+/// deployment's own configuration, not a request: a URL pointing somewhere else
+/// would mint a session token for a repository the proxy cannot reach.
+const GITHUB_HOST: &str = "github.com";
+
+/// Mints session tokens and gathers the MCP servers a sandbox may dial.
+pub struct EgressProvisioner<Connections> {
+ connections: Arc<Connections>,
+ base_url: String,
+}
+
+impl<Connections> EgressProvisioner<Connections>
+where
+ Connections: ConnectionStore,
+{
+ /// Build the provisioner over the Pipedream connection store and the
+ /// egress proxy's public address.
+ pub fn new(connections: Arc<Connections>, base_url: impl Into<String>) -> Self {
+ Self {
+ connections,
+ base_url: base_url.into().trim_end_matches('/').to_owned(),
+ }
+ }
+
+ /// The slugs of the owner's enabled Pipedream connections, verbatim.
+ ///
+ /// `app_slug`, exactly as the proxy resolves it - the same value at both
+ /// ends by equality is what makes a server entry dialable, and there is
+ /// no derivation for the two to disagree over. Macro's own server is not
+ /// in the list: every session has it, on its own route. An app the owner
+ /// turned off is left out here as well as refused by the proxy: an agent
+ /// that can see a server in its list will try it, and a tool call that
+ /// always fails is worse than a tool that is absent.
+ async fn slugs(&self, owner: &MacroUserIdStr<'static>) -> Result<Vec<McpServerSlug>> {
+ let records = self.connections.list(owner).await.map_err(|error| {
+ HarnessError::Egress(rootcause::report!(
+ "could not list Pipedream connections: {error:?}"
+ ))
+ })?;
+
+ let slugs: Vec<McpServerSlug> = records
+ .into_iter()
+ .filter(|record| record.enabled)
+ .filter_map(|record| {
+ let slug = McpServerSlug::parse(&record.app_slug);
+ if slug.is_none() {
+ // An app slug the strict parse refuses could never be
+ // dialed - the proxy would refuse the same path segment -
+ // so leaving it out is the only honest rendering.
+ tracing::warn!(
+ %owner,
+ app_slug = %record.app_slug,
+ "a Pipedream connection's app slug is not a valid path segment; skipped"
+ );
+ }
+ slug
+ })
+ .collect();
+ tracing::debug!(
+ mcp_servers = slugs.len(),
+ "advertising the owner's connected MCP servers"
+ );
+ Ok(slugs)
+ }
+}
+
+impl<Connections> SandboxEgressProvisioner for EgressProvisioner<Connections>
+where
+ Connections: ConnectionStore,
+{
+ #[tracing::instrument(err, skip(self), fields(%session, %owner))]
+ async fn provision(
+ &self,
+ session: AgentSessionId,
+ owner: &MacroUserIdStr<'static>,
+ repo_url: &str,
+ ) -> Result<ProvisionedEgress> {
+ // Validated even though nothing here uses it: it is the deployment's
+ // repository URL, and a session whose git traffic could never resolve
+ // should fail at provisioning rather than at the agent's first clone.
+ repo_slug(repo_url)?;
+
+ let token = SessionToken::mint();
+
+ Ok(ProvisionedEgress {
+ session_token_hash: token.hash(),
+ sandbox: SandboxEgress {
+ base_url: self.base_url.clone(),
+ session_token: token.as_str().to_owned(),
+ mcp_servers: self.slugs(owner).await?,
+ },
+ })
+ }
+
+ #[tracing::instrument(err, skip(self, session_token), fields(%owner))]
+ async fn restore(
+ &self,
+ owner: &MacroUserIdStr<'static>,
+ session_token: String,
+ ) -> Result<SandboxEgress> {
+ Ok(SandboxEgress {
+ base_url: self.base_url.clone(),
+ session_token,
+ mcp_servers: self.slugs(owner).await?,
+ })
+ }
+}
+
+/// The repository a configured GitHub URL names.
+///
+/// Deliberately narrow: it must be `https://github.com/<owner>/<name>` and
+/// nothing else. This reads the deployment's own configuration, so a URL that
+/// is nearly right - a different host, an extra path segment - is a mistake
+/// worth failing on rather than guessing at, and the answer decides which
+/// repository a session's credential will be minted for.
+fn repo_slug(repo_url: &str) -> Result<RepoSlug> {
+ let unusable = || {
+ HarnessError::Egress(rootcause::report!(
+ "configured repository url does not name a github repository"
+ ))
+ };
+
+ let url = Url::parse(repo_url).map_err(|_| unusable())?;
+ if url.host_str() != Some(GITHUB_HOST) {
+ return Err(unusable());
+ }
+
+ let mut segments = url.path_segments().ok_or_else(unusable)?;
+ let owner = segments.next().ok_or_else(unusable)?;
+ let name = segments.next().ok_or_else(unusable)?;
+ // Anything after the repository name is not part of it. A trailing empty
+ // segment is just a trailing slash.
+ if segments.any(|segment| !segment.is_empty()) {
+ return Err(unusable());
+ }
+
+ RepoSlug::parse(owner, name.trim_end_matches(".git")).ok_or_else(unusable)
+}
diff --git a/crates/agent_harness/src/outbound/egress/test.rs b/crates/agent_harness/src/outbound/egress/test.rs
new file mode 100644
index 0000000000..0d4dac5006
--- /dev/null
+++ b/crates/agent_harness/src/outbound/egress/test.rs
@@ -0,0 +1,231 @@
+use super::*;
+
+fn slug(name: &str) -> McpServerSlug {
+ McpServerSlug::parse(name).expect("a valid app slug")
+}
+
+#[test]
+fn reads_the_repository_out_of_a_configured_url() {
+ for url in [
+ "https://github.com/macro-inc/macro",
+ "https://github.com/macro-inc/macro/",
+ "https://github.com/macro-inc/macro.git",
+ ] {
+ let repo = repo_slug(url).expect(url);
+ assert_eq!(repo.to_string(), "macro-inc/macro", "for {url}");
+ }
+}
+
+#[test]
+fn refuses_a_url_that_does_not_name_a_repository() {
+ for url in [
+ "",
+ "not a url",
+ "https://github.com",
+ "https://github.com/macro-inc",
+ "https://gitlab.com/macro-inc/macro",
+ "https://github.com.evil.example/macro-inc/macro",
+ "https://github.com/macro-inc/macro/tree/main",
+ ] {
+ assert!(repo_slug(url).is_err(), "accepted {url}");
+ }
+}
+
+struct FixedConnections(Vec<pipedream_mcp::domain::models::PipedreamConnection>);
+
+impl ConnectionStore for FixedConnections {
+ type Err = std::convert::Infallible;
+
+ async fn save(
+ &self,
+ _record: &pipedream_mcp::domain::models::PipedreamConnection,
+ ) -> Result<(), Self::Err> {
+ unreachable!("provisioning never writes")
+ }
+
+ async fn load(
+ &self,
+ _user_id: &MacroUserIdStr<'static>,
+ _app_slug: &str,
+ ) -> Result<Option<pipedream_mcp::domain::models::PipedreamConnection>, Self::Err> {
+ unreachable!("provisioning lists, never loads one")
+ }
+
+ async fn delete(
+ &self,
+ _user_id: &MacroUserIdStr<'static>,
+ _app_slug: &str,
+ ) -> Result<(), Self::Err> {
+ unreachable!("provisioning never deletes")
+ }
+
+ async fn list(
+ &self,
+ _user_id: &MacroUserIdStr<'static>,
+ ) -> Result<Vec<pipedream_mcp::domain::models::PipedreamConnection>, Self::Err> {
+ Ok(self.0.clone())
+ }
+}
+
+fn connection(app_slug: &str, enabled: bool) -> pipedream_mcp::domain::models::PipedreamConnection {
+ pipedream_mcp::domain::models::PipedreamConnection {
+ user_id: MacroUserIdStr::try_from_email("[email protected]").expect("a valid user id"),
+ app_slug: app_slug.to_owned(),
+ server_name: app_slug.to_owned(),
+ account_id: format!("apn_{app_slug}"),
+ enabled,
+ }
+}
+
+/// Provisioning lists the owner's enabled app slugs verbatim - nothing is
+/// derived, disabled apps are absent, and an app slug the strict parse
+/// refuses is skipped rather than repaired into something dialable.
+#[tokio::test]
+async fn lists_enabled_app_slugs_verbatim() {
+ let provisioner = EgressProvisioner::new(
+ Arc::new(FixedConnections(vec![
+ connection("linear", true),
+ connection("google_sheets", true),
+ connection("datadog", false),
+ connection("Not A Slug!", true),
+ ])),
+ "https://egress.macro.com",
+ );
+
+ let provisioned = provisioner
+ .provision(
+ AgentSessionId::new(),
+ &MacroUserIdStr::try_from_email("[email protected]").expect("a valid user id"),
+ "https://github.com/macro-inc/macro",
+ )
+ .await
+ .expect("provisioned");
+
+ let slugs: Vec<String> = provisioned
+ .sandbox
+ .mcp_servers
+ .iter()
+ .map(ToString::to_string)
+ .collect();
+ assert_eq!(slugs, ["linear", "google_sheets"]);
+}
+
+/// `restore` rebuilds the same environment around a token that already
+/// exists: nothing is minted, and the server list is read fresh.
+#[tokio::test]
+async fn restore_wraps_an_existing_token_in_a_fresh_listing() {
+ let provisioner = EgressProvisioner::new(
+ Arc::new(FixedConnections(vec![connection("linear", true)])),
+ "https://egress.macro.com",
+ );
+
+ let restored = provisioner
+ .restore(
+ &MacroUserIdStr::try_from_email("[email protected]").expect("a valid user id"),
+ "already-minted-token".to_owned(),
+ )
+ .await
+ .expect("restored");
+
+ assert_eq!(restored.session_token, "already-minted-token");
+ let slugs: Vec<String> = restored
+ .mcp_servers
+ .iter()
+ .map(ToString::to_string)
+ .collect();
+ assert_eq!(slugs, ["linear"]);
+}
+
+fn egress(slugs: &[&str]) -> SandboxEgress {
+ SandboxEgress {
+ base_url: "https://egress.macro.com".to_owned(),
+ session_token: "session-token".to_owned(),
+ mcp_servers: slugs.iter().map(|name| slug(name)).collect(),
+ }
+}
+
+/// Every server points at the proxy and carries the session token rather than
+/// any upstream credential; Macro's own server leads the list on its own
+/// route.
+#[test]
+fn points_every_acp_server_at_the_proxy() {
+ let servers = egress(&["datadog", "linear"]).acp_servers();
+
+ let rendered: Vec<(String, String, Vec<(String, String)>)> = servers
+ .into_iter()
+ .map(|server| match server {
+ agent_client_protocol::schema::v1::McpServer::Http(http) => (
+ http.name,
+ http.url,
+ http.headers
+ .into_iter()
+ .map(|header| (header.name, header.value))
+ .collect(),
+ ),
+ other => panic!("every egress server is http transport, got {other:?}"),
+ })
+ .collect();
+
+ let authorization = vec![(
+ "Authorization".to_owned(),
+ "Bearer session-token".to_owned(),
+ )];
+ assert_eq!(
+ rendered,
+ [
+ (
+ "macro".to_owned(),
+ "https://egress.macro.com/mcp-macro".to_owned(),
+ authorization.clone(),
+ ),
+ (
+ "datadog".to_owned(),
+ "https://egress.macro.com/mcp/datadog".to_owned(),
+ authorization.clone(),
+ ),
+ (
+ "linear".to_owned(),
+ "https://egress.macro.com/mcp/linear".to_owned(),
+ authorization,
+ ),
+ ]
+ );
+}
+
+/// An owner with no connected apps still gets Macro's own server.
+#[test]
+fn an_owner_with_no_connected_apps_still_gets_the_macro_server() {
+ let entries: Vec<(String, String)> = egress(&[]).server_entries().collect();
+
+ assert_eq!(
+ entries,
+ [(
+ "macro".to_owned(),
+ "https://egress.macro.com/mcp-macro".to_owned()
+ )]
+ );
+}
+
+/// The environment carries the token, so nothing about this value may reach a
+/// log.
+#[test]
+fn the_egress_environment_does_not_print_its_secrets() {
+ let egress = egress(&["linear"]);
+
+ let printed = format!("{egress:?}");
+ assert!(!printed.contains("session-token"), "{printed}");
+ assert!(printed.contains("https://egress.macro.com"), "{printed}");
+
+ let environment: Vec<String> = egress
+ .environment()
+ .into_iter()
+ .map(|(name, _value)| name)
+ .collect();
+ assert_eq!(
+ environment,
+ [
+ "MACRO_EGRESS_URL".to_owned(),
+ "MACRO_SESSION_TOKEN".to_owned()
+ ]
+ );
+}
diff --git a/crates/agent_harness/src/outbound/local/manager.rs b/crates/agent_harness/src/outbound/local/manager.rs
index b74d8d9c76..7b915ff28f 100644
--- a/crates/agent_harness/src/outbound/local/manager.rs
+++ b/crates/agent_harness/src/outbound/local/manager.rs
@@ -5,10 +5,10 @@ use agent_session::domain::model::{AgentSessionId, SandboxSize};
use super::docker::{ContainerRef, Docker, RunSpec};
use super::errors::LocalError;
use crate::domain::error::{HarnessError, Result};
-use crate::domain::model::SpawnContainer;
+use crate::domain::model::{SandboxEgress, SpawnContainer};
use crate::domain::ports::ContainerManager;
use crate::domain::sandbox::{SandboxResizeEffect, create_only_resize_effect};
-use crate::outbound::daytona::{AnthropicApiKey, GithubToken};
+use crate::outbound::daytona::AnthropicApiKey;
use crate::outbound::provision::{self, SESSION_LABEL};
use crate::outbound::sidecar::SidecarTransport;
@@ -26,8 +26,6 @@ pub struct LocalSettings {
pub image: String,
/// Compose network the sandbox joins so this service can dial it by name.
pub network: String,
- /// Token with read access to the repository cloned into sandboxes.
- pub github_token: GithubToken,
/// Key sandboxes run Anthropic models with.
pub anthropic_api_key: AnthropicApiKey,
}
@@ -47,7 +45,6 @@ pub struct LocalContainerManager {
docker: Docker,
image: String,
network: String,
- github_token: GithubToken,
anthropic_api_key: AnthropicApiKey,
}
@@ -59,14 +56,12 @@ impl LocalContainerManager {
docker_binary,
image,
network,
- github_token,
anthropic_api_key,
} = settings;
Self {
docker: Docker::new(docker_binary),
image,
network,
- github_token,
anthropic_api_key,
}
}
@@ -196,15 +191,18 @@ impl LocalContainerManager {
impl ContainerManager for LocalContainerManager {
type Transport = SidecarTransport;
- #[tracing::instrument(err, skip(self))]
+ // `skip_all`: `SpawnContainer` carries the egress session token; nothing
+ // secret-bearing may be Debug-recorded into the span.
+ #[tracing::instrument(err, skip_all, fields(session_id = %command.session_id))]
async fn spawn(&self, command: SpawnContainer) -> Result<Self::Transport> {
let SpawnContainer {
session_id,
// Routing already consumed the kind; every spawn that reaches
// the local provider is a sandbox spawn.
kind: _,
- repo_url,
size: _,
+ egress,
+ ..
} = command;
if !self
@@ -234,7 +232,7 @@ impl ContainerManager for LocalContainerManager {
image: self.image.clone(),
name: container_name(session_id),
labels: vec![(SESSION_LABEL.to_owned(), session_id.to_string())],
- env: sandbox_env(repo_url, &self.github_token, &self.anthropic_api_key),
+ env: sandbox_env(&self.anthropic_api_key, egress),
network: self.network.clone(),
};
let container = self.docker.run(&spec).await.map_err(unavailable)?;
@@ -271,6 +269,26 @@ impl ContainerManager for LocalContainerManager {
self.bring_up(&container).await
}
+ #[tracing::instrument(err, skip(self))]
+ async fn session_token(&self, session: AgentSessionId) -> Result<Option<String>> {
+ let Some(container) = self.find(session).await? else {
+ return Ok(None);
+ };
+ let (status, output) = self
+ .docker
+ .exec(
+ &container,
+ &provision::session_token_command(),
+ Duration::from_secs(15),
+ )
+ .await
+ .map_err(unavailable)?;
+ if status != 0 {
+ return Ok(None);
+ }
+ Ok(provision::parse_session_token(&output))
+ }
+
#[tracing::instrument(err, skip(self))]
async fn teardown(&self, session: AgentSessionId) -> Result<()> {
let Some(container) = self.find(session).await? else {
@@ -299,18 +317,15 @@ fn sidecar_address(container: &ContainerRef) -> String {
}
fn sandbox_env(
- repo_url: String,
- github_token: &GithubToken,
anthropic_api_key: &AnthropicApiKey,
+ egress: SandboxEgress,
) -> Vec<(String, String)> {
- vec![
- ("REPO_URL".to_owned(), repo_url),
- ("GITHUB_TOKEN".to_owned(), github_token.expose().to_owned()),
- (
- "ANTHROPIC_API_KEY".to_owned(),
- anthropic_api_key.expose().to_owned(),
- ),
- ]
+ let mut env = vec![(
+ "ANTHROPIC_API_KEY".to_owned(),
+ anthropic_api_key.expose().to_owned(),
+ )];
+ env.extend(egress.environment());
+ env
}
fn unavailable(error: LocalError) -> HarnessError {
diff --git a/crates/agent_harness/src/outbound/local/manager/test.rs b/crates/agent_harness/src/outbound/local/manager/test.rs
index 78b151c53f..7545ca330f 100644
--- a/crates/agent_harness/src/outbound/local/manager/test.rs
+++ b/crates/agent_harness/src/outbound/local/manager/test.rs
@@ -1,5 +1,6 @@
use super::*;
-use crate::outbound::daytona::{AnthropicApiKey, GithubToken};
+use crate::outbound::daytona::AnthropicApiKey;
+use crate::testing::helpers::egress::test_egress;
/// One container per session, so a resume finds exactly one and `docker ps`
/// says which session it belongs to.
@@ -22,25 +23,27 @@ fn a_sidecar_is_dialed_by_container_name() {
);
}
-/// Same credentials Daytona injects, so the readiness recipe is exercised
-/// against the same environment a deployed sandbox sees. The Anthropic key
-/// is what activates the one model provider `container/opencode.json`
-/// enables.
+/// Same environment Daytona injects, so the readiness recipe is exercised
+/// against what a deployed sandbox sees: the Anthropic key that activates the
+/// one model provider `container/opencode.json` enables, plus the egress
+/// variables the clone and every outbound call go through. No GitHub
+/// credential - the proxy holds that one.
#[test]
-fn sandbox_env_carries_the_repo_and_credentials() {
+fn sandbox_env_carries_the_model_key_and_egress() {
let env = sandbox_env(
- "https://github.com/macro-inc/macro".to_owned(),
- &GithubToken::new("test-token".to_owned()),
&AnthropicApiKey::new("test-anthropic-key".to_owned()),
+ test_egress(),
);
- assert!(env.contains(&(
- "REPO_URL".to_owned(),
- "https://github.com/macro-inc/macro".to_owned()
- )));
- assert!(env.contains(&("GITHUB_TOKEN".to_owned(), "test-token".to_owned())));
assert!(env.contains(&(
"ANTHROPIC_API_KEY".to_owned(),
"test-anthropic-key".to_owned()
)));
+ assert!(
+ !env.iter()
+ .any(|(key, _)| key == "GITHUB_TOKEN" || key == "REPO_URL")
+ );
+ for (key, value) in test_egress().environment() {
+ assert!(env.contains(&(key, value)));
+ }
}
diff --git a/crates/agent_harness/src/outbound/mod.rs b/crates/agent_harness/src/outbound/mod.rs
index ecc07d94f1..7fb25fdddb 100644
--- a/crates/agent_harness/src/outbound/mod.rs
+++ b/crates/agent_harness/src/outbound/mod.rs
@@ -7,6 +7,7 @@ pub mod channel_prompt_context;
pub mod containers;
pub mod cursor;
pub mod daytona;
+pub mod egress;
pub mod local;
pub(crate) mod managed_containers;
pub mod namespace;
diff --git a/crates/agent_harness/src/outbound/namespace/manager.rs b/crates/agent_harness/src/outbound/namespace/manager.rs
index 874c13e460..118251cca2 100644
--- a/crates/agent_harness/src/outbound/namespace/manager.rs
+++ b/crates/agent_harness/src/outbound/namespace/manager.rs
@@ -12,7 +12,6 @@ use crate::domain::error::{HarnessError, Result};
use crate::domain::model::SpawnContainer;
use crate::domain::ports::ContainerManager;
use crate::domain::sandbox::{SandboxResizeEffect, create_only_resize_effect, resources};
-use crate::outbound::daytona::{AnthropicApiKey, GithubToken};
use crate::outbound::provision;
use crate::outbound::sidecar::SidecarTransport;
@@ -21,8 +20,6 @@ pub struct NamespaceContainerManager {
client: NamespaceClient,
image_ref: super::types::ImageRef,
lifetime: std::time::Duration,
- github_token: GithubToken,
- anthropic_api_key: AnthropicApiKey,
}
impl NamespaceContainerManager {
@@ -34,15 +31,11 @@ impl NamespaceContainerManager {
token,
image_ref,
lifetime,
- github_token,
- anthropic_api_key,
} = settings;
Self {
client: NamespaceClient::new(api_url, token),
image_ref,
lifetime,
- github_token,
- anthropic_api_key,
}
}
@@ -96,26 +89,23 @@ impl NamespaceContainerManager {
impl ContainerManager for NamespaceContainerManager {
type Transport = NamespaceContainer;
+ // `skip_all`: `SpawnContainer` carries the egress session token; nothing
+ // secret-bearing may be Debug-recorded into the span.
#[tracing::instrument(
name = "agent.container.spawn",
err,
- skip(self),
- fields(agent.container.provider = "namespace")
+ skip_all,
+ fields(
+ agent.container.provider = "namespace",
+ session_id = %command.session_id,
+ )
)]
async fn spawn(&self, command: SpawnContainer) -> Result<Self::Transport> {
+ let mut env = Vec::new();
+ env.extend(command.egress.environment());
let container = ContainerSpec {
image_ref: self.image_ref.clone(),
- env: vec![
- ("REPO_URL".to_owned(), command.repo_url),
- (
- "GITHUB_TOKEN".to_owned(),
- self.github_token.expose().to_owned(),
- ),
- (
- "ANTHROPIC_API_KEY".to_owned(),
- self.anthropic_api_key.expose().to_owned(),
- ),
- ],
+ env,
exported_ports: vec![provision::SIDECAR_PORT],
};
let instance = self
@@ -155,6 +145,13 @@ impl ContainerManager for NamespaceContainerManager {
todo!("resuming Namespace instances is not implemented yet")
}
+ async fn session_token(&self, _session: AgentSessionId) -> Result<Option<String>> {
+ // Instances do hold a token in their environment, but reading it back
+ // needs the instance id for a session - the same lookup `resume` is
+ // waiting on.
+ todo!("recovering a Namespace instance's session token is not implemented yet")
+ }
+
async fn teardown(&self, _session: AgentSessionId) -> Result<()> {
// Tearing down needs the instance id for a session, which is the same
// lookup `resume` is waiting on.
diff --git a/crates/agent_harness/src/outbound/namespace/types.rs b/crates/agent_harness/src/outbound/namespace/types.rs
index 63ae81c6e3..b033953c32 100644
--- a/crates/agent_harness/src/outbound/namespace/types.rs
+++ b/crates/agent_harness/src/outbound/namespace/types.rs
@@ -1,7 +1,5 @@
use std::time::Duration;
-use crate::outbound::daytona::{AnthropicApiKey, GithubToken};
-
/// Namespace instance identifier.
#[derive(Debug, Clone)]
pub struct InstanceId(String);
@@ -97,8 +95,4 @@ pub struct NamespaceSettings {
pub image_ref: ImageRef,
/// Maximum lifetime of an instance.
pub lifetime: Duration,
- /// Token with read access to the repository cloned into instances.
- pub github_token: GithubToken,
- /// Key instances run Anthropic models with.
- pub anthropic_api_key: AnthropicApiKey,
}
diff --git a/crates/agent_harness/src/outbound/provision.rs b/crates/agent_harness/src/outbound/provision.rs
index 65afd1fef8..48209dbc25 100644
--- a/crates/agent_harness/src/outbound/provision.rs
+++ b/crates/agent_harness/src/outbound/provision.rs
@@ -27,8 +27,31 @@ const ENSURE_READY_SCRIPT: &str = include_str!(concat!(
"/container/ensure_ready.sh"
));
+#[cfg(test)]
+mod test;
+
/// Wrap the readiness recipe as one command for provider exec APIs.
#[must_use]
pub fn ensure_ready_command() -> String {
format!("bash -c '{}'", ENSURE_READY_SCRIPT.replace('\'', r"'\''"))
}
+
+/// Read the egress session token back out of a running container.
+///
+/// The container was handed the raw token in its environment at spawn and the
+/// harness keeps only the hash, so on reattach this is where the token comes
+/// from.
+#[must_use]
+pub fn session_token_command() -> String {
+ format!("printenv {}", crate::domain::model::SESSION_TOKEN_VARIABLE)
+}
+
+/// The token as [`session_token_command`]'s output carries it.
+///
+/// `None` for empty output: a container with no token in its environment
+/// answers a blank line, and a blank Authorization header is worse than none.
+#[must_use]
+pub fn parse_session_token(output: &str) -> Option<String> {
+ let token = output.trim();
+ (!token.is_empty()).then(|| token.to_owned())
+}
diff --git a/crates/agent_harness/src/outbound/provision/test.rs b/crates/agent_harness/src/outbound/provision/test.rs
new file mode 100644
index 0000000000..5aee404cf4
--- /dev/null
+++ b/crates/agent_harness/src/outbound/provision/test.rs
@@ -0,0 +1,21 @@
+use super::{ENSURE_READY_SCRIPT, SIDECAR_PORT};
+use crate::domain::model::{EGRESS_URL_VARIABLE, SESSION_TOKEN_VARIABLE};
+
+/// The script and the Rust constants name the same things. Asserted rather
+/// than commented because the two are edited months apart, and a rename on
+/// either side would otherwise show up only as a sandbox that never clones.
+#[test]
+fn the_script_and_the_harness_agree_on_shared_names() {
+ assert!(ENSURE_READY_SCRIPT.contains(&format!("sidecar_port={SIDECAR_PORT}")));
+ assert!(ENSURE_READY_SCRIPT.contains(&format!("${{{EGRESS_URL_VARIABLE}%/}}/git")));
+ assert!(ENSURE_READY_SCRIPT.contains(&format!("${SESSION_TOKEN_VARIABLE}")));
+}
+
+/// The sandbox holds no GitHub credential and is told no repository: it clones
+/// from the proxy, which reads both off the session's own grant.
+#[test]
+fn clone_uses_session_egress_without_a_github_token() {
+ assert!(!ENSURE_READY_SCRIPT.contains("GITHUB_TOKEN"));
+ assert!(!ENSURE_READY_SCRIPT.contains("REPO_URL"));
+ assert!(!ENSURE_READY_SCRIPT.contains("gh auth"));
+}
diff --git a/crates/agent_harness/src/outbound/routing.rs b/crates/agent_harness/src/outbound/routing.rs
index 243beeb234..21e01d1721 100644
--- a/crates/agent_harness/src/outbound/routing.rs
+++ b/crates/agent_harness/src/outbound/routing.rs
@@ -74,6 +74,16 @@ where
}
}
+ async fn session_token(&self, session: AgentSessionId) -> Result<Option<String>> {
+ match AgentKind::of(self.sessions.get(session).await?.bot_id) {
+ AgentKind::Cursor => self.cursor.session_token(session).await,
+ AgentKind::SandboxedCoder | AgentKind::InMemory => {
+ self.sandbox.session_token(session).await
+ }
+ AgentKind::External => Err(external_is_unroutable()),
+ }
+ }
+
async fn teardown(&self, session: AgentSessionId) -> Result<()> {
match AgentKind::of(self.sessions.get(session).await?.bot_id) {
AgentKind::Cursor => self.cursor.teardown(session).await,
diff --git a/crates/agent_harness/src/outbound/routing/test.rs b/crates/agent_harness/src/outbound/routing/test.rs
index e406958d44..85cbfcb50b 100644
--- a/crates/agent_harness/src/outbound/routing/test.rs
+++ b/crates/agent_harness/src/outbound/routing/test.rs
@@ -1,5 +1,6 @@
use super::*;
use crate::domain::sandbox::SandboxResizeEffect;
+use crate::testing::helpers::egress::test_egress;
use agent_runtime_protocol::domain::schema::v0::{ToRuntimeMessage, ToServerMessage};
use agent_session::domain::error::Result as SessionResult;
use agent_session::domain::model::{
@@ -65,6 +66,11 @@ impl ContainerManager for TaggedManager {
Ok(TaggedTransport)
}
+ async fn session_token(&self, _session: AgentSessionId) -> Result<Option<String>> {
+ self.record("session_token");
+ Ok(None)
+ }
+
async fn teardown(&self, _session: AgentSessionId) -> Result<()> {
self.record("teardown");
Ok(())
@@ -88,6 +94,13 @@ impl AgentSessionRepo for FixedBotSessions {
unimplemented!("the router never creates sessions")
}
+ async fn find_by_egress_token_hash(
+ &self,
+ _egress_token_hash: &str,
+ ) -> SessionResult<Option<AgentSession>> {
+ unimplemented!("the router never looks sessions up by egress token")
+ }
+
async fn get(&self, id: AgentSessionId) -> SessionResult<AgentSession> {
Ok(AgentSession {
id,
@@ -178,8 +191,8 @@ fn spawn_for(kind: AgentKind) -> SpawnContainer {
SpawnContainer {
session_id: AgentSessionId::new(),
kind,
- repo_url: "https://github.com/macro-inc/macro".to_owned(),
size: SandboxSize::Default,
+ egress: test_egress(),
}
}
diff --git a/crates/agent_harness/src/testing/helpers/containers.rs b/crates/agent_harness/src/testing/helpers/containers.rs
index ebc56bd9b4..d71ff594f6 100644
--- a/crates/agent_harness/src/testing/helpers/containers.rs
+++ b/crates/agent_harness/src/testing/helpers/containers.rs
@@ -339,6 +339,15 @@ impl ContainerManager for MockContainerManager {
Ok(container)
}
+ /// The fixed token every mock container "holds", for sessions that were
+ /// spawned; `None` otherwise, like a provider that finds no container.
+ async fn session_token(&self, session: AgentSessionId) -> Result<Option<String>, HarnessError> {
+ Ok(self
+ .lock()
+ .contains_key(&session)
+ .then(|| "test-session-token".to_owned()))
+ }
+
async fn teardown(&self, session: AgentSessionId) -> Result<(), HarnessError> {
self.teardowns.fetch_add(1, Ordering::Relaxed);
self.lock().remove(&session);
diff --git a/crates/agent_harness/src/testing/helpers/egress.rs b/crates/agent_harness/src/testing/helpers/egress.rs
new file mode 100644
index 0000000000..7885349269
--- /dev/null
+++ b/crates/agent_harness/src/testing/helpers/egress.rs
@@ -0,0 +1,74 @@
+//! Sandbox egress provisioner test double.
+
+use std::sync::{Arc, Mutex};
+
+use agent_session::domain::model::AgentSessionId;
+use macro_user_id::user_id::MacroUserIdStr;
+
+use crate::domain::error::Result;
+use crate::domain::model::{ProvisionedEgress, SandboxEgress};
+use crate::domain::ports::SandboxEgressProvisioner;
+
+/// A [`SandboxEgressProvisioner`] that records who it was asked for and hands
+/// back a fixed environment. Cloning shares one record.
+#[derive(Clone, Default)]
+pub struct EgressProvisionerMock {
+ provisioned: Arc<Mutex<Vec<(AgentSessionId, String, String)>>>,
+}
+
+impl EgressProvisionerMock {
+ /// A provisioner that has provisioned nothing.
+ #[must_use]
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// Every provisioning recorded, as session, owner, and repository URL.
+ #[must_use]
+ pub fn provisioned(&self) -> Vec<(AgentSessionId, String, String)> {
+ self.provisioned
+ .lock()
+ .expect("egress mock lock should not be poisoned")
+ .clone()
+ }
+}
+
+impl SandboxEgressProvisioner for EgressProvisionerMock {
+ async fn provision(
+ &self,
+ session: AgentSessionId,
+ owner: &MacroUserIdStr<'static>,
+ repo_url: &str,
+ ) -> Result<ProvisionedEgress> {
+ self.provisioned
+ .lock()
+ .expect("egress mock lock should not be poisoned")
+ .push((session, owner.to_string(), repo_url.to_owned()));
+
+ Ok(ProvisionedEgress {
+ sandbox: test_egress(),
+ session_token_hash: "test-token-hash".to_owned(),
+ })
+ }
+
+ async fn restore(
+ &self,
+ _owner: &MacroUserIdStr<'static>,
+ session_token: String,
+ ) -> Result<SandboxEgress> {
+ Ok(SandboxEgress {
+ session_token,
+ ..test_egress()
+ })
+ }
+}
+
+/// An egress environment for tests that only need one to exist.
+#[must_use]
+pub fn test_egress() -> SandboxEgress {
+ SandboxEgress {
+ base_url: "https://egress.test".to_owned(),
+ session_token: "test-session-token".to_owned(),
+ mcp_servers: Vec::new(),
+ }
+}
diff --git a/crates/agent_harness/src/testing/helpers/mod.rs b/crates/agent_harness/src/testing/helpers/mod.rs
index 98e0c96657..5d5e6bddc8 100644
--- a/crates/agent_harness/src/testing/helpers/mod.rs
+++ b/crates/agent_harness/src/testing/helpers/mod.rs
@@ -3,3 +3,4 @@
pub mod agent;
pub mod announcer;
pub mod containers;
+pub mod egress;
diff --git a/crates/agent_inmem/src/outbound/manager/test.rs b/crates/agent_inmem/src/outbound/manager/test.rs
index 5785ad9cd2..4358ace7d4 100644
--- a/crates/agent_inmem/src/outbound/manager/test.rs
+++ b/crates/agent_inmem/src/outbound/manager/test.rs
@@ -85,6 +85,7 @@ async fn a_prompt_runs_end_to_end_through_the_real_session_machine() {
repo_url: None,
workspace: "/workspace".to_owned(),
sandbox_size: agent_session::domain::model::SandboxSize::Default,
+ egress_token_hash: None,
})
.await
.expect("the session row should create");
@@ -217,6 +218,7 @@ async fn a_restarted_manager_rebuilds_the_conversation_from_the_log() {
repo_url: None,
workspace: "/workspace".to_owned(),
sandbox_size: agent_session::domain::model::SandboxSize::Default,
+ egress_token_hash: None,
})
.await
.expect("the session row should create");
diff --git a/crates/agent_session/src/bin/seed_jsonl.rs b/crates/agent_session/src/bin/seed_jsonl.rs
index 5681aa51b4..f2a835717b 100644
--- a/crates/agent_session/src/bin/seed_jsonl.rs
+++ b/crates/agent_session/src/bin/seed_jsonl.rs
@@ -249,6 +249,7 @@ async fn seed(args: &Args) -> Result<(), SeedError> {
repo_url: Some(args.repo_url.clone()),
workspace: args.workspace.clone(),
sandbox_size: agent_session::domain::model::SandboxSize::Default,
+ egress_token_hash: None,
},
)
.await
diff --git a/crates/agent_session/src/domain/connection.rs b/crates/agent_session/src/domain/connection.rs
index a91e20354f..11c82402c6 100644
--- a/crates/agent_session/src/domain/connection.rs
+++ b/crates/agent_session/src/domain/connection.rs
@@ -23,7 +23,7 @@ use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, OnceLock};
use agent_client_protocol::RawJsonRpcMessage;
-use agent_client_protocol::schema::v1::{RequestId, Response, SessionId};
+use agent_client_protocol::schema::v1::{McpServer, RequestId, Response, SessionId};
use agent_runtime_protocol::domain::ports::{
Transport, TransportError, TransportReceiver, TransportSender,
};
@@ -136,6 +136,14 @@ fn acp_session_of(frame: &RawJsonRpcMessage) -> Option<SessionId> {
pub struct RuntimeAttachment<Connector> {
pub(crate) connector: Connector,
pub(crate) handshake: watch::Sender<HandshakeStatus>,
+ /// MCP servers the agent is told to connect to when this attachment's
+ /// session is established (`session/new`, `session/load`,
+ /// `session/resume`).
+ ///
+ /// Per attachment rather than per session row because it is computed
+ /// fresh at each attach - the set follows what the owner has connected
+ /// *now*, not what they had connected when the session was created.
+ pub(crate) mcp_servers: Vec<McpServer>,
}
impl<Connector> RuntimeAttachment<Connector> {
@@ -148,8 +156,17 @@ impl<Connector> RuntimeAttachment<Connector> {
Self {
connector,
handshake,
+ mcp_servers: Vec::new(),
}
}
+
+ /// The MCP servers the agent is handed when this attachment's session is
+ /// established.
+ #[must_use]
+ pub fn mcp_servers(mut self, mcp_servers: Vec<McpServer>) -> Self {
+ self.mcp_servers = mcp_servers;
+ self
+ }
}
/// Every session this connection carries, and where to reach it.
@@ -268,6 +285,9 @@ where
frames,
},
handshake: self.handshake.clone(),
+ // External runtimes hold no egress environment; the sessions
+ // they serve are not handed proxied MCP servers.
+ mcp_servers: Vec::new(),
}
}
diff --git a/crates/agent_session/src/domain/model.rs b/crates/agent_session/src/domain/model.rs
index 7dbfaf1bf3..4750e23a89 100644
--- a/crates/agent_session/src/domain/model.rs
+++ b/crates/agent_session/src/domain/model.rs
@@ -56,6 +56,14 @@ pub struct CreateAgentSessionParams {
pub workspace: String,
/// Compute tier the managed sandbox was spawned with.
pub sandbox_size: SandboxSize,
+ /// SHA-256 hex of the opaque token the session's sandbox presents to the
+ /// egress proxy, or `None` for a session that never gets one.
+ ///
+ /// The hash and never the token: this row is the only durable record of
+ /// the credential, and a database dump must not yield a live one. A session
+ /// replayed from a recording, or created without a sandbox, has nothing to
+ /// store here.
+ pub egress_token_hash: Option<String>,
}
/// A running or historical agent coding session.
diff --git a/crates/agent_session/src/domain/ports.rs b/crates/agent_session/src/domain/ports.rs
index aab9e97047..115d6788d6 100644
--- a/crates/agent_session/src/domain/ports.rs
+++ b/crates/agent_session/src/domain/ports.rs
@@ -142,6 +142,23 @@ pub trait AgentSessionRepo: Send + Sync + 'static {
/// Get an agent session by id.
fn get(&self, id: AgentSessionId) -> impl Future<Output = Result<AgentSession>> + Send;
+ /// The session a sandbox's egress token stands for, if any still does.
+ ///
+ /// `egress_token_hash` is the SHA-256 hex of the token as presented, never
+ /// the token: implementations match on the stored hash, so the comparison
+ /// happens in an index rather than over secret-derived bytes in memory.
+ ///
+ /// `None` rather than an error when nothing matches - a token we never
+ /// minted and a token whose session has since been deleted are the same
+ /// fact, and the caller refuses both the same way. The whole session comes
+ /// back because everything the token entitles its holder to is on the row:
+ /// the owner whose credentials it spends, the repository its git traffic is
+ /// pinned to, and whether the session is still open.
+ fn find_by_egress_token_hash(
+ &self,
+ egress_token_hash: &str,
+ ) -> impl Future<Output = Result<Option<AgentSession>>> + Send;
+
/// Find the session associated with an incoming channel context.
///
/// Matches only when `thread_id` and `bot_id` are both given and a session
diff --git a/crates/agent_session/src/domain/service.rs b/crates/agent_session/src/domain/service.rs
index 2092348322..00e8132b6a 100644
--- a/crates/agent_session/src/domain/service.rs
+++ b/crates/agent_session/src/domain/service.rs
@@ -354,6 +354,7 @@ impl<R, Folds, Rt, Namer> AgentSessionServiceImpl<R, Folds, Rt, Namer> {
id,
session.acp_session_id,
session.workspace,
+ attachment.mcp_servers,
attachment.connector,
logs,
command_rx,
@@ -845,6 +846,13 @@ where
self.repo.get(id).await
}
+ async fn find_by_egress_token_hash(
+ &self,
+ egress_token_hash: &str,
+ ) -> Result<Option<AgentSession>> {
+ self.repo.find_by_egress_token_hash(egress_token_hash).await
+ }
+
async fn session_bot(
&self,
id: bots::domain::models::BotId,
diff --git a/crates/agent_session/src/domain/service/test.rs b/crates/agent_session/src/domain/service/test.rs
index 04b458c263..bc45b57572 100644
--- a/crates/agent_session/src/domain/service/test.rs
+++ b/crates/agent_session/src/domain/service/test.rs
@@ -340,6 +340,13 @@ impl AgentSessionRepo for BlockingPromptLogs {
self.repo.session_bot(id).await
}
+ async fn find_by_egress_token_hash(
+ &self,
+ egress_token_hash: &str,
+ ) -> Result<Option<AgentSession>> {
+ self.repo.find_by_egress_token_hash(egress_token_hash).await
+ }
+
async fn find_for_channel(
&self,
thread_id: Option<Uuid>,
@@ -633,6 +640,7 @@ async fn cancellation_does_not_drop_an_effect_batch_after_machine_mutation() {
session,
None,
"/workspace".to_owned(),
+ Vec::new(),
RecordingTransport {
outbound: outbound_tx,
inbound: inbound_rx,
@@ -706,6 +714,7 @@ async fn live_inbound_logs_do_not_reuse_the_expired_handshake_deadline() {
session,
None,
"/workspace".to_owned(),
+ Vec::new(),
RecordingTransport {
outbound: outbound_tx,
inbound: inbound_rx,
diff --git a/crates/agent_session/src/domain/session/actors.rs b/crates/agent_session/src/domain/session/actors.rs
index d199785f16..084de131c0 100644
--- a/crates/agent_session/src/domain/session/actors.rs
+++ b/crates/agent_session/src/domain/session/actors.rs
@@ -15,7 +15,7 @@
use std::{collections::VecDeque, time::Duration};
use agent_client_protocol::RawJsonRpcMessage;
-use agent_client_protocol::schema::v1::SessionId;
+use agent_client_protocol::schema::v1::{McpServer, SessionId};
use agent_runtime_protocol::domain::action::{AgentAction, AgentActionId};
use agent_runtime_protocol::domain::schema::v0::{
AcpMessage, SystemEvent, ToRuntimeMessage, ToServerMessage,
@@ -88,10 +88,14 @@ where
Connector: AgentConnector,
Logs: AgentSessionLogWriter + AgentSessionRepo,
{
+ // One argument per fact the actor owns; a struct here would only move the
+ // same list one level down.
+ #[allow(clippy::too_many_arguments)]
pub(crate) fn new(
id: AgentSessionId,
acp_session_id: Option<SessionId>,
workspace: String,
+ mcp_servers: Vec<McpServer>,
connector: Connector,
logs: Logs,
commands: mpsc::Receiver<SessionCommand>,
@@ -117,8 +121,8 @@ where
handshake_seen,
handshake,
machine: match acp_session_id {
- None => SessionMachine::new(id, workspace),
- Some(session_id) => SessionMachine::resume(id, session_id, workspace),
+ None => SessionMachine::new(id, workspace, mcp_servers),
+ Some(session_id) => SessionMachine::resume(id, session_id, workspace, mcp_servers),
},
logs,
commands,
diff --git a/crates/agent_session/src/domain/session/session.rs b/crates/agent_session/src/domain/session/session.rs
index fb556f4fd5..ad6a29e374 100644
--- a/crates/agent_session/src/domain/session/session.rs
+++ b/crates/agent_session/src/domain/session/session.rs
@@ -3,7 +3,7 @@
use std::collections::VecDeque;
use agent_client_protocol::schema::v1::{
- InitializeRequest, InitializeResponse, LoadSessionRequest, LoadSessionResponse,
+ InitializeRequest, InitializeResponse, LoadSessionRequest, LoadSessionResponse, McpServer,
NewSessionRequest, NewSessionResponse, PermissionOptionKind, RequestId,
RequestPermissionOutcome, RequestPermissionRequest, RequestPermissionResponse, Response,
ResumeSessionRequest, ResumeSessionResponse, SelectedPermissionOutcome, SessionId,
@@ -41,11 +41,15 @@ pub struct SessionMachine<Token> {
/// carry it, so a reconnect re-enters the directory the session
/// actually ran in.
workspace: String,
+ /// MCP servers the agent is told to connect to. Carried by `session/new`,
+ /// `session/resume`, and `session/load` alike, because the agent process
+ /// behind a reconnect is fresh and holds no server from before.
+ mcp_servers: Vec<McpServer>,
}
impl<Token> SessionMachine<Token> {
/// A fresh connection for `id`: booting, nothing queued.
- pub fn new(id: AgentSessionId, workspace: String) -> Self {
+ pub fn new(id: AgentSessionId, workspace: String, mcp_servers: Vec<McpServer>) -> Self {
Self {
id,
phase: SessionPhase::Booting,
@@ -53,11 +57,17 @@ impl<Token> SessionMachine<Token> {
pending: VecDeque::new(),
resume_session_id: None,
workspace,
+ mcp_servers,
}
}
/// A fresh connection that must restore an existing ACP session.
- pub fn resume(id: AgentSessionId, session_id: SessionId, workspace: String) -> Self {
+ pub fn resume(
+ id: AgentSessionId,
+ session_id: SessionId,
+ workspace: String,
+ mcp_servers: Vec<McpServer>,
+ ) -> Self {
Self {
id,
phase: SessionPhase::Booting,
@@ -65,6 +75,7 @@ impl<Token> SessionMachine<Token> {
pending: VecDeque::new(),
resume_session_id: Some(session_id),
workspace,
+ mcp_servers,
}
}
@@ -374,7 +385,8 @@ impl<Token> SessionMachine<Token> {
agent_client_protocol::Error,
> {
self.build_session_request(
- ResumeSessionRequest::new(session_id.clone(), self.workspace.clone()),
+ ResumeSessionRequest::new(session_id.clone(), self.workspace.clone())
+ .mcp_servers(self.mcp_servers.clone()),
SessionOpening::Resume(session_id),
)
}
@@ -387,7 +399,8 @@ impl<Token> SessionMachine<Token> {
agent_client_protocol::Error,
> {
self.build_session_request(
- LoadSessionRequest::new(session_id.clone(), self.workspace.clone()),
+ LoadSessionRequest::new(session_id.clone(), self.workspace.clone())
+ .mcp_servers(self.mcp_servers.clone()),
SessionOpening::Load(session_id),
)
}
@@ -410,7 +423,7 @@ impl<Token> SessionMachine<Token> {
agent_client_protocol::Error,
> {
self.build_session_request(
- NewSessionRequest::new(self.workspace.clone()),
+ NewSessionRequest::new(self.workspace.clone()).mcp_servers(self.mcp_servers.clone()),
SessionOpening::New,
)
}
diff --git a/crates/agent_session/src/domain/session/tests.rs b/crates/agent_session/src/domain/session/tests.rs
index 0a28dc0546..a922a51e0d 100644
--- a/crates/agent_session/src/domain/session/tests.rs
+++ b/crates/agent_session/src/domain/session/tests.rs
@@ -23,7 +23,7 @@ use super::{
};
fn machine() -> SessionMachine<u32> {
- SessionMachine::new(AgentSessionId::TEST_A, "/workspace".to_owned())
+ SessionMachine::new(AgentSessionId::TEST_A, "/workspace".to_owned(), Vec::new())
}
fn command(text: &str, token: u32) -> Input<u32> {
@@ -238,6 +238,7 @@ fn reconnect_uses_session_resume_when_the_agent_supports_it() {
AgentSessionId::TEST_A,
"acp-42".into(),
"/workspace".to_owned(),
+ Vec::new(),
);
machine.handle(command("continue", 1));
machine.handle(acp_ready());
@@ -274,6 +275,7 @@ fn reconnect_falls_back_to_session_load() {
AgentSessionId::TEST_A,
"acp-42".into(),
"/workspace".to_owned(),
+ Vec::new(),
);
machine.handle(acp_ready());
let initialized = InitializeResponse::new(PROTOCOL_VERSION)
@@ -290,6 +292,7 @@ fn reconnect_stops_when_the_agent_cannot_restore_sessions() {
AgentSessionId::TEST_A,
"acp-42".into(),
"/workspace".to_owned(),
+ Vec::new(),
);
machine.handle(command("cannot continue", 1));
machine.handle(acp_ready());
@@ -708,7 +711,11 @@ fn sent_cwds(effects: &[Effect<u32>], method: &str) -> Vec<String> {
#[test]
fn session_new_carries_the_sessions_workspace() {
- let mut machine = SessionMachine::new(AgentSessionId::TEST_A, "/home/operator/code".to_owned());
+ let mut machine = SessionMachine::new(
+ AgentSessionId::TEST_A,
+ "/home/operator/code".to_owned(),
+ Vec::new(),
+ );
machine.handle(acp_ready());
let effects = machine.handle(initialized());
@@ -722,6 +729,7 @@ fn resume_carries_the_sessions_workspace() {
AgentSessionId::TEST_A,
"acp-42".into(),
"/home/operator/code".to_owned(),
+ Vec::new(),
);
machine.handle(acp_ready());
let effects = machine.handle(initialized_with(
@@ -766,6 +774,7 @@ fn a_ready_connection_still_picks_resume_for_a_session_that_has_one() {
AgentSessionId::TEST_A,
"acp-42".into(),
"/workspace".to_owned(),
+ Vec::new(),
);
let opening = machine.handle(Input::Ready {
@@ -784,6 +793,7 @@ fn a_ready_connection_that_cannot_restore_stops_the_session() {
AgentSessionId::TEST_A,
"acp-42".into(),
"/workspace".to_owned(),
+ Vec::new(),
);
let effects = machine.handle(Input::Ready {
diff --git a/crates/agent_session/src/outbound/postgres.rs b/crates/agent_session/src/outbound/postgres.rs
index 10014a1fbf..ac667e1df5 100644
--- a/crates/agent_session/src/outbound/postgres.rs
+++ b/crates/agent_session/src/outbound/postgres.rs
@@ -166,6 +166,7 @@ impl AgentSessionRepo for PgAgentSessionRepo {
repo_url,
workspace,
sandbox_size,
+ egress_token_hash,
} = params;
// The session row and its access grants land together: a crash between
@@ -184,9 +185,9 @@ impl AgentSessionRepo for PgAgentSessionRepo {
INSERT INTO agent_session (
id, owner_id, thread_id, originating_message_id, bot_id, model,
harness, repo_url, workspace, sandbox_size, acp_session_id, status,
- status_event_name
+ status_event_name, egress_token_hash
)
- VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+ VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)
RETURNING
id, name, owner_id, thread_id, originating_message_id, bot_id,
model, harness, repo_url, workspace, sandbox_size, acp_session_id, status,
@@ -210,6 +211,7 @@ impl AgentSessionRepo for PgAgentSessionRepo {
None::<String>,
status,
status_event_name,
+ egress_token_hash,
)
.fetch_one(&mut *transaction)
.await
@@ -297,6 +299,40 @@ impl AgentSessionRepo for PgAgentSessionRepo {
Ok(row.try_into()?)
}
+ async fn find_by_egress_token_hash(
+ &self,
+ egress_token_hash: &str,
+ ) -> Result<Option<AgentSession>> {
+ // Matched in SQL rather than fetched and compared: the unique partial
+ // index on this column does the work, and nothing secret-derived is
+ // compared byte by byte in this process.
+ let row = sqlx::query_as!(
+ AgentSessionRow,
+ r#"
+ SELECT
+ id, name, owner_id, thread_id, originating_message_id, bot_id,
+ model, harness, repo_url, workspace, sandbox_size, acp_session_id, status,
+ status_event_name, agent_session.created_at, modified_at,
+ (SELECT channel_id FROM comms_messages WHERE id = agent_session.thread_id)
+ AS "thread_channel_id?",
+ ext.provider AS "external_provider?", ext.external_id AS "external_id?",
+ ext.external_name AS "external_name?", ext.external_url AS "external_url?"
+ FROM agent_session
+ LEFT JOIN external_agent_session AS ext ON ext.agent_session_id = agent_session.id
+ WHERE egress_token_hash = $1
+ "#,
+ egress_token_hash,
+ )
+ .fetch_optional(&self.pool)
+ .await
+ .context("failed to find agent session by egress token hash")?;
+
+ Ok(match row {
+ Some(row) => Some(row.try_into()?),
+ None => None,
+ })
+ }
+
async fn find_for_channel(
&self,
thread_id: Option<Uuid>,
diff --git a/crates/agent_session/src/outbound/postgres/test.rs b/crates/agent_session/src/outbound/postgres/test.rs
index cdca706523..dfe843a39f 100644
--- a/crates/agent_session/src/outbound/postgres/test.rs
+++ b/crates/agent_session/src/outbound/postgres/test.rs
@@ -93,6 +93,7 @@ fn new_session(
repo_url: Some("https://github.com/example/example".to_string()),
workspace: "/workspace".to_string(),
sandbox_size: SandboxSize::Default,
+ egress_token_hash: None,
}
}
diff --git a/crates/agent_session/src/testing.rs b/crates/agent_session/src/testing.rs
index 9f27996f54..b31ef4c08a 100644
--- a/crates/agent_session/src/testing.rs
+++ b/crates/agent_session/src/testing.rs
@@ -29,6 +29,9 @@ use std::sync::{Arc, Mutex};
#[derive(Debug, Clone, Default)]
pub struct InMemoryAgentSessionRepo {
sessions: Arc<Mutex<HashMap<AgentSessionId, AgentSession>>>,
+ /// Egress token hash -> the session it was stored against, mirroring the
+ /// unique partial index the real table carries.
+ egress_token_hashes: Arc<Mutex<HashMap<String, AgentSessionId>>>,
logs: Arc<Mutex<HashMap<AgentSessionId, Vec<StoredAgentSessionLog>>>>,
user_sizes: Arc<Mutex<HashMap<String, SandboxSize>>>,
log_reads: Arc<AtomicUsize>,
@@ -121,10 +124,35 @@ impl AgentSessionRepo for InMemoryAgentSessionRepo {
created_at: now,
modified_at: now,
};
+ if let Some(hash) = params.egress_token_hash {
+ self.egress_token_hashes
+ .lock()
+ .expect("in-memory session store is not poisoned")
+ .insert(hash, session.id);
+ }
self.insert_session(session.clone());
Ok(session)
}
+ async fn find_by_egress_token_hash(
+ &self,
+ egress_token_hash: &str,
+ ) -> Result<Option<AgentSession>> {
+ let id = self
+ .egress_token_hashes
+ .lock()
+ .expect("in-memory session store is not poisoned")
+ .get(egress_token_hash)
+ .copied();
+ Ok(id.and_then(|id| {
+ self.sessions
+ .lock()
+ .expect("in-memory session store is not poisoned")
+ .get(&id)
+ .cloned()
+ }))
+ }
+
async fn get(&self, id: AgentSessionId) -> Result<AgentSession> {
self.session_reads.fetch_add(1, Ordering::Relaxed);
self.sessions
diff --git a/crates/github/src/domain/models.rs b/crates/github/src/domain/models.rs
index d7e18a4028..1a7efcfdd7 100644
--- a/crates/github/src/domain/models.rs
+++ b/crates/github/src/domain/models.rs
@@ -3,11 +3,14 @@
#[cfg(test)]
mod test;
+mod app_jwt;
mod installation_state;
mod link;
mod pull_request;
mod sync;
+pub use app_jwt::AppJwt;
+pub(crate) use app_jwt::app_jwt;
pub use installation_state::{
InstallationState, InstallationStateError, sign_installation_state, verify_installation_state,
};
@@ -61,4 +64,13 @@ pub enum GithubError {
/// setup state was minted for.
#[error("GitHub account is not linked to the Macro user who started setup")]
SetupUserNotLinked,
+ /// Our App has no installation covering the requested repository, or the
+ /// installation it has belongs to neither the requesting user nor any team
+ /// they are on.
+ ///
+ /// One variant for both because a caller must not be able to tell them
+ /// apart: "installed, but not yours" and "not installed" differ only in
+ /// what they report about other people's accounts.
+ #[error("no GitHub App installation for this user and repository")]
+ RepositoryUnavailable,
}
diff --git a/crates/github/src/domain/models/app_jwt.rs b/crates/github/src/domain/models/app_jwt.rs
new file mode 100644
index 0000000000..f83583af7d
--- /dev/null
+++ b/crates/github/src/domain/models/app_jwt.rs
@@ -0,0 +1,74 @@
+use super::GithubError;
+use jsonwebtoken::{Algorithm, EncodingKey, Header};
+
+#[cfg(test)]
+mod test;
+
+/// How long an App JWT stays valid. GitHub rejects anything over ten minutes.
+const LIFETIME_SECONDS: i64 = 10 * 60;
+
+/// How far the issued-at time is backdated, so a small clock skew between us
+/// and GitHub cannot make a freshly signed token look future-dated.
+const BACKDATE_SECONDS: i64 = 60;
+
+/// The claims GitHub reads off an App JWT. It ignores anything else, and
+/// rejects the token outright if these three are wrong.
+#[derive(serde::Serialize)]
+struct AppClaims<'a> {
+ /// Issued at, in seconds since the epoch.
+ iat: i64,
+ /// Expires at, in seconds since the epoch.
+ exp: i64,
+ /// The App's client id.
+ iss: &'a str,
+}
+
+/// A signed, short-lived proof that we are the GitHub App.
+///
+/// A newtype rather than a `String` because the sync client's port also
+/// passes user OAuth access tokens as strings, in the same argument
+/// position - and an App JWT handed to a user endpoint (or the reverse)
+/// compiles fine and fails only at GitHub, confusingly. The type makes the
+/// two credentials unmixable.
+pub struct AppJwt(String);
+
+impl AppJwt {
+ /// The JWT as GitHub accepts it in a bearer header.
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+// A credential that can mint tokens for every installation; it stays out of
+// debug output.
+impl std::fmt::Debug for AppJwt {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ formatter.write_str("AppJwt([REDACTED])")
+ }
+}
+
+/// Sign a short-lived JWT proving we are the GitHub App.
+///
+/// This is the first half of every App-authenticated exchange: GitHub trades
+/// this JWT for something narrower - an installation access token, or the
+/// installation record for a repository - and only ever accepts it directly on
+/// the `/app/...` endpoints.
+///
+/// `iss` is the App's *client id* rather than its numeric App id, which is what
+/// GitHub now documents. Both are accepted today, but the numeric form is the
+/// legacy one.
+pub fn app_jwt(client_id: &str, private_key_pem: &str) -> Result<AppJwt, GithubError> {
+ let now = chrono::Utc::now().timestamp();
+ let claims = AppClaims {
+ iat: now - BACKDATE_SECONDS,
+ exp: now + LIFETIME_SECONDS,
+ iss: client_id,
+ };
+
+ let key = EncodingKey::from_rsa_pem(private_key_pem.as_bytes())
+ .map_err(|error| GithubError::Internal(anyhow::anyhow!("invalid PEM key: {error}")))?;
+
+ jsonwebtoken::encode(&Header::new(Algorithm::RS256), &claims, &key)
+ .map(AppJwt)
+ .map_err(|error| GithubError::Internal(anyhow::anyhow!("failed to encode JWT: {error}")))
+}
diff --git a/crates/github/src/domain/models/app_jwt/test.rs b/crates/github/src/domain/models/app_jwt/test.rs
new file mode 100644
index 0000000000..1321a29f0d
--- /dev/null
+++ b/crates/github/src/domain/models/app_jwt/test.rs
@@ -0,0 +1,11 @@
+use super::*;
+
+/// The happy path is covered by the sync service's tests, which sign with a
+/// real test key. What is worth pinning here is that an unusable key fails
+/// loudly rather than producing a token GitHub will silently reject.
+#[test]
+fn an_unusable_key_is_an_error() {
+ let error = app_jwt("Iv1.client", "not a pem").expect_err("refused");
+
+ assert!(matches!(error, GithubError::Internal(_)));
+}
diff --git a/crates/github/src/domain/models/sync.rs b/crates/github/src/domain/models/sync.rs
index 4598ac76a1..b848bb8262 100644
--- a/crates/github/src/domain/models/sync.rs
+++ b/crates/github/src/domain/models/sync.rs
@@ -98,14 +98,42 @@ pub struct GithubUserInstallationsPage {
}
/// GitHub App installation access token response
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Clone, Deserialize)]
pub struct GithubInstallationAccessToken {
/// The installation access token
pub token: String,
- /// When the token expires
+ /// When the token expires, as GitHub sent it (RFC 3339).
pub expires_at: String,
}
+impl std::fmt::Debug for GithubInstallationAccessToken {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("GithubInstallationAccessToken")
+ .field("token", &"[REDACTED]")
+ .field("expires_at", &self.expires_at)
+ .finish()
+ }
+}
+
+impl GithubInstallationAccessToken {
+ /// When this token expires.
+ ///
+ /// Parsed here rather than by callers: the field is a string because that
+ /// is how GitHub sends it, and a caller that has to know the format in
+ /// order to cache the token would be the second place that knowledge
+ /// lives.
+ pub fn expires_at(&self) -> Result<chrono::DateTime<chrono::Utc>, GithubError> {
+ chrono::DateTime::parse_from_rfc3339(&self.expires_at)
+ .map(|expiry| expiry.with_timezone(&chrono::Utc))
+ .map_err(|error| {
+ GithubError::Internal(anyhow::anyhow!(
+ "github sent an unparseable token expiry {:?}: {error}",
+ self.expires_at
+ ))
+ })
+ }
+}
+
/// Source that grants a GitHub App installation access to Macro sync data.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum GithubAppInstallationSource {
diff --git a/crates/github/src/domain/ports/sync.rs b/crates/github/src/domain/ports/sync.rs
index c91e4d18fd..0cd5ebccba 100644
--- a/crates/github/src/domain/ports/sync.rs
+++ b/crates/github/src/domain/ports/sync.rs
@@ -5,10 +5,10 @@ use std::future::Future;
use macro_user_id::user_id::MacroUserIdStr;
use crate::domain::models::{
- EnrichedGithubPullRequest, GithubAppInstallationSource, GithubAuthenticatedUser, GithubError,
- GithubInstallationAccessToken, GithubKey, GithubPullRequestDetails, GithubSetupAccessToken,
- GithubUserInstallation, MacroTaskId, ResolvedTeamTaskReference, TeamTaskReference,
- ValidatedGithubWebhookEvent,
+ AppJwt, EnrichedGithubPullRequest, GithubAppInstallationSource, GithubAuthenticatedUser,
+ GithubError, GithubInstallationAccessToken, GithubKey, GithubPullRequestDetails,
+ GithubSetupAccessToken, GithubUserInstallation, MacroTaskId, ResolvedTeamTaskReference,
+ TeamTaskReference, ValidatedGithubWebhookEvent,
};
/// Repository for accessing github sync data from the database.
@@ -160,10 +160,37 @@ pub trait GithubSyncClient: Send + Sync + 'static {
/// Generates an installation access token for a given GitHub App installation.
fn generate_installation_access_token(
&self,
- jwt: &str,
+ jwt: &AppJwt,
installation_id: u64,
) -> impl Future<Output = Result<GithubInstallationAccessToken, GithubError>> + Send;
+ /// Finds which installation of our App covers a repository, if any.
+ ///
+ /// `None` means the App is not installed on it - which, from a caller
+ /// acting for a user, is indistinguishable from a repository that does not
+ /// exist, and deliberately so.
+ fn get_repository_installation(
+ &self,
+ jwt: &AppJwt,
+ owner: &str,
+ repository: &str,
+ ) -> impl Future<Output = Result<Option<u64>, GithubError>> + Send;
+
+ /// Generates an installation access token cut down to one repository and a
+ /// named set of permissions.
+ ///
+ /// An unscoped installation token reaches every repository in the
+ /// installation with every permission it was granted; this is the narrow
+ /// form, for callers acting on one repository's behalf. `permissions` are
+ /// GitHub's own names and levels, e.g. `("contents", "write")`.
+ fn generate_scoped_installation_access_token(
+ &self,
+ jwt: &AppJwt,
+ installation_id: u64,
+ repository: &str,
+ permissions: &[(&str, &str)],
+ ) -> impl Future<Output = Result<GithubInstallationAccessToken, GithubError>> + Send;
+
/// Posts a comment on a GitHub pull request (via the issues API).
fn create_pr_comment(
&self,
diff --git a/crates/github/src/domain/service/installation_tokens.rs b/crates/github/src/domain/service/installation_tokens.rs
new file mode 100644
index 0000000000..b65a202a1d
--- /dev/null
+++ b/crates/github/src/domain/service/installation_tokens.rs
@@ -0,0 +1,145 @@
+//! Minting installation access tokens scoped to one repository, on a user's
+//! behalf.
+//!
+//! Four steps, and the third is the one that matters:
+//!
+//! 1. sign a JWT proving we are the App
+//! 2. find which installation of the App covers the repository
+//! 3. check that installation belongs to the user, or to a team they are on
+//! 4. mint a token cut down to that repository and the asked-for permissions
+//!
+//! Step 3 is not optional. Our App is installed across many accounts and its
+//! JWT can mint a token for any of them, so without it a caller could name any
+//! repository we can reach and be handed access to it. Step 4 is defence in
+//! depth on top: an unscoped installation token covers every repository in the
+//! installation, which is more than any single caller needs.
+//!
+//! This is deliberately its own service rather than a method on
+//! [`GithubSyncServiceImpl`](super::GithubSyncServiceImpl). That type needs a
+//! document service, a foreign-entity service and a notification ingress;
+//! minting a token needs a database handle and an HTTP client, and a caller
+//! that only wants a token should not have to construct the rest.
+
+use macro_user_id::user_id::MacroUserIdStr;
+
+use crate::domain::models::{
+ GithubAppInstallationSource, GithubError, GithubInstallationAccessToken, app_jwt,
+};
+use crate::domain::ports::{GithubSyncClient, GithubSyncRepo};
+
+#[cfg(test)]
+mod test;
+
+/// The GitHub App tokens are minted for.
+pub struct InstallationTokenConfig {
+ /// The App's client id, which GitHub wants as the JWT's `iss`.
+ pub client_id: String,
+ /// The App's RSA private key, PEM-encoded.
+ pub private_key_pem: String,
+}
+
+/// Mints repository-scoped installation access tokens.
+pub struct InstallationTokenService<Installations, Client> {
+ config: InstallationTokenConfig,
+ installations: Installations,
+ client: Client,
+}
+
+impl<Installations, Client> InstallationTokenService<Installations, Client>
+where
+ Installations: GithubSyncRepo,
+ Client: GithubSyncClient,
+{
+ /// Build the service over the App's credentials, the installation records
+ /// that say who owns which installation, and a GitHub client.
+ pub fn new(
+ config: InstallationTokenConfig,
+ installations: Installations,
+ client: Client,
+ ) -> Self {
+ Self {
+ config,
+ installations,
+ client,
+ }
+ }
+
+ /// A token for `owner`/`repository`, valid because `macro_user_id` may
+ /// reach it.
+ ///
+ /// Returns [`GithubError::RepositoryUnavailable`] when the App is not
+ /// installed on the repository *or* when the installation belongs to
+ /// someone the user has no claim to - one answer for both, so the caller
+ /// learns nothing about other people's accounts.
+ #[tracing::instrument(skip(self, permissions), err, fields(%macro_user_id, owner, repository))]
+ pub async fn for_repository(
+ &self,
+ macro_user_id: &MacroUserIdStr<'_>,
+ owner: &str,
+ repository: &str,
+ permissions: &[(&str, &str)],
+ ) -> Result<GithubInstallationAccessToken, GithubError> {
+ let jwt = app_jwt(&self.config.client_id, &self.config.private_key_pem)?;
+
+ let installation = self
+ .client
+ .get_repository_installation(&jwt, owner, repository)
+ .await?
+ .ok_or_else(|| {
+ tracing::warn!(owner, repository, "app is not installed on the repository");
+ GithubError::RepositoryUnavailable
+ })?;
+
+ self.ensure_reachable(macro_user_id, installation).await?;
+
+ self.client
+ .generate_scoped_installation_access_token(&jwt, installation, repository, permissions)
+ .await
+ }
+
+ /// Confirm `installation` was installed by this user or by a team they
+ /// belong to.
+ async fn ensure_reachable(
+ &self,
+ macro_user_id: &MacroUserIdStr<'_>,
+ installation: u64,
+ ) -> Result<(), GithubError> {
+ let sources = self
+ .installations
+ .get_installation_sources(&installation.to_string())
+ .await
+ .map_err(|error| {
+ GithubError::Internal(anyhow::anyhow!(
+ "could not read installation sources: {error:?}"
+ ))
+ })?;
+
+ // Cheapest first: a personal installation needs no team lookup at all.
+ if sources.iter().any(|source| {
+ matches!(source, GithubAppInstallationSource::User(user) if user == macro_user_id.as_ref())
+ }) {
+ return Ok(());
+ }
+
+ let teams = self
+ .installations
+ .get_user_team_ids(macro_user_id.as_ref())
+ .await
+ .map_err(|error| {
+ GithubError::Internal(anyhow::anyhow!("could not read user teams: {error:?}"))
+ })?;
+
+ if sources.iter().any(|source| {
+ matches!(source, GithubAppInstallationSource::Team(team) if teams.contains(team))
+ }) {
+ return Ok(());
+ }
+
+ tracing::warn!(
+ %macro_user_id,
+ installation,
+ "refused an installation the user has no claim to"
+ );
+ Err(GithubError::RepositoryUnavailable)
+ }
+}
diff --git a/crates/github/src/domain/service/installation_tokens/test.rs b/crates/github/src/domain/service/installation_tokens/test.rs
new file mode 100644
index 0000000000..8948a9ab15
--- /dev/null
+++ b/crates/github/src/domain/service/installation_tokens/test.rs
@@ -0,0 +1,393 @@
+use super::*;
+use crate::domain::models::AppJwt;
+use crate::domain::models::{
+ EnrichedGithubPullRequest, GithubAuthenticatedUser, GithubKey, GithubPullRequestDetails,
+ GithubSetupAccessToken, GithubUserInstallation, MacroTaskId, ResolvedTeamTaskReference,
+ TeamTaskReference,
+};
+use std::collections::HashMap;
+use std::sync::Mutex;
+
+/// SAFETY: test-only key, matching the one the sync service's tests sign with.
+const TEST_PEM: &str = include_str!("test_key.pem");
+
+const INSTALLATION: u64 = 42;
+
+fn user() -> MacroUserIdStr<'static> {
+ MacroUserIdStr::try_from_email("[email protected]").expect("a valid user id")
+}
+
+fn config() -> InstallationTokenConfig {
+ InstallationTokenConfig {
+ client_id: "Iv1.testclient".to_owned(),
+ private_key_pem: TEST_PEM.to_owned(),
+ }
+}
+
+fn permissions() -> Vec<(&'static str, &'static str)> {
+ vec![("contents", "write")]
+}
+
+/// Answers the two lookups this service makes and refuses the rest: a call to
+/// anything else would mean the service reached further into the repository
+/// than minting a token needs.
+struct FakeRepo {
+ sources: Vec<GithubAppInstallationSource>,
+ teams: Vec<uuid::Uuid>,
+}
+
+impl GithubSyncRepo for FakeRepo {
+ type Err = anyhow::Error;
+
+ async fn get_installation_sources(
+ &self,
+ installation_id: &str,
+ ) -> Result<Vec<GithubAppInstallationSource>, Self::Err> {
+ assert_eq!(installation_id, INSTALLATION.to_string());
+ Ok(self.sources.clone())
+ }
+
+ async fn get_user_team_ids(&self, _macro_id: &str) -> Result<Vec<uuid::Uuid>, Self::Err> {
+ Ok(self.teams.clone())
+ }
+
+ async fn get_task_ids(&self, _github_key: GithubKey) -> Result<Vec<MacroTaskId>, Self::Err> {
+ unimplemented!("minting a token does not read tasks")
+ }
+
+ async fn upsert_task_ids(
+ &self,
+ _github_key: GithubKey,
+ _task_ids: &[MacroTaskId],
+ ) -> Result<(), Self::Err> {
+ unimplemented!("minting a token does not write tasks")
+ }
+
+ async fn filter_duplicate_tasks(
+ &self,
+ _github_key: GithubKey,
+ _task_ids: &[MacroTaskId],
+ ) -> Result<Vec<MacroTaskId>, Self::Err> {
+ unimplemented!("minting a token does not read tasks")
+ }
+
+ async fn resolve_team_task_references(
+ &self,
+ _installation_id: &str,
+ _references: &[TeamTaskReference],
+ ) -> Result<Vec<ResolvedTeamTaskReference>, Self::Err> {
+ unimplemented!("minting a token does not resolve task references")
+ }
+
+ async fn get_macro_ids_by_github_user_ids(
+ &self,
+ _github_user_ids: &[String],
+ ) -> Result<HashMap<String, Vec<String>>, Self::Err> {
+ unimplemented!("minting a token does not map github users")
+ }
+
+ async fn get_macro_ids_by_github_logins(
+ &self,
+ _github_logins: &[String],
+ ) -> Result<HashMap<String, Vec<String>>, Self::Err> {
+ unimplemented!("minting a token does not map github logins")
+ }
+
+ async fn get_team_member_ids(
+ &self,
+ _team_id: uuid::Uuid,
+ ) -> Result<Vec<MacroUserIdStr<'static>>, Self::Err> {
+ unimplemented!("minting a token does not list team members")
+ }
+
+ async fn upsert_installation_sources(
+ &self,
+ _installation_id: &str,
+ _sources: &[GithubAppInstallationSource],
+ ) -> Result<(), Self::Err> {
+ unimplemented!("minting a token does not change installations")
+ }
+
+ async fn delete_installation_sources(&self, _installation_id: &str) -> Result<(), Self::Err> {
+ unimplemented!("minting a token does not change installations")
+ }
+
+ async fn upsert_installation_request(
+ &self,
+ _github_user_id: &str,
+ _source: &GithubAppInstallationSource,
+ ) -> Result<(), Self::Err> {
+ unimplemented!("minting a token does not change installation requests")
+ }
+
+ async fn get_installation_request(
+ &self,
+ _github_user_id: &str,
+ ) -> Result<Option<GithubAppInstallationSource>, Self::Err> {
+ unimplemented!("minting a token does not read installation requests")
+ }
+
+ async fn delete_installation_request(&self, _github_user_id: &str) -> Result<(), Self::Err> {
+ unimplemented!("minting a token does not change installation requests")
+ }
+}
+
+/// Records what it was asked to mint, so a test can assert the scope.
+struct FakeClient {
+ installation: Option<u64>,
+ minted: Mutex<Vec<(u64, String, Vec<(String, String)>)>>,
+}
+
+impl FakeClient {
+ fn installed() -> Self {
+ Self {
+ installation: Some(INSTALLATION),
+ minted: Mutex::default(),
+ }
+ }
+
+ fn not_installed() -> Self {
+ Self {
+ installation: None,
+ minted: Mutex::default(),
+ }
+ }
+
+ fn mint_count(&self) -> usize {
+ self.minted.lock().expect("lock").len()
+ }
+}
+
+impl GithubSyncClient for FakeClient {
+ async fn get_repository_installation(
+ &self,
+ _jwt: &AppJwt,
+ _owner: &str,
+ _repository: &str,
+ ) -> Result<Option<u64>, GithubError> {
+ Ok(self.installation)
+ }
+
+ async fn generate_scoped_installation_access_token(
+ &self,
+ _jwt: &AppJwt,
+ installation_id: u64,
+ repository: &str,
+ permissions: &[(&str, &str)],
+ ) -> Result<GithubInstallationAccessToken, GithubError> {
+ self.minted.lock().expect("lock").push((
+ installation_id,
+ repository.to_owned(),
+ permissions
+ .iter()
+ .map(|(permission, level)| ((*permission).to_owned(), (*level).to_owned()))
+ .collect(),
+ ));
+
+ Ok(GithubInstallationAccessToken {
+ token: "ghs-scoped".to_owned(),
+ expires_at: "2099-01-01T00:00:00Z".to_owned(),
+ })
+ }
+
+ async fn exchange_setup_code(
+ &self,
+ _client_id: &str,
+ _client_secret: &str,
+ _code: &str,
+ ) -> Result<GithubSetupAccessToken, GithubError> {
+ unimplemented!("minting a token does not exchange setup codes")
+ }
+
+ async fn list_user_installations(
+ &self,
+ _access_token: &str,
+ ) -> Result<Vec<GithubUserInstallation>, GithubError> {
+ unimplemented!("ownership comes from our own records, not from GitHub")
+ }
+
+ async fn get_authenticated_user(
+ &self,
+ _access_token: &str,
+ ) -> Result<GithubAuthenticatedUser, GithubError> {
+ unimplemented!("minting a token does not need a github user")
+ }
+
+ async fn generate_installation_access_token(
+ &self,
+ _jwt: &AppJwt,
+ _installation_id: u64,
+ ) -> Result<GithubInstallationAccessToken, GithubError> {
+ unimplemented!("this service only ever mints scoped tokens")
+ }
+
+ async fn create_pr_comment(
+ &self,
+ _access_token: &str,
+ _owner: &str,
+ _repo: &str,
+ _pull_number: u64,
+ _body: &str,
+ ) -> Result<(), GithubError> {
+ unimplemented!("minting a token does not comment")
+ }
+
+ async fn get_pull_request_details(
+ &self,
+ _access_token: &str,
+ _owner: &str,
+ _repo: &str,
+ _number: u64,
+ ) -> Result<GithubPullRequestDetails, GithubError> {
+ unimplemented!("minting a token does not read pull requests")
+ }
+
+ async fn list_open_pull_requests(
+ &self,
+ _access_token: &str,
+ ) -> Result<Vec<EnrichedGithubPullRequest>, GithubError> {
+ unimplemented!("minting a token does not list pull requests")
+ }
+}
+
+fn service(
+ sources: Vec<GithubAppInstallationSource>,
+ teams: Vec<uuid::Uuid>,
+ client: FakeClient,
+) -> InstallationTokenService<FakeRepo, FakeClient> {
+ InstallationTokenService::new(config(), FakeRepo { sources, teams }, client)
+}
+
+#[tokio::test]
+async fn mints_for_an_installation_the_user_installed_themselves() {
+ let service = service(
+ vec![GithubAppInstallationSource::User(user().to_string())],
+ vec![],
+ FakeClient::installed(),
+ );
+
+ let token = service
+ .for_repository(&user(), "macro-inc", "macro", &permissions())
+ .await
+ .expect("minted");
+
+ assert_eq!(token.token, "ghs-scoped");
+}
+
+#[tokio::test]
+async fn mints_for_an_installation_owned_by_one_of_the_users_teams() {
+ let team = uuid::Uuid::from_u128(7);
+ let service = service(
+ vec![GithubAppInstallationSource::Team(team)],
+ vec![team],
+ FakeClient::installed(),
+ );
+
+ service
+ .for_repository(&user(), "macro-inc", "macro", &permissions())
+ .await
+ .expect("minted");
+}
+
+/// The check that stops any session minting a token for any repository our App
+/// happens to be installed on.
+#[tokio::test]
+async fn refuses_an_installation_belonging_to_someone_else() {
+ let service = service(
+ vec![GithubAppInstallationSource::Team(uuid::Uuid::from_u128(1))],
+ vec![uuid::Uuid::from_u128(2)],
+ FakeClient::installed(),
+ );
+
+ let error = service
+ .for_repository(&user(), "someone-else", "private", &permissions())
+ .await
+ .expect_err("refused");
+
+ assert!(matches!(error, GithubError::RepositoryUnavailable));
+}
+
+#[tokio::test]
+async fn refuses_a_repository_the_app_is_not_installed_on() {
+ let service = service(vec![], vec![], FakeClient::not_installed());
+
+ let error = service
+ .for_repository(&user(), "macro-inc", "macro", &permissions())
+ .await
+ .expect_err("refused");
+
+ assert!(matches!(error, GithubError::RepositoryUnavailable));
+}
+
+/// A refusal must not mint first and check afterwards.
+#[tokio::test]
+async fn refusing_mints_nothing() {
+ let client = FakeClient::installed();
+ let service = service(
+ vec![GithubAppInstallationSource::Team(uuid::Uuid::from_u128(1))],
+ vec![],
+ client,
+ );
+
+ service
+ .for_repository(&user(), "someone-else", "private", &permissions())
+ .await
+ .expect_err("refused");
+
+ assert_eq!(service.client.mint_count(), 0);
+}
+
+#[tokio::test]
+async fn scopes_the_token_to_the_one_repository_and_the_asked_for_permissions() {
+ let service = service(
+ vec![GithubAppInstallationSource::User(user().to_string())],
+ vec![],
+ FakeClient::installed(),
+ );
+
+ service
+ .for_repository(
+ &user(),
+ "macro-inc",
+ "macro",
+ &[("contents", "write"), ("pull_requests", "write")],
+ )
+ .await
+ .expect("minted");
+
+ let minted = service.client.minted.lock().expect("lock").clone();
+ assert_eq!(
+ minted,
+ vec![(
+ INSTALLATION,
+ "macro".to_owned(),
+ vec![
+ ("contents".to_owned(), "write".to_owned()),
+ ("pull_requests".to_owned(), "write".to_owned()),
+ ]
+ )]
+ );
+}
+
+#[test]
+fn reads_the_expiry_github_sent() {
+ let token = GithubInstallationAccessToken {
+ token: "ghs-scoped".to_owned(),
+ expires_at: "2099-01-01T00:00:00Z".to_owned(),
+ };
+
+ assert_eq!(
+ token.expires_at().expect("parsed").to_rfc3339(),
+ "2099-01-01T00:00:00+00:00"
+ );
+}
+
+#[test]
+fn an_unparseable_expiry_is_an_error() {
+ let token = GithubInstallationAccessToken {
+ token: "ghs-scoped".to_owned(),
+ expires_at: "whenever".to_owned(),
+ };
+
+ assert!(matches!(token.expires_at(), Err(GithubError::Internal(_))));
+}
diff --git a/crates/github/src/domain/service/installation_tokens/test_key.pem b/crates/github/src/domain/service/installation_tokens/test_key.pem
new file mode 100644
index 0000000000..735d5af3bf
--- /dev/null
+++ b/crates/github/src/domain/service/installation_tokens/test_key.pem
@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEogIBAAKCAQEAky4t+NMylQ8TEjJIKciwvjKWM+5EzSXDkvc+dlNN2g0/wRsr
+CTkFE9tQdEpJASbUz8+TRnExM8rbAB3p0tAyhAino2UDYvMRCBH5tGIBxKAPejZ2
+pEv63Gzk7xAlbIKyoOqdf/VUs5rNOsiB+l6/0Dbi2nBXFEjbQTNt33LOY6Smqu5f
+tcvN9gxHMr+m+vhnuUraL39sP0AWEhml/aw+LLIPlO1Cfp/on0sxRGmd0bhqTVWa
+o3fVqp8xqopQ3nCkZaYu6EUIzdg/ioktPEgY3kul/IS2QvJAfLAmi20/ahMLXJ+v
+izWM11Qs4jwfjKDxtXBgU70bv3WMC4aaU6o7JQIDAQABAoIBAHXS5UiqQncj3z+U
+80JIAH3y313pZDja/4s61U1CeTOTobNEvZofhJoV232NLo52eK14Xk1pNlthDRs1
+10dGFvquNw3OQvzG256bTUyDnSi8fkd3LFlw3f3ySv+67ErHApth1v5l9w3lYmCp
+vawih+n21nrKrlt1y9iRhGb6cJFBOsF8lmcFo9ijEzbRyaW+ou8J0ty9GNuwioET
+RaimVOo0nct0lrN4A269C+LqHLRUpj2MdxYEH4+1ziSCRDhCIQhPxd0ylpcXVEYP
+XubG5Kad8bueXn9HPtvkhxJJ0P9rD0M6+enPh5CdFPRg1qQchsoqSvRDxN4kwf5k
+XzbLw8ECgYEAxDQrvwDaGDMpcMrNaxtyatUfLi4uuinDNYuK+45XqMSWKXehINMc
+5bva0WBT3brKAdAoDRmZtfDiVvwc6Z59/WBSh+Zq29iLftazUhgCLejWFdIVO/SE
+vAx6v3Ctyl0XgrkkV2wtKtpj9T8EU+8O9HnduP075VXrMmOwrh8/qbECgYEAwAkz
+UG1fTs29BIbtAXauqhp14QM+J91viSQ7kzRIyElxp7S9IkAWWzei5K4piJGxBGBg
+QwgviN0cpK8URtfFIXQijzcYMwKhf0RqPrX9Kwh+9FGHcK0SHCx3JMdzkhtNrkR3
+1w+cjhP3VqsoZo/+reT7Wy6E4FlcrY6Rbo2qkbUCgYBZJiNibC6spEKGH3/q1NPO
+Ovwp7Y4JxIQQRlFmL60g4AIi4VpzIbmVoR+x1wUEUKUM4dnw6drv0n3lbDRu6jbw
+891MJqQTNHddsIxWFtaWqZ7s10ISte3BzCHR7o7ozheqrBkZJ+v19rlIa9O5l3vC
+FcVrEpUuhTWS9b0HwOcaYQKBgCuOqq32cOS9876gIAfx9IIuyEgGZUXDizXvGvgz
+psKPLhFdBH1NTgTYpMD74/3PFfipJ4xsweNoS8Pq1k2PSW5iGiij1YBUe28ThIm+
+27K0FZ+zEmZzSyVKzKdx+fvM55y8ePY120u6qaJl5h8FUD3/LygqcAc3HbdcHA6Y
+YXT1AoGAUyOZ7RPz8dLHWMA0+bRM4XGNxbyIjULKC/Fjf9bM3GIUWG8klxmBkCQJ
+MEt9yPb3VfwFUyBSNJt4C6zDrnd+62oT+A9aJHJcUDUjqdBsmZamDu7xBAeLGxsn
+sNRx7TF4iOEBkdJgBUoY4X/rZ+51FQOrdZGqeWo+8TjBhMQN7b4=
+-----END RSA PRIVATE KEY-----
diff --git a/crates/github/src/domain/service/mod.rs b/crates/github/src/domain/service/mod.rs
index aae7b837e7..1bffeec63d 100644
--- a/crates/github/src/domain/service/mod.rs
+++ b/crates/github/src/domain/service/mod.rs
@@ -1,8 +1,12 @@
//! Github service implementation.
+#[cfg(feature = "sync")]
+mod installation_tokens;
#[cfg(feature = "sync")]
mod sync;
+#[cfg(feature = "sync")]
+pub use installation_tokens::{InstallationTokenConfig, InstallationTokenService};
#[cfg(feature = "sync")]
pub use sync::{GithubSyncConfig, GithubSyncServiceImpl};
#[cfg(feature = "link")]
diff --git a/crates/github/src/domain/service/sync.rs b/crates/github/src/domain/service/sync.rs
index 7319084876..027e75097a 100644
--- a/crates/github/src/domain/service/sync.rs
+++ b/crates/github/src/domain/service/sync.rs
@@ -1140,21 +1140,10 @@ impl<
&self,
installation_id: u64,
) -> Result<GithubInstallationAccessToken, GithubError> {
- let now = chrono::Utc::now().timestamp() as u64;
-
- let claims = serde_json::json!({
- "iat": now - 60,
- "exp": now + (10 * 60),
- "iss": self.config.sync_app_client_id,
- });
-
- let header = jsonwebtoken::Header::new(jsonwebtoken::Algorithm::RS256);
- let encoding_key =
- jsonwebtoken::EncodingKey::from_rsa_pem(self.config.sync_app_pem.as_bytes())
- .map_err(|e| GithubError::Internal(anyhow::anyhow!("invalid PEM key: {e}")))?;
-
- let jwt = jsonwebtoken::encode(&header, &claims, &encoding_key)
- .map_err(|e| GithubError::Internal(anyhow::anyhow!("failed to encode JWT: {e}")))?;
+ let jwt = crate::domain::models::app_jwt(
+ &self.config.sync_app_client_id,
+ &self.config.sync_app_pem,
+ )?;
self.client
.generate_installation_access_token(&jwt, installation_id)
diff --git a/crates/github/src/domain/service/sync/test.rs b/crates/github/src/domain/service/sync/test.rs
index c33903bb1c..c1ac363dc4 100644
--- a/crates/github/src/domain/service/sync/test.rs
+++ b/crates/github/src/domain/service/sync/test.rs
@@ -44,6 +44,7 @@ use notification::domain::{
};
use super::*;
+use crate::domain::models::AppJwt;
/// UUID that corresponds to the short ID `2BuyvtY3aeEvHx4uG8iD51`.
const KNOWN_TASK_UUID: &str = "0d0dc589-f301-43f1-8b11-4ab448ca4bb4";
@@ -843,7 +844,7 @@ impl GithubSyncClient for StubSyncClient {
async fn generate_installation_access_token(
&self,
- _jwt: &str,
+ _jwt: &AppJwt,
_installation_id: u64,
) -> Result<GithubInstallationAccessToken, GithubError> {
Ok(GithubInstallationAccessToken {
@@ -852,6 +853,25 @@ impl GithubSyncClient for StubSyncClient {
})
}
+ async fn get_repository_installation(
+ &self,
+ _jwt: &AppJwt,
+ _owner: &str,
+ _repository: &str,
+ ) -> Result<Option<u64>, GithubError> {
+ unimplemented!("the sync service does not look installations up by repository")
+ }
+
+ async fn generate_scoped_installation_access_token(
+ &self,
+ _jwt: &AppJwt,
+ _installation_id: u64,
+ _repository: &str,
+ _permissions: &[(&str, &str)],
+ ) -> Result<GithubInstallationAccessToken, GithubError> {
+ unimplemented!("the sync service mints unscoped installation tokens")
+ }
+
async fn create_pr_comment(
&self,
_access_token: &str,
diff --git a/crates/github/src/inbound.rs b/crates/github/src/inbound.rs
index 02266a47f5..fbd008912d 100644
--- a/crates/github/src/inbound.rs
+++ b/crates/github/src/inbound.rs
@@ -27,7 +27,11 @@ impl axum::response::IntoResponse for crate::domain::models::GithubError {
(StatusCode::UNAUTHORIZED, "unauthenticated")
}
crate::domain::models::GithubError::Forbidden
- | crate::domain::models::GithubError::SetupUserNotLinked => {
+ | crate::domain::models::GithubError::SetupUserNotLinked
+ // Deliberately the same answer as any other refusal: whether the
+ // App is uninstalled or installed somewhere the caller has no
+ // claim to is a fact about other people's accounts.
+ | crate::domain::models::GithubError::RepositoryUnavailable => {
(StatusCode::FORBIDDEN, "forbidden")
}
crate::domain::models::GithubError::InvalidInstallationState
diff --git a/crates/github/src/outbound/github_sync_client.rs b/crates/github/src/outbound/github_sync_client.rs
index 18b9fc0899..0814f64258 100644
--- a/crates/github/src/outbound/github_sync_client.rs
+++ b/crates/github/src/outbound/github_sync_client.rs
@@ -8,7 +8,7 @@ use super::pull_request_metadata::{
use crate::domain::{
models::{
- EnrichedGithubPullRequest, GithubAuthenticatedUser, GithubError,
+ AppJwt, EnrichedGithubPullRequest, GithubAuthenticatedUser, GithubError,
GithubInstallationAccessToken, GithubPullRequestDetails, GithubSetupAccessToken,
GithubUserInstallation, GithubUserInstallationsPage,
},
@@ -222,7 +222,7 @@ impl GithubSyncClient for GithubSyncClientImpl {
#[tracing::instrument(skip(self, jwt), err)]
async fn generate_installation_access_token(
&self,
- jwt: &str,
+ jwt: &AppJwt,
installation_id: u64,
) -> Result<GithubInstallationAccessToken, GithubError> {
let response = self
@@ -230,7 +230,7 @@ impl GithubSyncClient for GithubSyncClientImpl {
.post(format!(
"https://api.github.com/app/installations/{installation_id}/access_tokens"
))
- .header("Authorization", format!("Bearer {jwt}"))
+ .header("Authorization", format!("Bearer {}", jwt.as_str()))
.header("Accept", "application/vnd.github+json")
.header("User-Agent", "Macro-Auth-Service")
.header("X-GitHub-Api-Version", "2022-11-28")
@@ -257,6 +257,114 @@ impl GithubSyncClient for GithubSyncClientImpl {
Ok(token)
}
+ #[tracing::instrument(skip(self, jwt), err)]
+ async fn get_repository_installation(
+ &self,
+ jwt: &AppJwt,
+ owner: &str,
+ repository: &str,
+ ) -> Result<Option<u64>, GithubError> {
+ #[derive(serde::Deserialize)]
+ struct InstallationResponse {
+ id: u64,
+ }
+
+ let response = self
+ .client
+ .get(format!(
+ "{}/repos/{owner}/{repository}/installation",
+ self.api_base_url()
+ ))
+ .header("Authorization", format!("Bearer {}", jwt.as_str()))
+ .header("Accept", "application/vnd.github+json")
+ .header("User-Agent", "Macro-Auth-Service")
+ .header("X-GitHub-Api-Version", "2022-11-28")
+ .send()
+ .await
+ .map_err(|e| GithubError::Internal(e.into()))?;
+
+ // Not installed and not visible to our App look the same from here, and
+ // both mean the same thing to a caller: no token is coming.
+ if response.status() == reqwest::StatusCode::NOT_FOUND {
+ return Ok(None);
+ }
+
+ let status = response.status();
+ if !status.is_success() {
+ let error_body = response
+ .text()
+ .await
+ .unwrap_or_else(|_| "unknown error".to_string());
+ return Err(GithubError::Internal(anyhow::anyhow!(
+ "failed to look up a repository installation (status {status}): {error_body}"
+ )));
+ }
+
+ let installation: InstallationResponse = response
+ .json()
+ .await
+ .map_err(|e| GithubError::Internal(e.into()))?;
+
+ Ok(Some(installation.id))
+ }
+
+ #[tracing::instrument(skip(self, jwt), err)]
+ async fn generate_scoped_installation_access_token(
+ &self,
+ jwt: &AppJwt,
+ installation_id: u64,
+ repository: &str,
+ permissions: &[(&str, &str)],
+ ) -> Result<GithubInstallationAccessToken, GithubError> {
+ /// The narrowing GitHub applies to the minted token. Omitting either
+ /// field widens it to everything the installation can reach, so both
+ /// are always sent.
+ #[derive(serde::Serialize)]
+ struct ScopedTokenRequest<'a> {
+ /// Names only, without the owner - GitHub resolves them within the
+ /// installation.
+ repositories: [&'a str; 1],
+ /// Permission name to level, as GitHub names them.
+ permissions: std::collections::BTreeMap<&'a str, &'a str>,
+ }
+
+ let body = ScopedTokenRequest {
+ repositories: [repository],
+ permissions: permissions.iter().copied().collect(),
+ };
+
+ let response = self
+ .client
+ .post(format!(
+ "{}/app/installations/{installation_id}/access_tokens",
+ self.api_base_url()
+ ))
+ .header("Authorization", format!("Bearer {}", jwt.as_str()))
+ .header("Accept", "application/vnd.github+json")
+ .header("User-Agent", "Macro-Auth-Service")
+ .header("X-GitHub-Api-Version", "2022-11-28")
+ .json(&body)
+ .send()
+ .await
+ .map_err(|e| GithubError::Internal(e.into()))?;
+
+ let status = response.status();
+ if !status.is_success() {
+ let error_body = response
+ .text()
+ .await
+ .unwrap_or_else(|_| "unknown error".to_string());
+ return Err(GithubError::Internal(anyhow::anyhow!(
+ "failed to create a scoped installation access token (status {status}): {error_body}"
+ )));
+ }
+
+ response
+ .json()
+ .await
+ .map_err(|e| GithubError::Internal(e.into()))
+ }
+
#[tracing::instrument(skip(self, access_token, body), err)]
async fn create_pr_comment(
&self,
diff --git a/crates/macro_db_client/migrations/20260819193628_agent_session_egress_token_hash.sql b/crates/macro_db_client/migrations/20260819193628_agent_session_egress_token_hash.sql
new file mode 100644
index 0000000000..9f3179d521
--- /dev/null
+++ b/crates/macro_db_client/migrations/20260819193628_agent_session_egress_token_hash.sql
@@ -0,0 +1,16 @@
+-- The sandbox's one secret, as it is stored: the SHA-256 hex digest of the
+-- opaque session token, never the token itself. A database dump must not yield
+-- a live credential.
+--
+-- Nullable because a session that never had a sandbox provisioned - a replayed
+-- recording, a row from before egress existed - has no token, and because the
+-- rows already in this table have none.
+ALTER TABLE agent_session
+ ADD COLUMN egress_token_hash text;
+
+-- Partial: the digests that exist must be unique, since this index is what the
+-- egress proxy authenticates by, while the many rows without one are not in
+-- conflict with each other.
+CREATE UNIQUE INDEX agent_session_egress_token_hash_key
+ ON agent_session (egress_token_hash)
+ WHERE egress_token_hash IS NOT NULL;
diff --git a/crates/mcp_client/src/domain/provider_registry.rs b/crates/mcp_client/src/domain/provider_registry.rs
index c23e11199f..c81a31df43 100644
--- a/crates/mcp_client/src/domain/provider_registry.rs
+++ b/crates/mcp_client/src/domain/provider_registry.rs
@@ -67,9 +67,15 @@ impl PreRegisteredProviders {
}
/// Look up pre-registered credentials for a server URL.
+ ///
+ /// A trailing slash does not change which server a URL names, and these
+ /// providers are exactly the ones that cannot register a client on the
+ /// fly: missing the match sends the flow to DCR, which they refuse, so
+ /// `https://api.githubcopilot.com/mcp/` would fail with "Dynamic client
+ /// registration not supported" while `.../mcp` connected fine.
pub fn get(&self, server_url: &str) -> Option<PreRegisteredCredentials> {
let env = self.env.as_ref()?;
- match server_url {
+ match server_url.trim_end_matches('/') {
SLACK_SERVER_URL => Some(PreRegisteredCredentials {
client_id: env.slack_mcp_client_id.to_string(),
client_secret: env.slack_mcp_client_secret.to_string(),
@@ -95,8 +101,13 @@ impl PreRegisteredProviders {
/// leaving the recorded approval and the granted access out of sync and the
/// flow failing after the user approves. Requesting explicit scopes keeps
/// both sides consistent.
+///
+/// Trailing slash insensitive, on the same grounds as
+/// [`PreRegisteredProviders::get`]: it does not change which server the URL
+/// names, and missing the match here is what leaves the recorded approval and
+/// the granted access out of sync.
pub fn dcr_default_scopes(server_url: &str) -> Vec<String> {
- match server_url {
+ match server_url.trim_end_matches('/') {
LINEAR_SERVER_URL => vec!["read".to_string(), "write".to_string()],
_ => vec![],
}
diff --git a/crates/mcp_client/src/domain/provider_registry/test.rs b/crates/mcp_client/src/domain/provider_registry/test.rs
index c2ffbdc840..73094e9832 100644
--- a/crates/mcp_client/src/domain/provider_registry/test.rs
+++ b/crates/mcp_client/src/domain/provider_registry/test.rs
@@ -15,3 +15,16 @@ fn unknown_server_gets_no_default_scopes() {
Vec::<String>::new()
);
}
+
+/// A trailing slash does not change which server a URL names. Getting this
+/// wrong is quiet and confusing: the pre-registered providers are exactly the
+/// ones that cannot register a client on the fly, so a missed match sends the
+/// flow to DCR and the connector fails with "Dynamic client registration not
+/// supported" for a provider Macro has credentials for.
+#[test]
+fn a_trailing_slash_names_the_same_server() {
+ assert_eq!(
+ dcr_default_scopes("https://mcp.linear.app/mcp/"),
+ dcr_default_scopes("https://mcp.linear.app/mcp")
+ );
+}
diff --git a/crates/pipedream_mcp/Cargo.toml b/crates/pipedream_mcp/Cargo.toml
index 529c7f2955..c6c9b68277 100644
--- a/crates/pipedream_mcp/Cargo.toml
+++ b/crates/pipedream_mcp/Cargo.toml
@@ -15,6 +15,7 @@ macro_authorization = { path = "../macro_authorization", default-features = fals
macro_user_id = { path = "../macro_user_id" }
model-error-response = { path = "../model-error-response" }
reqwest.workspace = true
+url.workspace = true
rmcp = { workspace = true, features = ["client", "transport-streamable-http-client-reqwest"] }
schemars.workspace = true
serde.workspace = true
diff --git a/crates/pipedream_mcp/src/outbound/api.rs b/crates/pipedream_mcp/src/outbound/api.rs
index 3de2411403..2c3a78797f 100644
--- a/crates/pipedream_mcp/src/outbound/api.rs
+++ b/crates/pipedream_mcp/src/outbound/api.rs
@@ -4,12 +4,14 @@ use crate::domain::models::{
};
use crate::domain::ports::{ConnectorDirectory, McpConnection, PipedreamConnect};
use anyhow::Context;
+use reqwest::header::{HeaderMap, HeaderValue};
use rmcp::service::ServiceExt;
use rmcp::transport::StreamableHttpClientTransport;
use rmcp::transport::streamable_http_client::StreamableHttpClientTransportConfig;
use serde::Deserialize;
use std::sync::Mutex;
use std::time::{Duration, Instant};
+use url::Url;
/// Default base URL of the Pipedream REST API.
pub const DEFAULT_API_URL: &str = "https://api.pipedream.com";
@@ -94,6 +96,7 @@ impl PipedreamClient {
{
return Ok(cached.token.clone());
}
+ tracing::debug!("pipedream api token absent or near expiry; requesting a fresh one");
let response = self
.http
@@ -289,30 +292,85 @@ impl ConnectorDirectory for PipedreamClient {
}
}
+/// How to address Pipedream's remote MCP server on behalf of one user's
+/// connected app.
+///
+/// The bearer is our project-level API token and the headers are what scope a
+/// request to the user and app - Pipedream injects the account's own
+/// credentials server-side from nothing but these. That is why this exists as
+/// a value handed to a proxy rather than only inside a client: whoever holds
+/// the bearer can claim to be any user, so the caller is expected to keep it
+/// away from anything user-controlled.
+///
+/// An outbound vocabulary, not a domain one, typed accordingly: headers are a
+/// validated `HeaderMap` and the destination a parsed `Url`, so an injectable
+/// value fails here, where it originates, and consumers have nothing left to
+/// re-validate.
+#[derive(Clone, Debug)]
+pub struct McpUpstreamCall {
+ /// URL of Pipedream's remote MCP server.
+ pub url: Url,
+ /// Our project API token, for `Authorization: Bearer`.
+ pub bearer_token: String,
+ /// The `x-pd-*` headers scoping the call to the record's user and app.
+ pub headers: HeaderMap,
+}
+
+/// Port for addressing Pipedream's remote MCP server without opening a
+/// session on it.
+///
+/// What [`McpConnection`] uses under the hood, exposed for callers that
+/// proxy raw MCP-over-HTTP traffic instead of speaking MCP themselves: they
+/// need the URL, bearer, and scoping headers to stamp onto a request that
+/// already exists. The returned call carries our project-level bearer, so it
+/// must never travel anywhere user-controlled.
+pub trait McpUpstream: Send + Sync + 'static {
+ /// The upstream call scoped to `record`'s app for `record.user_id`.
+ fn upstream(
+ &self,
+ record: &PipedreamConnection,
+ ) -> impl Future<Output = anyhow::Result<McpUpstreamCall>> + Send;
+}
+
+impl McpUpstream for PipedreamClient {
+ #[tracing::instrument(skip_all, err, fields(app = %record.app_slug, user_id = %record.user_id))]
+ async fn upstream(&self, record: &PipedreamConnection) -> anyhow::Result<McpUpstreamCall> {
+ let mut headers = HeaderMap::new();
+ let header = |value: &str| {
+ HeaderValue::from_str(value).with_context(|| format!("{value:?} is not a header value"))
+ };
+ headers.insert("x-pd-project-id", header(&self.config.project_id)?);
+ headers.insert("x-pd-environment", header(&self.config.environment)?);
+ headers.insert("x-pd-external-user-id", header(record.user_id.as_ref())?);
+ headers.insert("x-pd-app-slug", header(&record.app_slug)?);
+ // Flat per-app tools; no configuration meta-tools.
+ headers.insert("x-pd-tool-mode", HeaderValue::from_static("tools-only"));
+
+ Ok(McpUpstreamCall {
+ url: Url::parse(&self.config.mcp_url).context("PIPEDREAM_MCP_URL is not a url")?,
+ bearer_token: self.access_token().await?,
+ headers,
+ })
+ }
+}
+
impl McpConnection for PipedreamClient {
#[tracing::instrument(skip_all, err, fields(app = %record.app_slug, user_id = %record.user_id))]
async fn connect(&self, record: &PipedreamConnection) -> anyhow::Result<McpServer> {
- let token = self.access_token().await?;
+ let upstream = self.upstream(record).await?;
- let mut headers = reqwest::header::HeaderMap::new();
- let mut auth = reqwest::header::HeaderValue::from_str(&format!("Bearer {token}"))
+ let mut headers = upstream.headers;
+ let mut auth = HeaderValue::from_str(&format!("Bearer {}", upstream.bearer_token))
.map_err(|e| anyhow::anyhow!("invalid bearer token: {e}"))?;
auth.set_sensitive(true);
headers.insert(reqwest::header::AUTHORIZATION, auth);
- let header = |v: &str| reqwest::header::HeaderValue::from_str(v);
- headers.insert("x-pd-project-id", header(&self.config.project_id)?);
- headers.insert("x-pd-environment", header(&self.config.environment)?);
- headers.insert("x-pd-external-user-id", header(record.user_id.as_ref())?);
- headers.insert("x-pd-app-slug", header(&record.app_slug)?);
- // Flat per-app tools; no configuration meta-tools.
- headers.insert("x-pd-tool-mode", header("tools-only")?);
let client = reqwest::Client::builder()
.default_headers(headers)
.build()
.context("building Pipedream MCP HTTP client")?;
- let config = StreamableHttpClientTransportConfig::with_uri(&*self.config.mcp_url.clone());
+ let config = StreamableHttpClientTransportConfig::with_uri(upstream.url.as_str());
let transport = StreamableHttpClientTransport::with_client(client, config);
Ok(client_info().serve(transport).await?)
}
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index 3e9ff6237f..4d115cde8e 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -328,8 +328,50 @@ services:
- connection_gateway
- lexical_service
networks:
- - databases
- - services
+ databases:
+ services:
+ aliases:
+ # Hyphens, because a sandbox's git reaches the egress proxy by this
+ # name and git percent-encodes `_` in a host before matching
+ # `credential.<url>.helper`. Under the compose service name the
+ # scoped helper silently never fires and the clone prompts for a
+ # password it has no terminal to read.
+ - agent-harness-service
+
+ # ============================================================================
+ # mcp_service
+ # Macro's own MCP server: the DCS AI toolset over streamable HTTP, OAuth
+ # 2.1-fronted. Its one local client is the agent egress proxy, which serves
+ # it to sandboxes and Cursor agents under the reserved `macro` slug and
+ # dials it in-network - no host port, no proxy route.
+ # ============================================================================
+ mcp_service:
+ <<: [*common-env, *rust-services-image]
+ command: ["/app/out/mcp_service"]
+ restart: on-failure
+ environment:
+ # Its own public identity, not the env-wide value (which is document
+ # cognition's MCP OAuth callback route): rmcp only answers requests
+ # whose Host is on this URL's allowed-hosts list, and the egress proxy
+ # dials it as `mcp-service`.
+ - MCP_PUBLIC_URL=http://mcp-service:8080
+ # Links in tool responses open the local app.
+ - APP_BASE_URL=http://localhost:${FRONTEND_PORT:-3000}
+ - REDIS_URL=redis://redis:6379
+ depends_on:
+ - postgres
+ - redis
+ - fusionauth
+ networks:
+ # `auth` too: boot resolves the Google identity provider in FusionAuth,
+ # which lives on that network only.
+ auth:
+ databases:
+ services:
+ aliases:
+ # Hyphenated for the same reason as the harness alias above, and
+ # because it is the host the egress proxy's MACRO_MCP_URL names.
+ - mcp-service
# ============================================================================
# static_file_service (Port 8094)
diff --git a/infra/packages/resources/src/resources/service_target_group.ts b/infra/packages/resources/src/resources/service_target_group.ts
index 4a4becd4bf..0d94dc5c8a 100644
--- a/infra/packages/resources/src/resources/service_target_group.ts
+++ b/infra/packages/resources/src/resources/service_target_group.ts
@@ -16,8 +16,11 @@ type ServiceTargetGroupArgs = {
containerPort: number;
// Health check
healthCheckPath: string;
- // Path patterns
- pathPatterns: string[];
+ // Path patterns. Exactly one of pathPatterns and hostHeaders must be set.
+ pathPatterns?: string[];
+ // Host headers to match instead of paths, for a target group that owns a
+ // whole hostname on a shared listener.
+ hostHeaders?: string[];
// Priority **MUST BE UNIQUE**
priority: number;
// Health check
@@ -46,6 +49,12 @@ export class ServiceTargetGroup extends pulumi.ComponentResource {
this.tags = args.tags;
+ if (!args.pathPatterns === !args.hostHeaders) {
+ throw new Error(
+ `${name}: exactly one of pathPatterns and hostHeaders must be set`
+ );
+ }
+
this.target_group = new aws.lb.TargetGroup(
`${name}-target-group`,
{
@@ -79,11 +88,9 @@ export class ServiceTargetGroup extends pulumi.ComponentResource {
priority: args.priority,
conditions: [
- {
- pathPattern: {
- values: args.pathPatterns,
- },
- },
+ args.pathPatterns
+ ? { pathPattern: { values: args.pathPatterns } }
+ : { hostHeader: { values: args.hostHeaders ?? [] } },
],
actions: [
diff --git a/infra/stacks/agent-harness-service/Pulumi.dev.yaml b/infra/stacks/agent-harness-service/Pulumi.dev.yaml
index 9cfd7a1eb5..9188c41f0e 100644
--- a/infra/stacks/agent-harness-service/Pulumi.dev.yaml
+++ b/infra/stacks/agent-harness-service/Pulumi.dev.yaml
@@ -1,3 +1,5 @@
config:
aws-native:region: us-east-1
aws:region: us-east-1
+ agent-harness-service:github_sync_app_pem: github-sync-app-pem-dev
+ agent-harness-service:macro_api_token_private_secret_key: macro-api-token-private-key-dev
diff --git a/infra/stacks/agent-harness-service/Pulumi.prod.yaml b/infra/stacks/agent-harness-service/Pulumi.prod.yaml
index 9cfd7a1eb5..d692238d1b 100644
--- a/infra/stacks/agent-harness-service/Pulumi.prod.yaml
+++ b/infra/stacks/agent-harness-service/Pulumi.prod.yaml
@@ -1,3 +1,5 @@
config:
aws-native:region: us-east-1
aws:region: us-east-1
+ agent-harness-service:github_sync_app_pem: github-sync-app-pem-prod
+ agent-harness-service:macro_api_token_private_secret_key: macro-api-token-private-key-prod
diff --git a/infra/stacks/agent-harness-service/agent_harness_service.ts b/infra/stacks/agent-harness-service/agent_harness_service.ts
index 1abb9c70a4..005ed685df 100644
--- a/infra/stacks/agent-harness-service/agent_harness_service.ts
+++ b/infra/stacks/agent-harness-service/agent_harness_service.ts
@@ -5,6 +5,7 @@ import {
DATADOG_API_KEY,
DEFAULT_CONTINUE_BEFORE_STEADY_STATE,
EcsDeploymentFailureAlarm,
+ ServiceTargetGroup,
datadogAgentContainer,
fargateLogRouterSidecarContainer,
serviceLoadBalancer,
@@ -25,6 +26,15 @@ export const SERVICE_DOMAIN_NAME = `agent-harness${
stack === 'prod' ? '' : `-${stack}`
}.${BASE_DOMAIN}`;
+// The sandbox-facing egress proxy gets its own hostname rather than paths
+// carved out of the control API's: the control routes authenticate Macro
+// users, the egress routes authenticate session tokens presented by
+// model-authored code, and a separate host keeps the two trust domains
+// separable at the load balancer.
+export const EGRESS_DOMAIN_NAME = `agent-harness-egress${
+ stack === 'prod' ? '' : `-${stack}`
+}.${BASE_DOMAIN}`;
+
type Args = {
vpc: {
vpcId: pulumi.Output<string> | string;
@@ -35,6 +45,8 @@ type Args = {
containerEnvVars: { name: string; value: pulumi.Output<string> | string }[];
platform: { family: string; architecture: 'amd64' | 'arm64' };
serviceContainerPort: number;
+ /** Container port of the sandbox-facing egress proxy listener. */
+ egressContainerPort: number;
healthCheckPath: string;
isPrivate?: boolean;
ecsClusterArn: pulumi.Output<string> | string;
@@ -60,7 +72,9 @@ export class AgentHarnessService extends pulumi.ComponentResource {
public serviceAlbSg: aws.ec2.SecurityGroup;
public serviceSg: aws.ec2.SecurityGroup;
public domain: string;
+ public egressDomain: string;
public targetGroup: aws.lb.TargetGroup;
+ public egressTargetGroup: aws.lb.TargetGroup;
public lb: aws.lb.LoadBalancer;
public listener: aws.lb.Listener;
public service: awsx.ecs.FargateService;
@@ -78,6 +92,7 @@ export class AgentHarnessService extends pulumi.ComponentResource {
tags,
platform,
serviceContainerPort,
+ egressContainerPort,
healthCheckPath,
isPrivate,
ecsClusterArn,
@@ -89,6 +104,7 @@ export class AgentHarnessService extends pulumi.ComponentResource {
} = args;
this.domain = `https://${SERVICE_DOMAIN_NAME}`;
+ this.egressDomain = `https://${EGRESS_DOMAIN_NAME}`;
this.cloudStorageClusterName = cloudStorageClusterName;
this.tags = tags;
@@ -239,12 +255,41 @@ export class AgentHarnessService extends pulumi.ComponentResource {
vpc,
albSecurityGroupId: serviceAlbSg.id,
isPrivate,
+ // The egress proxy carries MCP event streams and git pack negotiation,
+ // both of which sit idle past the ALB's 60s default. Same value the
+ // other streaming hosts (mcp-server, connection-gateway) use.
+ idleTimeout: 3600,
tags,
});
this.targetGroup = targetGroup;
this.lb = lb;
this.listener = listener;
+ // The egress proxy listener, published on the same ALB under its own
+ // hostname. The default action still forwards to the control API, so
+ // nothing about the existing surface changes; only requests naming the
+ // egress host reach the egress port. The component also opens the
+ // ALB-to-service holes for the egress port.
+ // Not `${BASE_NAME}-egress`: with the helper's `-tg` suffix that is 36
+ // chars, and target group names cap at 32.
+ const egress = new ServiceTargetGroup(
+ `agent-harness-egress-${stack}`,
+ {
+ listenerArn: listener.arn,
+ vpcId: vpc.vpcId,
+ containerPort: egressContainerPort,
+ healthCheckPath,
+ hostHeaders: [EGRESS_DOMAIN_NAME],
+ // The only rule on this listener; any future rule must pick another.
+ priority: 10,
+ serviceSecurityGroupId: serviceSg.id,
+ albSecurityGroupId: serviceAlbSg.id,
+ tags,
+ },
+ { parent: this }
+ );
+ this.egressTargetGroup = egress.target_group;
+
const dopplerEcsEnvironment = new DopplerEcsEnvironment(
BASE_NAME,
{ tags: this.tags },
@@ -267,6 +312,9 @@ export class AgentHarnessService extends pulumi.ComponentResource {
},
// Never run 2 tasks at once, even transiently during a deploy: stop
// the old one before the new one starts (see the class doc comment).
+ // This blackout covers the egress proxy too - sandbox git and MCP
+ // calls fail for the whole window, they are not more available than
+ // the control API.
deploymentMinimumHealthyPercent: 0,
deploymentMaximumPercent: 100,
desiredCount: 1,
@@ -299,6 +347,13 @@ export class AgentHarnessService extends pulumi.ComponentResource {
name: 'BASE_URL',
value: this.domain,
},
+ // Where sandboxes dial the egress proxy - through the ALB,
+ // not the container port, so it is set here where the
+ // hostname is defined rather than in Doppler.
+ {
+ name: 'EGRESS_BASE_URL',
+ value: this.egressDomain,
+ },
],
secrets: [...dopplerEcsEnvironment.containerSecrets],
logConfiguration: {
@@ -321,6 +376,13 @@ export class AgentHarnessService extends pulumi.ComponentResource {
containerPort: serviceContainerPort,
targetGroup,
},
+ {
+ appProtocol: 'http',
+ name: `${BASE_NAME}-egress-tcp-${stack}`,
+ hostPort: egressContainerPort,
+ containerPort: egressContainerPort,
+ targetGroup: this.egressTargetGroup,
+ },
],
},
},
@@ -357,6 +419,22 @@ export class AgentHarnessService extends pulumi.ComponentResource {
},
{ parent: this }
);
+ new aws.route53.Record(
+ `${BASE_NAME}-egress-domain-record`,
+ {
+ name: EGRESS_DOMAIN_NAME,
+ type: 'A',
+ zoneId: zone.zoneId,
+ aliases: [
+ {
+ evaluateTargetHealth: false,
+ name: this.lb.dnsName,
+ zoneId: this.lb.zoneId,
+ },
+ ],
+ },
+ { parent: this }
+ );
}
private initializeSecurityGroups({
diff --git a/infra/stacks/agent-harness-service/index.ts b/infra/stacks/agent-harness-service/index.ts
index 631053e0e3..0fe1df2561 100644
--- a/infra/stacks/agent-harness-service/index.ts
+++ b/infra/stacks/agent-harness-service/index.ts
@@ -1,6 +1,7 @@
import * as aws from '@pulumi/aws';
import * as pulumi from '@pulumi/pulumi';
import {
+ config,
getAiToolsInfra,
getMacroApiToken,
stack,
@@ -27,6 +28,19 @@ const jwtSecretKeyArn = aws.secretsmanager
.getSecretVersionOutput({ secretId: `fusionauth-jwt-secret-${stack}` })
.apply((secret) => secret.arn);
+// The egress proxy mints GitHub App installation tokens and Macro API tokens
+// inline, so the task role needs the App's PEM and the signing key - both
+// held as Secrets Manager secret names the service resolves at runtime.
+const githubSyncAppPemArn = aws.secretsmanager
+ .getSecretVersionOutput({ secretId: config.require('github_sync_app_pem') })
+ .apply((secret) => secret.arn);
+
+const macroApiTokenPrivateKeyArn = aws.secretsmanager
+ .getSecretVersionOutput({
+ secretId: config.require('macro_api_token_private_secret_key'),
+ })
+ .apply((secret) => secret.arn);
+
const MACRO_API_TOKENS = getMacroApiToken();
// ── AI tools infra ───────────────────────────────────────────────────────────
@@ -71,6 +85,7 @@ const service = new AgentHarnessService(`agent-harness-service-${stack}`, {
tags,
platform: { family: 'linux', architecture: 'amd64' },
serviceContainerPort: 8101,
+ egressContainerPort: 8102,
healthCheckPath: '/health',
isPrivate: false,
ecsClusterArn: cloudStorageClusterArn,
@@ -78,6 +93,8 @@ const service = new AgentHarnessService(`agent-harness-service-${stack}`, {
secretKeyArns: [
jwtSecretKeyArn,
MACRO_API_TOKENS.macroApiTokenPublicKeyArn,
+ macroApiTokenPrivateKeyArn,
+ githubSyncAppPemArn,
...aiTools.secretArns,
],
queueArns:
@@ -103,4 +120,5 @@ const service = new AgentHarnessService(`agent-harness-service-${stack}`, {
});
export const agentHarnessServiceUrl = pulumi.interpolate`${service.domain}`;
+export const agentHarnessEgressUrl = pulumi.interpolate`${service.egressDomain}`;
export const agentHarnessServiceRoleArn = service.role.arn;
diff --git a/nix/cloud-storage.nix b/nix/cloud-storage.nix
index 01689953dc..31fd73eb88 100644
--- a/nix/cloud-storage.nix
+++ b/nix/cloud-storage.nix
@@ -828,6 +828,9 @@
nsc
parallel
docker-compose
+ # `just run_local` opens a quick tunnel to the agent egress proxy so
+ # Cursor cloud agents can dial a local stack's MCP servers.
+ cloudflared
curl
openssh
wget
diff --git a/rules/ast-grep/rust-no-transport-in-domain.yml b/rules/ast-grep/rust-no-transport-in-domain.yml
index 278239161d..e759859d26 100644
--- a/rules/ast-grep/rust-no-transport-in-domain.yml
+++ b/rules/ast-grep/rust-no-transport-in-domain.yml
@@ -15,6 +15,12 @@ ignores:
- '**/tests.rs'
- '**/test/**'
- '**/tests/**'
+ # agent_egress is a credential-stamping HTTP proxy: its domain's subject
+ # matter IS the http request passing through, so `http` (the I/O-free
+ # vocabulary crate axum and reqwest both speak) is its domain language,
+ # not transport leakage. What this rule exists to catch — IntoResponse
+ # impls and status-code mapping — stays in that crate's inbound adapter.
+ - 'crates/agent_egress/src/domain/**'
rule:
any:
- kind: scoped_identifier
diff --git a/services/agent_harness_service/Cargo.toml b/services/agent_harness_service/Cargo.toml
index 11b8114e31..bcef07b90b 100644
--- a/services/agent_harness_service/Cargo.toml
+++ b/services/agent_harness_service/Cargo.toml
@@ -13,6 +13,7 @@ name = "agent_harness_service_openapi"
path = "src/openapi.rs"
[dependencies]
+agent_egress = { path = "../../crates/agent_egress" }
agent_fold = { path = "../../crates/agent_fold" }
agent_harness = { path = "../../crates/agent_harness" }
agent_inmem = { path = "../../crates/agent_inmem" }
@@ -30,6 +31,13 @@ cursor_api_key = { path = "../../crates/cursor_api_key" }
cursor_cloud_agents = { path = "../../crates/cursor_cloud_agents" }
database_env_vars = { path = "../../crates/database_env_vars" }
entity_access = { path = "../../crates/entity_access" }
+github = { path = "../../crates/github", default-features = false, features = [
+ "outbound",
+ "ports",
+ "sync",
+] }
+pipedream_mcp = { path = "../../crates/pipedream_mcp" }
+url = { workspace = true }
contacts = { path = "../../crates/contacts" }
macro_aws_config = { path = "../../crates/macro_aws_config" }
macro_event_broker = { path = "../../crates/macro_event_broker", features = ["outbound"] }
diff --git a/services/agent_harness_service/src/api.rs b/services/agent_harness_service/src/api.rs
index 3daed36cb9..b9739d5506 100644
--- a/services/agent_harness_service/src/api.rs
+++ b/services/agent_harness_service/src/api.rs
@@ -5,6 +5,8 @@
use std::time::Duration;
+use agent_egress::domain::service::EgressService;
+use agent_egress::inbound::axum_router::{EgressRouterState, egress_router};
use agent_harness::inbound::runtime_gateway::{RuntimeGatewayState, runtime_gateway_router};
use agent_session::domain::ports::{
AgentSessionNotificationRecipient, BotDirectory, SessionOpener,
@@ -26,6 +28,32 @@ use utoipa_swagger_ui::SwaggerUi;
pub mod swagger;
+/// Serve the sandbox-facing egress proxy on its own listener.
+///
+/// No CORS layer and no Swagger: nothing browses this. Its only client is a
+/// sandbox, and its only credential is a session token.
+pub async fn serve_egress<Service>(
+ service: Service,
+ port: u16,
+ shutdown: impl Future<Output = ()> + Send + 'static,
+) -> anyhow::Result<()>
+where
+ Service: EgressService + 'static,
+{
+ let app = egress_router(EgressRouterState::new(std::sync::Arc::new(service)));
+
+ let listener = tokio::net::TcpListener::bind(format!("0.0.0.0:{port}"))
+ .await
+ .with_context(|| format!("failed to bind agent harness egress to port {port}"))?;
+
+ tracing::info!(port, "agent harness egress listening");
+
+ axum::serve(listener, app.into_make_service())
+ .with_graceful_shutdown(shutdown)
+ .await
+ .context("agent harness egress http failed")
+}
+
/// Build the router and serve it until the process is asked to stop.
pub async fn setup_and_serve<T, R, Opener, Bots, Access, Auth>(
read_state: AgentSessionRouterState<T, Access, Auth>,
diff --git a/services/agent_harness_service/src/config.rs b/services/agent_harness_service/src/config.rs
index b1be2c1c6c..6a92ee569b 100644
--- a/services/agent_harness_service/src/config.rs
+++ b/services/agent_harness_service/src/config.rs
@@ -6,12 +6,40 @@ use database_env_vars::DatabaseUrl;
pub use macro_env::Environment;
use macro_uuid::Uuid;
+use secretsmanager_client::LocalOrRemoteSecret;
+
macro_env_var::env_vars!(
/// Comma-separated Kafka bootstrap servers.
#[derive(Clone)]
pub struct KafkaBrokers;
+ /// PEM private key of the GitHub App installation tokens are minted with.
+ pub struct GithubSyncAppPemSecretKey;
+ /// RSA key Macro API tokens are signed with - the same one
+ /// `authentication_service` signs with. The egress proxy mints
+ /// short-lived tokens for session owners inline.
+ pub struct MacroApiTokenPrivateSecretKey;
+ /// Issuer stamped into minted Macro API tokens; must match what the
+ /// validators expect.
+ pub struct MacroApiTokenIssuer;
+ /// OAuth client ID for the Pipedream API. The same credentials
+ /// `document_cognition_service` uses: the connections a sandbox spends
+ /// are the ones the person connected in Macro, in the same rows.
+ pub struct PipedreamClientId;
+ /// OAuth client secret for the Pipedream API.
+ pub struct PipedreamClientSecret;
+ /// The Pipedream Connect project ID (`proj_...`).
+ pub struct PipedreamProjectId;
);
+/// The Pipedream project environment matching this deployment: production in
+/// prd, development everywhere else.
+fn default_pipedream_environment() -> String {
+ match Environment::new_or_prod() {
+ Environment::Production => "production".to_owned(),
+ _ => "development".to_owned(),
+ }
+}
+
/// The configuration parameters for the agent harness service.
#[derive(macro_config::MacroConfig)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
@@ -36,11 +64,6 @@ pub struct Config {
/// keeping image builds off the first-prompt critical path.
#[macro_config_default(String::from("macro-agent-harness"))]
pub daytona_snapshot: String,
- /// Token with read access to the repo cloned into sandboxes. Empty
- /// means managed sandboxes cannot clone; external sessions are
- /// unaffected.
- #[macro_config_default(String::new())]
- pub github_token: String,
/// API key sandboxes run Anthropic models with. Injected into the
/// sandbox environment at creation, where it activates opencode's
/// `anthropic` provider — the only provider
@@ -109,6 +132,49 @@ pub struct Config {
/// Port the control routes are served on.
#[macro_config_default(8101)]
pub port: u16,
+ /// Port the sandbox-facing egress proxy is served on.
+ ///
+ /// A second listener rather than more routes on `port`: the control routes
+ /// are authenticated as Macro users and reached from inside the platform,
+ /// and the egress routes are authenticated by session token and reached
+ /// from a sandbox running model-authored code. Separate ports keep the two
+ /// separable at the network as well as in the code.
+ #[macro_config_default(8102)]
+ pub egress_port: u16,
+ /// Where a sandbox should dial the egress proxy.
+ ///
+ /// Not derivable from `egress_port`: the sandbox reaches this through
+ /// whatever ingress fronts the deployment, not on the container's own port.
+ #[macro_config_default(String::from("http://localhost:8102"))]
+ pub egress_base_url: String,
+ /// OAuth client ID for the Pipedream API.
+ pub pipedream_client_id: PipedreamClientId,
+ /// OAuth client secret for the Pipedream API.
+ pub pipedream_client_secret: PipedreamClientSecret,
+ /// The Pipedream Connect project ID.
+ pub pipedream_project_id: PipedreamProjectId,
+ /// The Pipedream project environment (`development` or `production`).
+ #[macro_config_default(default_pipedream_environment())]
+ pub pipedream_environment: String,
+ /// Base URL of the Pipedream API.
+ #[macro_config_default(String::from(pipedream_mcp::outbound::api::DEFAULT_API_URL))]
+ pub pipedream_api_url: String,
+ /// URL of Pipedream's remote MCP server.
+ #[macro_config_default(String::from(pipedream_mcp::outbound::api::DEFAULT_MCP_URL))]
+ pub pipedream_mcp_url: String,
+ /// Where the egress proxy reaches Macro's own MCP server (`mcp_service`),
+ /// endpoint path included - e.g. `https://mcp.macro.com/mcp`, or the
+ /// in-network `http://mcp-service:8080/mcp` on a local stack. Cleartext is
+ /// refused at boot unless `ENVIRONMENT=local`.
+ pub macro_mcp_url: String,
+ /// RSA key Macro API tokens are signed with.
+ pub macro_api_token_private_secret_key: LocalOrRemoteSecret<MacroApiTokenPrivateSecretKey>,
+ /// Issuer stamped into minted Macro API tokens.
+ pub macro_api_token_issuer: MacroApiTokenIssuer,
+ /// Client id of the GitHub App installation tokens are minted for.
+ pub github_sync_app_client_id: String,
+ /// PEM private key of that App.
+ pub github_sync_app_pem_secret_key: LocalOrRemoteSecret<GithubSyncAppPemSecretKey>,
}
impl Config {
diff --git a/services/agent_harness_service/src/containers.rs b/services/agent_harness_service/src/containers.rs
index b67e09003a..7fed9473ae 100644
--- a/services/agent_harness_service/src/containers.rs
+++ b/services/agent_harness_service/src/containers.rs
@@ -194,6 +194,15 @@ where
}
}
+ /// An in-process session has no container and no egress environment, so
+ /// there is no token to read back; sandboxes delegate to their provider.
+ async fn session_token(&self, session: AgentSessionId) -> Result<Option<String>> {
+ match self.route(session).await? {
+ Route::InMem(_) => Ok(None),
+ Route::Sandbox => self.sandbox.session_token(session).await,
+ }
+ }
+
async fn teardown(&self, session: AgentSessionId) -> Result<()> {
match self.route(session).await? {
Route::InMem(_) => {
diff --git a/services/agent_harness_service/src/containers/test.rs b/services/agent_harness_service/src/containers/test.rs
index 27980aa0c5..2a4a6f0e01 100644
--- a/services/agent_harness_service/src/containers/test.rs
+++ b/services/agent_harness_service/src/containers/test.rs
@@ -1,6 +1,6 @@
use super::*;
use agent_fold::domain::service::FoldedMessageService;
-use agent_harness::outbound::daytona::{AnthropicApiKey, GithubToken};
+use agent_harness::outbound::daytona::AnthropicApiKey;
use agent_harness::outbound::local::{LocalContainerManager, LocalSettings};
use agent_session::domain::ports::NoOpRealtime;
use agent_session::domain::service::AgentSessionServiceImpl;
@@ -13,7 +13,6 @@ fn unreachable_sandbox() -> HarnessContainers {
docker_binary: "false".to_owned(),
image: "unused".to_owned(),
network: "unused".to_owned(),
- github_token: GithubToken::new(String::new()),
anthropic_api_key: AnthropicApiKey::new(String::new()),
}))
}
diff --git a/services/agent_harness_service/src/main.rs b/services/agent_harness_service/src/main.rs
index ed77761b50..26c73e43fc 100644
--- a/services/agent_harness_service/src/main.rs
+++ b/services/agent_harness_service/src/main.rs
@@ -15,6 +15,12 @@ mod trigger;
use std::{future::Future, pin::Pin, sync::Arc};
+use agent_egress::domain::service::EgressServiceImpl;
+use agent_egress::outbound::forwarder::ReqwestForwarder;
+use agent_egress::outbound::github_tokens::GithubAppTokens;
+use agent_egress::outbound::macro_mcp::{MacroApiTokenSigner, WithMacroMcp};
+use agent_egress::outbound::mcp_credentials::PipedreamMcpCredentials;
+use agent_egress::outbound::session_authority::StoredTokenSessionAuthority;
use agent_fold::domain::service::FoldedMessageService;
use agent_harness::domain::model::{HarnessCommand, HarnessDefaults, SessionDefaults};
use agent_harness::domain::service::AgentHarnessService;
@@ -27,8 +33,9 @@ use agent_harness::outbound::containers::HarnessContainers;
use agent_harness::outbound::cursor::{CursorContainerManager, PgCursorApiKeys};
use agent_harness::outbound::daytona::{
AnthropicApiKey as AnthropicApiKeySecret, DaytonaApiKey as DaytonaApiKeySecret,
- DaytonaContainerManager, DaytonaSettings, GithubToken as GithubTokenSecret, Snapshot,
+ DaytonaContainerManager, DaytonaSettings, Snapshot,
};
+use agent_harness::outbound::egress::EgressProvisioner;
use agent_harness::outbound::local::{LocalContainerManager, LocalSettings};
use agent_harness::outbound::routing::RoutedContainerManager;
use agent_harness::outbound::runtime_registry::RuntimeRegistry;
@@ -61,6 +68,9 @@ use containers::{InMemRuntime, RoutedContainers};
use cursor_api_key::cipher::{AwsKmsCiphertexts, KmsCursorApiKeyCipher};
use cursor_cloud_agents::api::CURSOR_API_BASE_URL;
use cursor_cloud_agents::domain::model::RepoUrl as CursorRepoUrl;
+use github::domain::service::{InstallationTokenConfig, InstallationTokenService};
+use github::outbound::github_sync_client::GithubSyncClientImpl;
+use github::outbound::pg_github_sync_repo::PgGithubSyncRepo;
use kafka_util::{GroupName, KafkaEventConsumer, consumer_span, record_span_error};
use lexical_client::LexicalClient;
use macro_auth::middleware::decode_jwt::JwtValidationArgs;
@@ -74,6 +84,8 @@ use macro_event_broker::{
MacroEventCollection as _, MacroEventConsumerService,
};
use macro_service_urls::{ConnectionGatewayUrl, LexicalServiceUrl};
+use pipedream_mcp::outbound::api::{PipedreamClient, PipedreamConfig};
+use pipedream_mcp::outbound::pg_connection_repo::PgConnectionRepo;
use rdkafka::consumer::CommitMode;
use rdkafka::message::{BorrowedMessage, Message as _};
use sqlx::postgres::PgPoolOptions;
@@ -122,7 +134,15 @@ async fn main() -> anyhow::Result<()> {
async fn run() -> anyhow::Result<()> {
agent_harness::install_tls_provider();
- let config = Config::from_env()?;
+ // AWS first, because the config's secrets resolve through Secrets Manager.
+ let aws_config = macro_aws_config::get_macro_aws_config().await;
+ let secrets = secretsmanager_client::SecretsManager::new(aws_sdk_secretsmanager::Client::new(
+ &aws_config,
+ ));
+ let config = Config::from_env()?
+ .resolve_remote_secrets(Environment::new_or_prod(), &secrets)
+ .await
+ .context("failed to resolve agent harness service secrets")?;
let bot_id = BotId::new_from_uuid(config.harness_bot_id);
// The in-process Macro bot is a compile-time identity, not configuration:
// it is always `bot_id::MACRO_AI_BOT_ID`, so the only real question is
@@ -183,11 +203,6 @@ async fn run() -> anyhow::Result<()> {
if !matches!(config.environment, Environment::Local) {
anyhow::bail!("DEV_DANGEROUS_LOCAL_CONTAINERS is only allowed when ENVIRONMENT=local");
}
- if config.github_token.trim().is_empty() {
- tracing::warn!(
- "GITHUB_TOKEN is unset: local sandboxes cannot clone private repositories; external agent sessions are unaffected"
- );
- }
let network = config.local_container_network.trim();
if network.is_empty() {
anyhow::bail!(
@@ -198,22 +213,21 @@ async fn run() -> anyhow::Result<()> {
docker_binary: config.local_container_docker_binary.clone(),
image: config.local_container_image.clone(),
network: network.to_owned(),
- github_token: GithubTokenSecret::new(config.github_token.clone()),
anthropic_api_key: anthropic_api_key.clone(),
}))
} else {
- // Credential-less boot is deliberate: external sessions need neither.
- // A managed spawn without them fails at spawn time instead, loudly.
- if config.daytona_api_key.trim().is_empty() || config.github_token.trim().is_empty() {
+ // Credential-less boot is deliberate: external sessions need no
+ // sandbox at all. A Daytona spawn without a key fails at spawn time
+ // instead, loudly.
+ if config.daytona_api_key.trim().is_empty() {
tracing::warn!(
- "DAYTONA_API_KEY and/or GITHUB_TOKEN are unset: managed sandboxes are unarmed; external agent sessions are unaffected"
+ "DAYTONA_API_KEY is unset: Daytona-backed sandboxes are unarmed; external agent sessions are unaffected"
);
}
HarnessContainers::Daytona(DaytonaContainerManager::new(DaytonaSettings {
api_url: config.daytona_api_url.clone(),
api_key: DaytonaApiKeySecret::new(config.daytona_api_key.clone()),
snapshot: Snapshot::new(config.daytona_snapshot.clone()),
- github_token: GithubTokenSecret::new(config.github_token.clone()),
anthropic_api_key,
}))
};
@@ -253,8 +267,6 @@ async fn run() -> anyhow::Result<()> {
),
);
- let aws_config = macro_aws_config::get_macro_aws_config().await;
-
// Cursor sessions run on their owner's own Cursor account, so there is no
// deployment-wide key to arm this with: the manager reads each session
// owner's key at spawn. Decrypt-only — registering keys belongs to the
@@ -290,6 +302,7 @@ async fn run() -> anyhow::Result<()> {
);
let containers =
RoutedContainerManager::new(sandbox_and_inmem, cursor_manager, session_repo.clone());
+
let notifications = Arc::new(notification::domain::service::SqsNotificationIngress {
queue: notification::outbound::queue::SqsQueue::new(
aws_sdk_sqs::Client::new(&aws_config),
@@ -360,6 +373,27 @@ async fn run() -> anyhow::Result<()> {
// in-process too; only mentioning the coder bot gets a sandbox.
.with_managed_bot(bot);
}
+
+ // MCP connections: the same rows the chat tool path reads, so an app
+ // connected in Macro is an app the sandbox can reach, with nothing to
+ // keep in sync. The rows hold no secrets - Pipedream owns the grants.
+ let mcp_connections = Arc::new(PgConnectionRepo::new(pool.clone()));
+
+ // The client that addresses Pipedream's remote MCP server, built from the
+ // same credentials `document_cognition_service` uses.
+ let pipedream = PipedreamClient::new(PipedreamConfig {
+ client_id: config.pipedream_client_id.to_string(),
+ client_secret: config.pipedream_client_secret.to_string(),
+ project_id: config.pipedream_project_id.to_string(),
+ environment: config.pipedream_environment.clone(),
+ api_url: config.pipedream_api_url.clone(),
+ mcp_url: config.pipedream_mcp_url.clone(),
+ // Only Connect tokens carry allowed origins, and this service never
+ // mints one: connecting apps stays in the app.
+ allowed_origins: Vec::new(),
+ })
+ .context("failed to build Pipedream client")?;
+
let harness = Arc::new(AgentHarnessService::new(
sessions,
containers,
@@ -367,6 +401,7 @@ async fn run() -> anyhow::Result<()> {
Arc::clone(&runtimes),
prompt_context,
prompt_composer,
+ EgressProvisioner::new(Arc::clone(&mcp_connections), config.egress_base_url.clone()),
defaults,
));
@@ -375,13 +410,7 @@ async fn run() -> anyhow::Result<()> {
// main task, and both run until shutdown.
let authorization_service = MacroAuthorizationServiceImpl::new(
MacroAuthJwtValidator::new(
- JwtValidationArgs::new_with_secret_manager(
- config.environment,
- &secretsmanager_client::SecretsManager::new(aws_sdk_secretsmanager::Client::new(
- &aws_config,
- )),
- )
- .await?,
+ JwtValidationArgs::new_with_secret_manager(config.environment, &secrets).await?,
),
InternalAuthConfig {
api_key: config.internal_api_key.clone(),
@@ -438,6 +467,46 @@ async fn run() -> anyhow::Result<()> {
config.internal_api_key.clone(),
));
+ // Every session's MCP servers: Macro's own under the reserved `macro`
+ // slug, then the owner's Pipedream connections. The `macro` credential is
+ // signed inline with the same key authentication_service holds; what this
+ // process hands out is always single-user and minutes from expiry.
+ let mcp_credentials = WithMacroMcp::new(
+ PipedreamMcpCredentials::new(mcp_connections, pipedream),
+ MacroApiTokenSigner::new(
+ pool.clone(),
+ config.macro_api_token_issuer.as_ref(),
+ config.macro_api_token_private_secret_key.as_ref(),
+ ),
+ url::Url::parse(&config.macro_mcp_url).context("MACRO_MCP_URL is not a url")?,
+ // The one gate on cleartext: a local stack's mcp-service is dialed
+ // across the compose bridge, where TLS would be theater. Everywhere
+ // else, an http URL refuses to boot.
+ matches!(config.environment, Environment::Local),
+ )
+ .context("the macro MCP upstream is misconfigured")?;
+
+ // The egress proxy: one binary today, its own listener from the start.
+ let egress = EgressServiceImpl::new(
+ StoredTokenSessionAuthority::new(PgAgentSessionRepo::new(pool.clone())),
+ mcp_credentials,
+ GithubAppTokens::new(InstallationTokenService::new(
+ InstallationTokenConfig {
+ client_id: config.github_sync_app_client_id.clone(),
+ private_key_pem: config.github_sync_app_pem_secret_key.as_ref().to_owned(),
+ },
+ PgGithubSyncRepo::new(pool.clone()),
+ GithubSyncClientImpl::default(),
+ )),
+ ReqwestForwarder::new()?,
+ );
+ let egress_port = config.egress_port;
+ let egress_http = tokio::spawn(async move {
+ if let Err(error) = api::serve_egress(egress, egress_port, shutdown_signal()).await {
+ tracing::error!(error = ?error, "agent harness service egress stopped");
+ }
+ });
+
// The consumer: every agent-session event, filtered to our bot.
let consumer =
KafkaEventConsumer::<AgentHarnessConsumerGroup>::from_env(config.kafka_brokers.as_ref())?;
@@ -604,6 +673,7 @@ async fn run() -> anyhow::Result<()> {
http.abort();
trigger.abort();
+ egress_http.abort();
let stop_failures = container_shutdown.shutdown_all().await;
if stop_failures > 0 {
tracing::error!(stop_failures, "some sandboxes failed to stop");
diff --git a/services/document_cognition_service/src/config.rs b/services/document_cognition_service/src/config.rs
index e75a675b42..9eec2784b5 100644
--- a/services/document_cognition_service/src/config.rs
+++ b/services/document_cognition_service/src/config.rs
@@ -2,7 +2,7 @@ use anyhow::Context;
use macro_auth::InternalApiKey;
pub use macro_env::Environment;
use macro_env_var::{env_vars, maybe_env_vars};
-use macro_service_urls::AiEditingWorkerUrl;
+use macro_service_urls::{AiEditingWorkerUrl, DocumentCognitionServiceUrl};
use secretsmanager_client::LocalOrRemoteSecret;
use crate::core::constants::DEFAULT_DOCUMENT_BATCH_LIMIT;
@@ -107,6 +107,9 @@ pub struct Config {
/// AI editing worker URL
#[macro_config_default(AiEditingWorkerUrl::unwrap_new().to_string())]
pub ai_editing_worker_url: String,
+ /// Browser-facing base URL used for MCP OAuth redirects and client metadata.
+ #[macro_config_default(DocumentCognitionServiceUrl::unwrap_new().to_string())]
+ pub mcp_public_url: String,
/// JWT secret for minting document permission tokens for the editing worker.
pub document_permission_jwt: DocumentPermissionJwt,
/// Comma-separated Kafka bootstrap servers for the macro event broker.
@@ -165,6 +168,7 @@ impl Config {
pipedream_allowed_origins: PipedreamAllowedOrigins::Unset,
internal_api_key: InternalApiKey::Comptime(""),
ai_editing_worker_url: AiEditingWorkerUrl::unwrap_new().to_string(),
+ mcp_public_url: DocumentCognitionServiceUrl::unwrap_new().to_string(),
document_permission_jwt: DocumentPermissionJwt::Comptime("DOCUMENT_PERMISSION_JWT"),
kafka_brokers: KafkaBrokers::Comptime("localhost:9092"),
}
diff --git a/services/document_cognition_service/src/main.rs b/services/document_cognition_service/src/main.rs
index 0797353919..c869a6b3ab 100644
--- a/services/document_cognition_service/src/main.rs
+++ b/services/document_cognition_service/src/main.rs
@@ -34,8 +34,8 @@ use macro_authorization::{
};
use macro_entrypoint::MacroEntrypoint;
use macro_service_urls::{
- ConnectionGatewayUrl, DocumentCognitionServiceUrl, DocumentStorageServiceUrl, EmailServiceUrl,
- LexicalServiceUrl, StaticFileServiceUrl, SyncServiceUrl,
+ ConnectionGatewayUrl, DocumentStorageServiceUrl, EmailServiceUrl, LexicalServiceUrl,
+ StaticFileServiceUrl, SyncServiceUrl,
};
use notification::domain::service::{
NotificationReaderService, PlatformArnConfig, SqsNotificationIngress,
@@ -690,7 +690,7 @@ async fn main() -> anyhow::Result<()> {
tracing::info!("initialized onboarding service");
- let mcp_public_url = DocumentCognitionServiceUrl::new()?;
+ let mcp_public_url = &config.mcp_public_url;
let mcp_client_metadata = mcp_client::domain::models::OAuthClientMetadata::new(
format!("{mcp_public_url}/mcp/servers/auth/client-metadata"),
format!("{mcp_public_url}/mcp/servers/auth/callback"),
diff --git a/tooling/xtask/crates/xtask_local/src/local.rs b/tooling/xtask/crates/xtask_local/src/local.rs
index a3fb54a1cb..24dd28f3c8 100644
--- a/tooling/xtask/crates/xtask_local/src/local.rs
+++ b/tooling/xtask/crates/xtask_local/src/local.rs
@@ -15,6 +15,7 @@ use std::path::PathBuf;
pub mod arch;
pub mod build;
+pub mod cf_tunnel;
pub mod cli;
pub mod db;
pub mod docker;
@@ -155,7 +156,7 @@ use std::process::Command;
use anyhow::Result;
-use instance::Instance;
+use instance::{Instance, Port};
use stage::Stage;
/// Every non-Rust local service whose image is built from this repository.
@@ -227,10 +228,91 @@ pub fn run_stack(mode: Mode, args: &cli::RunArgs) -> Result<()> {
std::thread::spawn(move || teardown_commands(&instance))
});
+ // Sharing posture (`--with-cf-tunnel`, local only): besides the tunnels,
+ // the proxy additionally serves the headless static bundle, because that
+ // bundle — built against the `same-origin` sentinel — is the only frontend
+ // a remote visitor can actually use: the dev server's bundle calls the
+ // backend on an absolute `localhost:<proxy>` origin. The dev server still
+ // runs for the local developer. What a visitor can't do: follow
+ // backend-generated absolute links (invite/login emails point at
+ // `localhost:{FRONTEND_PORT}`) or the FusionAuth OAuth flow — passwordless
+ // login works, with the code readable at `<tunnel>/mailpit`.
+ let share_app = args.with_cf_tunnel && mode == Mode::Local;
+ if args.with_cf_tunnel && mode != Mode::Local {
+ stage.note("--with-cf-tunnel is ignored by run_dev (tunnels share a fully local stack)");
+ }
+
+ // The Cursor egress tunnel, before env resolution because the minted
+ // hostname is written into `EGRESS_BASE_URL`. Best-effort with a loud
+ // downgrade: a laptop with no route to Cloudflare should still get a
+ // working stack, minus the one thing that needs public ingress -
+ // `@cursor` sessions reaching local MCP servers.
+ let egress_tunnel = (share_app && !stage.is_dry_run())
+ .then(|| {
+ match cf_tunnel::open(&instance, "egress", instance.port(Port::AgentHarnessEgress)) {
+ Ok(tunnel) => {
+ stage.note(&format!("cursor egress tunnel: {}", tunnel.url));
+ Some(tunnel)
+ }
+ Err(error) => {
+ stage.note(&format!(
+ "WARNING: no cursor egress tunnel ({error:#}); EGRESS_BASE_URL stays \
+ in-network, so @cursor sessions cannot reach this stack's MCP servers"
+ ));
+ None
+ }
+ }
+ })
+ .flatten();
+
+ // The app tunnel does not feed the env, but it degrades the same way: a
+ // failure warns and the stack comes up localhost-only.
+ let app_tunnel = (share_app && !stage.is_dry_run())
+ .then(
+ || match cf_tunnel::open(&instance, "app", instance.port(Port::Proxy)) {
+ Ok(tunnel) => {
+ stage.note(&format!("shared app tunnel: {}/app/", tunnel.url));
+ Some(tunnel)
+ }
+ Err(error) => {
+ stage.note(&format!(
+ "WARNING: no shared app tunnel ({error:#}); the app stays reachable \
+ on localhost only"
+ ));
+ None
+ }
+ },
+ )
+ .flatten();
+
// Foreground: resolve env, build binaries + runtime image, generate the
// compose override / Caddyfile / kickstart. None of this touches the volumes
// or containers the teardown is removing, so it's safe to overlap.
- let (env, target) = prepare(&stage, mode, &instance, args, false, false, false)?;
+ let (env, target) = prepare(
+ &stage,
+ mode,
+ &instance,
+ args,
+ share_app,
+ false,
+ false,
+ egress_tunnel.as_ref().map(|tunnel| tunnel.url.as_str()),
+ )?;
+
+ // Build + stage the shareable bundle in the background (pure host-side
+ // work), joined just before `bring_up_app` creates the proxy container
+ // that mounts the staged dir. The bundle is a share-time snapshot: the
+ // `r` hotkey reloads service binaries, not this bundle — live frontend
+ // edits show on the dev server, not on the shared URL.
+ if share_app && stage.is_dry_run() {
+ frontend::build_static(&stage, &instance, mode)?;
+ }
+ let fe_build = (share_app && !stage.is_dry_run()).then(|| {
+ let instance = instance.clone();
+ std::thread::spawn(move || {
+ frontend::build_static(&Stage::from_env().quiet(), &instance, mode)
+ })
+ });
// Join the background teardown before we (re)create volumes + bring infra up,
// surfaced as a live spinner so it's clear what we're blocked on. It
@@ -254,6 +336,13 @@ pub fn run_stack(mode: Mode, args: &cli::RunArgs) -> Result<()> {
// otherwise the services race their backends on startup (no `macrodb`,
// DynamoDB/OpenSearch connection refused).
bring_up_infra(&stage, mode, &instance, &env, InfraInit::Full)?;
+ if let Some(handle) = fe_build {
+ stage.run_step("Building frontend (static bundle)", move || {
+ handle
+ .join()
+ .map_err(|_| anyhow::anyhow!("frontend build panicked"))?
+ })?;
+ }
bring_up_app(&stage, mode, &instance, &env)?;
let _sdk_webhook_tunnel = (mode == Mode::Local && !stage.is_dry_run())
.then(|| sdk_webhook::start(&instance))
@@ -281,12 +370,24 @@ pub fn run_stack(mode: Mode, args: &cli::RunArgs) -> Result<()> {
)?
};
+ // Sharing moves the Mailpit UI under `/mailpit` (MP_WEBROOT, so a remote
+ // visitor can read their login code through the proxy); show the URL that
+ // actually resolves.
+ let mailpit_url = if share_app {
+ mailpit::proxy_ui_url(&instance)
+ } else {
+ mailpit::direct_ui_url(&instance)
+ };
+ let shared_app_url = app_tunnel
+ .as_ref()
+ .map(|tunnel| format!("{}/app/", tunnel.url));
summary::print(
mode,
&instance,
&env,
&frontend::url(&instance),
- &mailpit::direct_ui_url(&instance),
+ &mailpit_url,
+ shared_app_url.as_deref(),
);
match frontend {
@@ -493,9 +594,14 @@ fn interact(
/// Caddyfile / kickstart. Deliberately does NOT create the external
/// networks/volumes — that's done after the background teardown joins, since
/// teardown removes them. `static_frontend` wires the proxy to serve the staged
-/// app bundle (headless `stack up`). `infra_only` skips zigbuild: bake never
+/// app bundle (headless `stack up`, and `run_local --with-cf-tunnel`'s shared
+/// app). `infra_only` skips zigbuild: bake never
/// starts Rust services and runs in parallel with the cargo lane. Returns the
/// resolved env + build target.
+///
+/// One argument per independent knob; bundling some into a struct would only
+/// move the same list one level down.
+#[allow(clippy::too_many_arguments)]
fn prepare(
stage: &Stage,
mode: Mode,
@@ -504,6 +610,7 @@ fn prepare(
static_frontend: bool,
pull_app_images: bool,
infra_only: bool,
+ egress_public_url: Option<&str>,
) -> Result<(env_layer::ResolvedEnv, arch::Target)> {
let env = env_layer::resolve(
mode,
@@ -511,6 +618,7 @@ fn prepare(
args.env.no_doppler,
args.env.env_file.as_deref(),
static_frontend,
+ egress_public_url,
)?;
stage.note(&format!("env: {}", env_layer::summarize(&env.merged)));
sandbox_image::ensure(stage, &env.merged, args.build.no_build)?;
@@ -548,7 +656,8 @@ fn prepare(
}
if mode.spec().runs_local_infra {
let google = kickstart::GoogleIdp::from_env(&env.merged);
- fusionauth::write_kickstart(instance, google.as_ref())?;
+ let github = kickstart::GithubIdp::from_env(&env.merged);
+ fusionauth::write_kickstart(instance, google.as_ref(), github.as_ref())?;
}
if args.build.build_aux_services {
build_aux_service_images(stage, instance, &env)?;
@@ -625,7 +734,6 @@ fn bring_up_infra(
if stage.is_dry_run() {
return Ok(());
}
- use instance::Port;
let spec = mode.spec();
// `--wait` gates on each service's healthcheck. Postgres (`pg_isready`) and
diff --git a/tooling/xtask/crates/xtask_local/src/local/cf_tunnel.rs b/tooling/xtask/crates/xtask_local/src/local/cf_tunnel.rs
new file mode 100644
index 0000000000..cbaa5ec23e
--- /dev/null
+++ b/tooling/xtask/crates/xtask_local/src/local/cf_tunnel.rs
@@ -0,0 +1,164 @@
+//! Cloudflare quick tunnels: opt-in public ingress into a local stack.
+//!
+//! Nothing here runs unless `--with-cf-tunnel` is passed — a plain `run_local`
+//! never dials out. With the flag, two tunnels open:
+//!
+//! - **egress**: a `@cursor` session runs on cursor.com, not in the compose
+//! network, and the MCP servers the harness hands it point at
+//! `EGRESS_BASE_URL`. In-network that URL is
+//! `http://agent-harness-service:8102`, which means nothing to Cursor's VM —
+//! so the tunnel targets the instance's published egress port and
+//! `EGRESS_BASE_URL` resolves to the minted `https://….trycloudflare.com`
+//! hostname instead.
+//! - **app**: the single-origin reverse proxy (Caddy), so the whole running
+//! product can be shared with someone who is not on this machine. The proxy
+//! — not the Vite dev server — is the only target that works remotely: the
+//! dev bundle calls the backend on an absolute `localhost:<proxy>` origin
+//! (`VITE_LOCAL_BACKEND_ORIGIN`), which a remote browser cannot reach. The
+//! share therefore serves the headless static bundle through the proxy,
+//! built against the `same-origin` sentinel, so every API and WebSocket call
+//! follows whatever hostname the visitor loaded the page from.
+//!
+//! *Quick* tunnels deliberately: no account, no DNS record, a fresh random
+//! hostname per run — which is fine because the env is regenerated per run
+//! too, so nothing can go stale. The trade is that local sandboxes now also
+//! reach the proxy out through Cloudflare and back; one extra hop on a dev
+//! stack, and one URL both renderings agree on.
+//!
+//! Same lifecycle as the SDK webhook tunnel: started before the env is
+//! resolved (the egress URL has to be known to be written into it), pid-filed
+//! per tunnel name so the next run reaps a leaked one, and killed when the
+//! guard drops.
+
+use std::io::{BufRead, BufReader, Read};
+use std::path::PathBuf;
+use std::process::{Child, Command, Stdio};
+use std::sync::mpsc;
+use std::time::Duration;
+
+use anyhow::{Context, Result, bail};
+
+use super::instance::Instance;
+
+#[cfg(test)]
+mod test;
+
+/// How long the quick tunnel gets to mint its hostname. Ordinarily it takes a
+/// couple of seconds; well past this it is not coming (no network, Cloudflare
+/// unreachable), and the caller downgrades to localhost-only with a warning.
+const HOSTNAME_DEADLINE: Duration = Duration::from_secs(30);
+
+/// A running quick tunnel. Dropping it kills the `cloudflared` process, which
+/// is what tears the public hostname down.
+pub struct QuickTunnel {
+ child: Child,
+ /// The minted public origin, e.g. `https://odds-and-ends.trycloudflare.com`.
+ pub url: String,
+}
+
+impl Drop for QuickTunnel {
+ fn drop(&mut self) {
+ let _ = self.child.kill();
+ let _ = self.child.wait();
+ }
+}
+
+/// Where the tunnel's pid is recorded, keyed by name so the egress and app
+/// tunnels reap independently.
+fn pid_path(instance: &Instance, name: &str) -> PathBuf {
+ instance.artifact_dir().join(format!("{name}-tunnel.pid"))
+}
+
+/// Open a named quick tunnel to a local port and wait for the minted hostname.
+/// Reaps a same-named tunnel leaked by a previous run first, so at most one
+/// per (instance, name) exists.
+pub fn open(instance: &Instance, name: &str, port: u16) -> Result<QuickTunnel> {
+ reap_stale(instance, name);
+ let mut child = Command::new("cloudflared")
+ .args([
+ "tunnel",
+ "--no-autoupdate",
+ "--url",
+ &format!("http://localhost:{port}"),
+ ])
+ .stdout(Stdio::null())
+ .stderr(Stdio::piped())
+ .spawn()
+ .context("starting cloudflared (is it in the dev shell?)")?;
+
+ let stderr = child
+ .stderr
+ .take()
+ .context("cloudflared spawned without a stderr pipe")?;
+
+ match await_hostname(stderr) {
+ Ok(url) => {
+ let _ = std::fs::write(pid_path(instance, name), child.id().to_string());
+ Ok(QuickTunnel { child, url })
+ }
+ Err(error) => {
+ let _ = child.kill();
+ let _ = child.wait();
+ Err(error)
+ }
+ }
+}
+
+/// Kill a previously started tunnel, if one leaked past its process.
+fn reap_stale(instance: &Instance, name: &str) {
+ let path = pid_path(instance, name);
+ let Some(pid) = std::fs::read_to_string(&path)
+ .ok()
+ .and_then(|p| p.trim().parse::<i32>().ok())
+ else {
+ return;
+ };
+ let _ = Command::new("kill")
+ .args(["-TERM", &pid.to_string()])
+ .status();
+ let _ = std::fs::remove_file(path);
+}
+
+/// Read cloudflared's log until the quick-tunnel hostname appears.
+///
+/// The reader thread outlives this function on purpose: cloudflared keeps
+/// logging for the life of the tunnel, and a pipe nobody drains eventually
+/// blocks the process, which would take the tunnel down mid-run. After the
+/// hostname is found the same thread keeps draining to the sink.
+fn await_hostname(stderr: impl Read + Send + 'static) -> Result<String> {
+ let (found, hostname) = mpsc::channel::<Option<String>>();
+ std::thread::spawn(move || {
+ let mut looking = true;
+ for line in BufReader::new(stderr).lines() {
+ let Ok(line) = line else { break };
+ if looking && let Some(url) = quick_tunnel_url(&line) {
+ looking = false;
+ let _ = found.send(Some(url));
+ }
+ }
+ // EOF with no hostname: cloudflared died. Unblock the wait so the
+ // caller reports that instead of sitting out the whole deadline.
+ let _ = found.send(None);
+ });
+
+ match hostname.recv_timeout(HOSTNAME_DEADLINE) {
+ Ok(Some(url)) => Ok(url),
+ Ok(None) => bail!("cloudflared exited before minting a quick-tunnel hostname"),
+ Err(mpsc::RecvTimeoutError::Timeout) => bail!(
+ "cloudflared did not mint a quick-tunnel hostname within {}s",
+ HOSTNAME_DEADLINE.as_secs()
+ ),
+ Err(mpsc::RecvTimeoutError::Disconnected) => {
+ bail!("cloudflared's log reader stopped before a hostname appeared")
+ }
+ }
+}
+
+/// The quick-tunnel origin in one of cloudflared's log lines, if this line
+/// carries it. The line looks like
+/// `2026-08-27T00:00:00Z INF | https://odds-and-ends.trycloudflare.com |`.
+fn quick_tunnel_url(line: &str) -> Option<String> {
+ line.split_whitespace()
+ .find(|token| token.starts_with("https://") && token.ends_with(".trycloudflare.com"))
+ .map(str::to_owned)
+}
diff --git a/tooling/xtask/crates/xtask_local/src/local/cf_tunnel/test.rs b/tooling/xtask/crates/xtask_local/src/local/cf_tunnel/test.rs
new file mode 100644
index 0000000000..82a364675b
--- /dev/null
+++ b/tooling/xtask/crates/xtask_local/src/local/cf_tunnel/test.rs
@@ -0,0 +1,41 @@
+use super::*;
+
+#[test]
+fn finds_the_minted_hostname_in_cloudflareds_banner() {
+ let line = "2026-08-27T00:00:00Z INF | https://odds-and-ends.trycloudflare.com |";
+ assert_eq!(
+ quick_tunnel_url(line).as_deref(),
+ Some("https://odds-and-ends.trycloudflare.com")
+ );
+}
+
+/// The banner also mentions the docs page and the local target - neither of
+/// which is the tunnel.
+#[test]
+fn ignores_every_other_url_cloudflared_logs() {
+ for line in [
+ "INF Requesting new quick Tunnel on trycloudflare.com...",
+ "INF | https://developers.cloudflare.com/cloudflare-one/ |",
+ "INF Route propagating http://localhost:8102",
+ "",
+ ] {
+ assert_eq!(quick_tunnel_url(line), None, "{line}");
+ }
+}
+
+/// A hostname that died at spawn reports the death, not a 30s wait.
+#[test]
+fn a_closed_log_reports_the_exit_immediately() {
+ let started = std::time::Instant::now();
+ let refusal = await_hostname(std::io::empty()).expect_err("refused");
+ assert!(refusal.to_string().contains("exited"), "{refusal}");
+ assert!(started.elapsed() < Duration::from_secs(5));
+}
+
+#[test]
+fn a_log_carrying_the_hostname_resolves_it() {
+ let log = "INF Requesting new quick Tunnel on trycloudflare.com...\n\
+ INF | https://odds-and-ends.trycloudflare.com |\n";
+ let url = await_hostname(std::io::Cursor::new(log.to_owned())).expect("resolved");
+ assert_eq!(url, "https://odds-and-ends.trycloudflare.com");
+}
diff --git a/tooling/xtask/crates/xtask_local/src/local/cli.rs b/tooling/xtask/crates/xtask_local/src/local/cli.rs
index 8cd5a9f9a2..eaf0b71581 100644
--- a/tooling/xtask/crates/xtask_local/src/local/cli.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/cli.rs
@@ -126,6 +126,12 @@ pub struct RunArgs {
/// for what each backend does.
#[arg(long)]
pub traces: Option<TracesBackend>,
+ /// Open Cloudflare quick tunnels into this stack: one for `@cursor`
+ /// sessions (a public `EGRESS_BASE_URL`) and one sharing the app itself
+ /// through the reverse proxy. Off by default — nothing dials out and the
+ /// stack stays localhost-only. `run_local` only.
+ #[arg(long)]
+ pub with_cf_tunnel: bool,
}
/// Which OTLP trace collector `--traces` should bring up.
diff --git a/tooling/xtask/crates/xtask_local/src/local/cli/test.rs b/tooling/xtask/crates/xtask_local/src/local/cli/test.rs
index bea8485439..0cfd543c09 100644
--- a/tooling/xtask/crates/xtask_local/src/local/cli/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/cli/test.rs
@@ -55,6 +55,24 @@ fn run_local_defaults_onboarding_off() {
assert!(!args.enable_onboarding);
}
+#[test]
+fn run_local_defaults_cf_tunnels_off() {
+ let cli = Cli::try_parse_from(["cargo-x", "run-local"]).unwrap();
+ let Cmd::RunLocal(args) = cli.command else {
+ panic!("expected run-local command");
+ };
+ assert!(!args.with_cf_tunnel);
+}
+
+#[test]
+fn run_local_accepts_with_cf_tunnel() {
+ let cli = Cli::try_parse_from(["cargo-x", "run-local", "--with-cf-tunnel"]).unwrap();
+ let Cmd::RunLocal(args) = cli.command else {
+ panic!("expected run-local command");
+ };
+ assert!(args.with_cf_tunnel);
+}
+
#[test]
fn run_local_accepts_enable_onboarding() {
let cli = Cli::try_parse_from(["cargo-x", "run-local", "--enable-onboarding"]).unwrap();
diff --git a/tooling/xtask/crates/xtask_local/src/local/e2e.rs b/tooling/xtask/crates/xtask_local/src/local/e2e.rs
index 644869e53f..7d367a7ce3 100644
--- a/tooling/xtask/crates/xtask_local/src/local/e2e.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/e2e.rs
@@ -125,6 +125,7 @@ pub fn run(args: &LocalE2eArgs) -> Result<()> {
enable_onboarding: false,
traces: None,
verbose: false,
+ with_cf_tunnel: false,
},
..stack::UpArgs::default()
};
diff --git a/tooling/xtask/crates/xtask_local/src/local/env_layer.rs b/tooling/xtask/crates/xtask_local/src/local/env_layer.rs
index 5489e5a50a..5b0a1b4135 100644
--- a/tooling/xtask/crates/xtask_local/src/local/env_layer.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/env_layer.rs
@@ -46,6 +46,7 @@ pub fn resolve(
no_doppler: bool,
env_file: Option<&Path>,
static_frontend: bool,
+ egress_public_url: Option<&str>,
) -> Result<ResolvedEnv> {
// Base = Doppler (`lcl_personal`/`dev_personal`); it supplies the
// integration/secret config services require. For local we then overlay the
@@ -54,9 +55,9 @@ pub fn resolve(
// has — unlike the old defaults.env, which Doppler overrode). Dev keeps
// Doppler as-is.
let spec = mode.spec();
- let local = spec
- .overlay_local_env
- .then(|| local_env::LocalEnv::for_instance(mode, instance, static_frontend));
+ let local = spec.overlay_local_env.then(|| {
+ local_env::LocalEnv::for_instance(mode, instance, static_frontend, egress_public_url)
+ });
let mut env = BTreeMap::new();
// Boot stubs go in FIRST so Doppler overrides them: they only exist to keep
// a `--no-doppler` stack's config loaders satisfied, never to replace a
diff --git a/tooling/xtask/crates/xtask_local/src/local/fusionauth.rs b/tooling/xtask/crates/xtask_local/src/local/fusionauth.rs
index f276d3d10d..35e22ee2ff 100644
--- a/tooling/xtask/crates/xtask_local/src/local/fusionauth.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/fusionauth.rs
@@ -27,10 +27,15 @@ fn read_lambda(file: xtask_paths::RepoFile<'static>) -> Result<String> {
/// FusionAuth container mounts. The kickstart is pure identity-provider config:
/// run_local pre-seeds no users — passwordless login auto-creates any user on
/// demand. `google` (from the resolved run env) additionally configures the
-/// `google`/`google_gmail` OIDC IdPs so the email connect flows work locally;
-/// the generated file is gitignored, and the init-snapshot key hashes it, so
-/// adding/removing the Google client re-inits the stack automatically.
-pub fn write_kickstart(instance: &Instance, google: Option<&kickstart::GoogleIdp>) -> Result<()> {
+/// `google`/`google_gmail` OIDC IdPs so the email connect flows work locally,
+/// and `github` the `github` IdP that `POST /link/github` resolves; the
+/// generated file is gitignored, and the init-snapshot key hashes it, so
+/// adding/removing either client re-inits the stack automatically.
+pub fn write_kickstart(
+ instance: &Instance,
+ google: Option<&kickstart::GoogleIdp>,
+ github: Option<&kickstart::GithubIdp>,
+) -> Result<()> {
let dir = gen_compose::kickstart_dir(instance);
std::fs::create_dir_all(&dir)
.with_context(|| format!("creating kickstart dir {}", dir.display()))?;
@@ -41,6 +46,7 @@ pub fn write_kickstart(instance: &Instance, google: Option<&kickstart::GoogleIdp
&read_lambda(POPULATE_JWT_LAMBDA)?,
&read_lambda(RECONCILE_LAMBDA)?,
google,
+ github,
);
let json = serde_json::to_string_pretty(&doc)? + "\n";
std::fs::write(dir.join("kickstart.json"), json)
diff --git a/tooling/xtask/crates/xtask_local/src/local/gen_compose.rs b/tooling/xtask/crates/xtask_local/src/local/gen_compose.rs
index f8589335a4..d52d67ae49 100644
--- a/tooling/xtask/crates/xtask_local/src/local/gen_compose.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/gen_compose.rs
@@ -26,6 +26,11 @@ use super::instance::{Instance, Port};
use super::inventory::services_for_mode;
use super::{Mode, repo_root};
+/// The one Rust service with a second listener: the agent egress proxy inside
+/// `agent_harness_service`, on the container port `EGRESS_PORT` defaults to.
+const EGRESS_SERVICE: &str = "agent_harness_service";
+const EGRESS_CONTAINER_PORT: u16 = 8102;
+
pub const LOCALSTACK_IMAGE: &str = "localstack/localstack:4";
pub const MAILPIT_IMAGE: &str = "axllent/mailpit:v1.20";
pub const CADDY_IMAGE: &str = "caddy:2-alpine";
@@ -79,11 +84,26 @@ pub fn generate(
// Named instances need their own host ports (replacing the base ports —
// emitted as `!override` in apply_tags). Only the self-contained local
// stacks remap; dev inherits the base-compose ports.
+ let mut ports = Vec::new();
if mode.spec().runs_local_infra
&& !instance.is_default()
&& let Some(port) = svc.host_port
{
- s.ports = dct::Ports::Short(vec![format!("{}:8080", instance.port(port))]);
+ ports.push(format!("{}:8080", instance.port(port)));
+ }
+ // The agent egress proxy is the harness's second listener, and the one
+ // service port a party outside the compose network has to reach: the
+ // egress tunnel forwards Cursor's cloud to this host port. Published on
+ // every local instance, default included - the base compose publishes
+ // nothing for the harness.
+ if mode.spec().runs_local_infra && svc.compose_name == EGRESS_SERVICE {
+ ports.push(format!(
+ "{}:{EGRESS_CONTAINER_PORT}",
+ instance.port(Port::AgentHarnessEgress)
+ ));
+ }
+ if !ports.is_empty() {
+ s.ports = dct::Ports::Short(ports);
}
services.insert(svc.compose_name.to_string(), Some(s));
}
diff --git a/tooling/xtask/crates/xtask_local/src/local/identity.rs b/tooling/xtask/crates/xtask_local/src/local/identity.rs
index 5b6bcab098..b27684fa69 100644
--- a/tooling/xtask/crates/xtask_local/src/local/identity.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/identity.rs
@@ -56,6 +56,16 @@ pub const GOOGLE_GMAIL_IDP_ID: &str = "55555555-5555-4555-8555-555555555555";
/// sign-in with a Google account that is linked as a secondary inbox).
pub const RECONCILE_LAMBDA_ID: &str = "66666666-6666-4666-8666-666666666666";
+/// Fixed id for the `github` identity provider. Only created when a real
+/// GitHub OAuth client is configured (see `kickstart::GithubIdp`).
+///
+/// Read from both ends, which is why it is here rather than written twice:
+/// `authentication_service` resolves the provider *by name* when it starts a
+/// link, and separately takes this id from `GITHUB_IDP_ID` for the link calls
+/// themselves. The kickstart therefore has to create one provider that is both
+/// named `github` and has this id, or the two halves address different things.
+pub const GITHUB_IDP_ID: &str = "99999999-9999-4999-8999-999999999999";
+
/// Local from-address for FusionAuth-sent mail (lands in Mailpit).
pub const MAIL_FROM: &str = "[email protected]";
diff --git a/tooling/xtask/crates/xtask_local/src/local/instance.rs b/tooling/xtask/crates/xtask_local/src/local/instance.rs
index 113f70c5a8..7c48a53c73 100644
--- a/tooling/xtask/crates/xtask_local/src/local/instance.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/instance.rs
@@ -104,6 +104,10 @@ pub enum Port {
AgentProxy = 8091,
/// Agent session control API.
AgentHarness = 8101,
+ /// The agent egress proxy, `agent_harness_service`'s second listener.
+ /// Published on every local instance - it is what the Cursor egress
+ /// tunnel points at, and Cursor's cloud is outside the compose network.
+ AgentHarnessEgress = 8102,
}
impl Port {
diff --git a/tooling/xtask/crates/xtask_local/src/local/inventory.rs b/tooling/xtask/crates/xtask_local/src/local/inventory.rs
index 6fcf04dfec..fa0d6eccec 100644
--- a/tooling/xtask/crates/xtask_local/src/local/inventory.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/inventory.rs
@@ -258,6 +258,21 @@ pub const RUST_SERVICES: &[RustService] = &[
opt_in: false,
no_default_features: false,
},
+ RustService {
+ compose_name: "mcp_service",
+ cargo_bin: "mcp_service",
+ package: "mcp_service",
+ // No host port and no proxy route: its one local client is the agent
+ // egress proxy, which dials it across the compose network as
+ // `mcp-service`. (Interactive MCP clients like claude.ai only exist
+ // against deployed environments.)
+ host_port: None,
+ path_prefix: None,
+ is_websocket: false,
+ modes: &[Mode::Local],
+ opt_in: false,
+ no_default_features: false,
+ },
];
/// The Rust services that participate in `mode` (opt-in services list no modes,
diff --git a/tooling/xtask/crates/xtask_local/src/local/inventory/test.rs b/tooling/xtask/crates/xtask_local/src/local/inventory/test.rs
index e4f9d245b0..3c0c7bdd1b 100644
--- a/tooling/xtask/crates/xtask_local/src/local/inventory/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/inventory/test.rs
@@ -3,15 +3,16 @@ use super::*;
#[test]
fn local_binaries_are_unique_and_complete() {
let bins = local_binaries();
- // 15 distinct binaries (the bundled set, including the local-only
- // search_processing_service, agent harness, and the seed_cli
+ // 16 distinct binaries (the bundled set, including the local-only
+ // search_processing_service, agent harness, mcp_service, and the seed_cli
// shipped for the gmail_forwarder sidecar).
- assert_eq!(bins.len(), 15, "{bins:?}");
+ assert_eq!(bins.len(), 16, "{bins:?}");
assert!(bins.contains(&"pubsub_workers"));
assert!(bins.contains(&"seed_cli"));
assert!(bins.contains(&"document_upload_finalizer_local_worker"));
assert!(bins.contains(&"search_processing_service"));
assert!(bins.contains(&"agent_harness_service"));
+ assert!(bins.contains(&"mcp_service"));
let mut sorted = bins.clone();
sorted.dedup();
assert_eq!(sorted.len(), bins.len(), "binaries must be deduplicated");
diff --git a/tooling/xtask/crates/xtask_local/src/local/kickstart.rs b/tooling/xtask/crates/xtask_local/src/local/kickstart.rs
index 0f2cfe430a..07c2d637b5 100644
--- a/tooling/xtask/crates/xtask_local/src/local/kickstart.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/kickstart.rs
@@ -51,6 +51,60 @@ impl GoogleIdp {
}
}
+/// The GitHub OAuth app the local `github` identity provider authenticates
+/// against. Optional on the same terms as [`GoogleIdp`]: without it the
+/// kickstart is unchanged and `POST /link/github` stays unreachable locally.
+pub struct GithubIdp {
+ pub client_id: String,
+ pub client_secret: String,
+ pub idp_id: String,
+}
+
+impl GithubIdp {
+ /// Extract the GitHub OAuth client from the resolved run env. The same
+ /// `GITHUB_CLIENT_ID`/`GITHUB_CLIENT_SECRET` pair `authentication_service`
+ /// builds its authorization URL from - the provider and the service have to
+ /// agree on the client or the callback cannot be linked.
+ ///
+ /// The id comes from the same env rather than from [`identity`], because
+ /// unlike the Google providers - which are only ever resolved by name -
+ /// `authentication_service` reads `GITHUB_IDP_ID` as config, and Doppler
+ /// overrides it with the dev instance's id. Pinning our own constant here
+ /// would create the provider somewhere the service never looks: the
+ /// by-name lookup that starts a link would succeed while every link call
+ /// addressed a provider that does not exist. The constant is the fallback
+ /// for a stack with no Doppler layer.
+ ///
+ /// The `local-` check is load-bearing, not cosmetic: a no-Doppler stack
+ /// fills both with `local-github-client…` placeholders so the service's
+ /// config loader is satisfied, and creating the provider with those would
+ /// bake a broken FusionAuth config into the init snapshot - which then
+ /// looks like a *configured* GitHub connector that fails at the callback,
+ /// rather than one that is plainly absent.
+ pub fn from_env(env: &BTreeMap<String, String>) -> Option<Self> {
+ let client_id = env.get("GITHUB_CLIENT_ID")?.trim().to_string();
+ let client_secret = env.get("GITHUB_CLIENT_SECRET")?.trim().to_string();
+ if client_id.is_empty()
+ || client_secret.is_empty()
+ || client_id.starts_with("local-")
+ || client_secret.starts_with("local-")
+ {
+ return None;
+ }
+ let idp_id = env
+ .get("GITHUB_IDP_ID")
+ .map(|id| id.trim())
+ .filter(|id| !id.is_empty())
+ .unwrap_or(identity::GITHUB_IDP_ID)
+ .to_string();
+ Some(GithubIdp {
+ client_id,
+ client_secret,
+ idp_id,
+ })
+ }
+}
+
/// Build the kickstart document. `lambda_body` is the JS source of
/// `populate_jwt_local.js`; `reconcile_lambda_body` is the reconcile lambda
/// attached to `google_gmail` (only used when `google` is configured); redirect
@@ -61,6 +115,7 @@ pub fn build(
lambda_body: &str,
reconcile_lambda_body: &str,
google: Option<&GoogleIdp>,
+ github: Option<&GithubIdp>,
) -> Value {
let app_id = identity::APPLICATION_ID;
let tenant_id = identity::TENANT_ID;
@@ -330,6 +385,58 @@ pub fn build(
}));
}
+ // The `github` identity provider, when a real GitHub client is configured
+ // (see `GithubIdp::from_env`). Generic OIDC with GitHub's endpoints spelled
+ // out, like the Google providers above - FusionAuth has no GitHub provider
+ // type at all (it rejects one with `[invalidJSON]`, listing the types it
+ // does accept), and GitHub publishes no discovery document to point at.
+ // Nothing drives this provider's own OAuth flow: Macro builds the
+ // authorization URL and only uses FusionAuth to record the resulting link,
+ // so these endpoints exist to make the provider well-formed rather than to
+ // be dialled.
+ //
+ // The name is fixed and the id is the service's own `GITHUB_IDP_ID`.
+ // `authentication_service` resolves this provider by name to start a link,
+ // then addresses it by that id for the link itself, so one provider has to
+ // answer to both. Macro builds the authorization URL itself and only uses
+ // FusionAuth to record the link, which is why the client here must be the
+ // same one the service holds.
+ if let Some(github) = github {
+ requests.push(json!({
+ "method": "POST",
+ "url": format!("/api/identity-provider/{}", github.idp_id),
+ "body": { "identityProvider": {
+ "type": "OpenIDConnect",
+ "name": "github",
+ "enabled": true,
+ "debug": true,
+ "buttonText": "GitHub",
+ "linkingStrategy": "LinkByEmail",
+ "oauth2": {
+ "authorization_endpoint": "https://github.com/login/oauth/authorize",
+ "token_endpoint": "https://github.com/login/oauth/access_token",
+ "userinfo_endpoint": "https://api.github.com/user",
+ "client_id": github.client_id.as_str(),
+ "client_secret": github.client_secret.as_str(),
+ "clientAuthenticationMethod": "client_secret_basic",
+ // Enough to identify the account being linked. A GitHub
+ // user can keep their address private, so the email scope
+ // is explicit rather than assumed.
+ "scope": "read:user user:email",
+ // GitHub's `/user` names these differently from OIDC: `id`
+ // rather than `sub`, `login` rather than
+ // `preferred_username`.
+ "uniqueIdClaim": "id",
+ "emailClaim": "email",
+ "usernameClaim": "login",
+ },
+ "applicationConfiguration": json!({
+ identity::APPLICATION_ID: { "enabled": true, "createRegistration": true }
+ }),
+ }}
+ }));
+ }
+
json!({
"//": "GENERATED by xtask (cargo x run-local). Deterministic local FusionAuth bootstrap. Do not edit.",
"apiKeys": [ { "key": identity::FUSIONAUTH_API_KEY, "description": "Local Development API Key" } ],
diff --git a/tooling/xtask/crates/xtask_local/src/local/kickstart/test.rs b/tooling/xtask/crates/xtask_local/src/local/kickstart/test.rs
index dcba8a6e7a..e5c61b28d8 100644
--- a/tooling/xtask/crates/xtask_local/src/local/kickstart/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/kickstart/test.rs
@@ -45,6 +45,7 @@ fn kickstart_without_google_has_no_idp_requests() {
"function populate() {}",
"function reconcile() {}",
None,
+ None,
);
let urls: Vec<&str> = doc["requests"]
.as_array()
@@ -70,6 +71,7 @@ fn kickstart_with_google_adds_lambda_and_both_idps_after_the_application() {
"function populate() {}",
"function reconcile() {}",
Some(&google),
+ None,
);
let requests = doc["requests"].as_array().unwrap();
@@ -120,6 +122,7 @@ fn kickstart_adopts_the_default_tenant() {
"function populate() {}",
"function reconcile() {}",
None,
+ None,
);
assert_eq!(
doc["variables"]["defaultTenantId"],
@@ -137,3 +140,142 @@ fn kickstart_adopts_the_default_tenant() {
"the tenant is reconfigured in place, not created — local stays single-tenant"
);
}
+
+/// A no-Doppler stack fills these with placeholders so the service's config
+/// loader is satisfied. Building the provider from them would bake a broken
+/// FusionAuth config into the init snapshot, which reads as a *configured*
+/// GitHub connector that fails at the callback rather than an absent one.
+#[test]
+fn github_idp_requires_a_real_client() {
+ assert!(GithubIdp::from_env(&env(&[])).is_none());
+ assert!(
+ GithubIdp::from_env(&env(&[
+ ("GITHUB_CLIENT_ID", "local-github-client"),
+ ("GITHUB_CLIENT_SECRET", "local-github-client-secret"),
+ ]))
+ .is_none()
+ );
+ assert!(
+ GithubIdp::from_env(&env(&[
+ ("GITHUB_CLIENT_ID", "Iv23livpJoVJw98dlKCk"),
+ ("GITHUB_CLIENT_SECRET", "local-github-client-secret"),
+ ]))
+ .is_none()
+ );
+ assert!(
+ GithubIdp::from_env(&env(&[
+ ("GITHUB_CLIENT_ID", ""),
+ ("GITHUB_CLIENT_SECRET", "realsecret"),
+ ]))
+ .is_none()
+ );
+
+ let ok = GithubIdp::from_env(&env(&[
+ ("GITHUB_CLIENT_ID", "Iv23livpJoVJw98dlKCk"),
+ ("GITHUB_CLIENT_SECRET", "a-real-github-secret"),
+ ]))
+ .expect("a real github client must parse");
+ assert_eq!(ok.client_id, "Iv23livpJoVJw98dlKCk");
+ assert_eq!(ok.client_secret, "a-real-github-secret");
+ // No Doppler layer, so the local constant stands in.
+ assert_eq!(ok.idp_id, identity::GITHUB_IDP_ID);
+}
+
+/// `authentication_service` reads `GITHUB_IDP_ID` as config and Doppler
+/// overrides it with the dev instance's id. Creating the provider at our own
+/// constant instead would put it somewhere the service never looks: starting a
+/// link (by name) would work while every link call addressed nothing.
+#[test]
+fn the_github_idp_id_follows_the_env_the_service_reads() {
+ let github = GithubIdp::from_env(&env(&[
+ ("GITHUB_CLIENT_ID", "Iv23livpJoVJw98dlKCk"),
+ ("GITHUB_CLIENT_SECRET", "a-real-github-secret"),
+ ("GITHUB_IDP_ID", "c8014fe7-aeb4-4898-a460-4047e0fdf6d8"),
+ ]))
+ .expect("a real github client must parse");
+ assert_eq!(github.idp_id, "c8014fe7-aeb4-4898-a460-4047e0fdf6d8");
+
+ let doc = build(
+ 3000,
+ 8080,
+ "function populate() {}",
+ "function reconcile() {}",
+ None,
+ Some(&github),
+ );
+ assert!(
+ doc["requests"]
+ .as_array()
+ .expect("requests")
+ .iter()
+ .any(|request| request["url"].as_str()
+ == Some("/api/identity-provider/c8014fe7-aeb4-4898-a460-4047e0fdf6d8"))
+ );
+}
+
+/// `authentication_service` resolves this provider by name to start a link and
+/// then addresses it by `GITHUB_IDP_ID` for the link itself, so one provider
+/// has to answer to both or the two halves address different things.
+#[test]
+fn the_github_idp_is_created_under_both_the_name_and_the_id_the_service_uses() {
+ let github = GithubIdp {
+ client_id: "Iv23livpJoVJw98dlKCk".to_string(),
+ client_secret: "a-real-github-secret".to_string(),
+ idp_id: identity::GITHUB_IDP_ID.to_string(),
+ };
+ let doc = build(
+ 3000,
+ 8080,
+ "function populate() {}",
+ "function reconcile() {}",
+ None,
+ Some(&github),
+ );
+
+ let requests = doc["requests"].as_array().expect("requests");
+ let idp = requests
+ .iter()
+ .find(|request| {
+ request["url"]
+ .as_str()
+ .is_some_and(|url| url.ends_with(identity::GITHUB_IDP_ID))
+ })
+ .expect("the github identity provider must be created at its fixed id");
+
+ let provider = &idp["body"]["identityProvider"];
+ assert_eq!(provider["name"], "github");
+ // FusionAuth has no GitHub provider type; it rejects one outright.
+ assert_eq!(provider["type"], "OpenIDConnect");
+ assert_eq!(provider["enabled"], true);
+ // The provider and the service must share one OAuth client.
+ assert_eq!(provider["oauth2"]["client_id"], "Iv23livpJoVJw98dlKCk");
+ assert_eq!(provider["oauth2"]["client_secret"], "a-real-github-secret");
+ assert_eq!(
+ provider["applicationConfiguration"][identity::APPLICATION_ID]["enabled"],
+ true
+ );
+}
+
+/// Absent client, absent provider - the connector is plainly unavailable
+/// rather than misconfigured.
+#[test]
+fn kickstart_without_github_creates_no_github_idp() {
+ let doc = build(
+ 3000,
+ 8080,
+ "function populate() {}",
+ "function reconcile() {}",
+ None,
+ None,
+ );
+
+ assert!(
+ !doc["requests"]
+ .as_array()
+ .expect("requests")
+ .iter()
+ .any(|request| request["url"]
+ .as_str()
+ .is_some_and(|url| url.contains(identity::GITHUB_IDP_ID)))
+ );
+}
diff --git a/tooling/xtask/crates/xtask_local/src/local/local_env.rs b/tooling/xtask/crates/xtask_local/src/local/local_env.rs
index b0187abb0e..e54ac24781 100644
--- a/tooling/xtask/crates/xtask_local/src/local/local_env.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/local_env.rs
@@ -29,6 +29,8 @@ pub struct LocalEnv {
/// `http://localhost:{FRONTEND_PORT}`, so this must track the serving
/// mode or every OAuth signup dead-ends on an unused port.
frontend_port: u16,
+ /// Browser-facing route to document cognition's MCP OAuth callback.
+ mcp_public_url: String,
infra: InfraEnv,
storage: StorageEnv,
queues: QueueEnv,
@@ -42,7 +44,17 @@ pub struct LocalEnv {
impl LocalEnv {
/// Build the local env for `instance` in `Local` mode (dev sources its env
/// from Doppler, not here).
- pub fn for_instance(mode: Mode, instance: &Instance, static_frontend: bool) -> Self {
+ ///
+ /// `egress_public_url` is the run's Cursor egress tunnel, when one opened:
+ /// it replaces the in-network egress address so the MCP servers the
+ /// harness hands a Cursor cloud agent are reachable from outside the
+ /// compose network. `None` (no tunnel) keeps the in-network address.
+ pub fn for_instance(
+ mode: Mode,
+ instance: &Instance,
+ static_frontend: bool,
+ egress_public_url: Option<&str>,
+ ) -> Self {
let name = instance.name();
LocalEnv {
// Both local flavors run against local infra (`local` env defaults).
@@ -53,11 +65,12 @@ impl LocalEnv {
} else {
instance.port(Port::Frontend)
},
+ mcp_public_url: format!("http://localhost:{}/cognition", instance.port(Port::Proxy)),
infra: InfraEnv::local(),
storage: StorageEnv::local(),
queues: QueueEnv::local(),
mail: MailEnv::local(),
- agent_harness: AgentHarnessEnv::local(instance.project_name()),
+ agent_harness: AgentHarnessEnv::local(instance.project_name(), egress_public_url),
service_auth: ServiceAuthEnv::for_instance(name),
fusionauth: FusionAuthEnv::for_instance(instance),
boot_stubs: BootStubEnv,
@@ -71,6 +84,15 @@ impl LocalEnv {
env.insert("COMPOSE_PROJECT_NAME".into(), self.project_name.clone());
env.insert("PORT".into(), "8080".into());
env.insert("FRONTEND_PORT".into(), self.frontend_port.to_string());
+ env.insert("MCP_PUBLIC_URL".into(), self.mcp_public_url.clone());
+ // Pipedream's hosted Connect UI refuses to be opened from an origin
+ // outside this list, and document_cognition's own local default only
+ // names port 3000 - a named instance's frontend lives on a derived
+ // port, so connecting an app there would fail at the consent popup.
+ env.insert(
+ "PIPEDREAM_ALLOWED_ORIGINS".into(),
+ format!("http://localhost:{}", self.frontend_port),
+ );
// Calendar ingestion/sync ships dark (both flags default off in
// deployed envs); local stacks keep it on for development.
env.insert("CALENDAR_SYNC_ENABLED".into(), "true".into());
@@ -270,8 +292,8 @@ impl MailEnv {
/// Daytona account is involved. `DAYTONA_API_KEY` is seeded empty so Doppler
/// cannot bill Daytona, while still leaving the key in the map for
/// `DAYTONA_API_KEY=... DEV_DANGEROUS_LOCAL_CONTAINERS=false just run_local`.
-/// `GITHUB_TOKEN` is left to Doppler / process env so a local sandbox can
-/// still clone.
+/// The sandbox holds no GitHub credential at all: it clones through the
+/// egress proxy.
///
/// Two managed bots: `@coder` (`HARNESS_BOT_ID`) gets a sandbox from the
/// local Docker provider, and `@macro` runs in-process on the in-memory ACP
@@ -284,12 +306,21 @@ struct AgentHarnessEnv {
/// `crates/agent_harness/container` to this tag (BuildKit cache is the
/// freshness check).
image: &'static str,
- /// Network sandboxes join, so this service can dial their sidecars.
+ /// Network sandboxes join, so this service can dial their sidecars and a
+ /// sandbox can dial its egress proxy. Both are containers, so neither can
+ /// use the host's loopback to reach the other.
network: String,
+ /// The egress proxy as its clients dial it: the run's Cursor egress
+ /// tunnel when one opened, otherwise the in-network address.
+ egress_base_url: String,
+ /// Macro's own MCP server as the egress proxy dials it. In-network and
+ /// cleartext, which the proxy permits only under `ENVIRONMENT=local`:
+ /// this hop never leaves the compose bridge.
+ macro_mcp_url: &'static str,
}
impl AgentHarnessEnv {
- fn local(project_name: &str) -> Self {
+ fn local(project_name: &str, egress_public_url: Option<&str>) -> Self {
AgentHarnessEnv {
// bot_id::MACRO_CODER_BOT_ID, a first-party bot with no row.
bot_id: "00000000-0000-0000-0000-00000000a9e7",
@@ -297,6 +328,19 @@ impl AgentHarnessEnv {
image: super::sandbox_image::DEFAULT_LOCAL_TAG,
// Compose names a network `<project>_<network>`.
network: format!("{project_name}_services"),
+ // With a tunnel, every client - the Cursor cloud, but also local
+ // sandboxes - dials the public hostname; one URL both renderings
+ // agree on beats a second config knob, and the extra hop only
+ // exists on a dev stack. Without one, the service's hyphenated
+ // network alias, not its compose name: a sandbox's git
+ // percent-encodes `_` in a host before matching
+ // `credential.<url>.helper`, so an underscore here means the
+ // scoped credential helper never fires and the clone prompts for
+ // a password it has no terminal to read.
+ egress_base_url: egress_public_url
+ .unwrap_or("http://agent-harness-service:8102")
+ .to_owned(),
+ macro_mcp_url: "http://mcp-service:8080/mcp",
}
}
@@ -307,6 +351,8 @@ impl AgentHarnessEnv {
env.insert("DEV_DANGEROUS_LOCAL_CONTAINERS".into(), "true".into());
env.insert("LOCAL_CONTAINER_IMAGE".into(), self.image.into());
env.insert("LOCAL_CONTAINER_NETWORK".into(), self.network.clone());
+ env.insert("EGRESS_BASE_URL".into(), self.egress_base_url.clone());
+ env.insert("MACRO_MCP_URL".into(), self.macro_mcp_url.into());
}
}
@@ -491,15 +537,7 @@ impl BootStubEnv {
"GITHUB_CLIENT_SECRET".into(),
"local-github-client-secret".into(),
);
- env.insert(
- "GITHUB_IDP_ID".into(),
- "99999999-9999-4999-8999-999999999999".into(),
- );
- // Clone token for local sandboxes. Empty here so `--no-doppler` still
- // has the key for `GITHUB_TOKEN=... just run_local`; Doppler overlays
- // a real token when present. Not in `to_env`, so a local stack does
- // not wipe Doppler's value the way it wipes `DAYTONA_API_KEY`.
- env.insert("GITHUB_TOKEN".into(), String::new());
+ env.insert("GITHUB_IDP_ID".into(), identity::GITHUB_IDP_ID.into());
env.insert("STRIPE_SECRET_KEY".into(), "local-stripe-secret".into());
env.insert("STRIPE_PRICE_ID".into(), "local-stripe-price".into());
env.insert(
diff --git a/tooling/xtask/crates/xtask_local/src/local/local_env/test.rs b/tooling/xtask/crates/xtask_local/src/local/local_env/test.rs
index c5fdcbe1a4..c9d6d88db8 100644
--- a/tooling/xtask/crates/xtask_local/src/local/local_env/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/local_env/test.rs
@@ -6,7 +6,7 @@ use crate::local::instance::{Instance, Port};
/// authoritative local env on top (mirrors `env_layer::resolve`).
fn local_env() -> BTreeMap<String, String> {
let instance = Instance::derive(None, None).expect("default instance derives");
- let local = LocalEnv::for_instance(Mode::Local, &instance, true);
+ let local = LocalEnv::for_instance(Mode::Local, &instance, true, None);
let mut env = local.boot_stub_env();
env.extend(local.to_env());
env
@@ -35,6 +35,7 @@ fn emits_required_keys() {
"FUSIONAUTH_API_KEY_SECRET_KEY",
"FUSIONAUTH_PUBLIC_URL",
"FUSIONAUTH_OAUTH_REDIRECT_URI",
+ "MCP_PUBLIC_URL",
"JWT_SECRET_KEY",
// Boot-blocking stubs — service config loaders require these even in a
// no-doppler stack (see `BootStubEnv`).
@@ -87,7 +88,6 @@ fn emits_required_keys() {
"CAL_EVENT_TYPE_CONTENT_NAMES_KEY",
"META_PIXEL_ID",
"META_ACCESS_TOKEN",
- "GITHUB_TOKEN",
"DEV_DANGEROUS_LOCAL_CONTAINERS",
"LOCAL_CONTAINER_IMAGE",
"LOCAL_CONTAINER_NETWORK",
@@ -107,7 +107,7 @@ fn emits_required_keys() {
#[test]
fn boot_stubs_do_not_overlap_authoritative_env() {
let instance = Instance::derive(None, None).expect("default instance derives");
- let local = LocalEnv::for_instance(Mode::Local, &instance, true);
+ let local = LocalEnv::for_instance(Mode::Local, &instance, true, None);
let authoritative = local.to_env();
for key in local.boot_stub_env().keys() {
assert!(
@@ -150,8 +150,13 @@ fn boot_stubs_are_local_only() {
#[test]
fn internal_auth_values_are_authoritative_local_env() {
- let env =
- LocalEnv::for_instance(Mode::Local, &Instance::derive(None, None).unwrap(), true).to_env();
+ let env = LocalEnv::for_instance(
+ Mode::Local,
+ &Instance::derive(None, None).unwrap(),
+ true,
+ None,
+ )
+ .to_env();
let expected = env.get("INTERNAL_API_SECRET_KEY");
assert_eq!(env.get("INTERNAL_API_KEY"), expected);
@@ -241,8 +246,8 @@ fn aws_creds_are_dummy() {
fn instance_secrets_are_scoped_but_identity_is_fixed() {
let default = Instance::derive(None, None).unwrap();
let agent_a = Instance::derive(Some("agent-a"), None).unwrap();
- let a = LocalEnv::for_instance(Mode::Local, &default, true).to_env();
- let b = LocalEnv::for_instance(Mode::Local, &agent_a, true).to_env();
+ let a = LocalEnv::for_instance(Mode::Local, &default, true, None).to_env();
+ let b = LocalEnv::for_instance(Mode::Local, &agent_a, true, None).to_env();
assert_ne!(
a.get("SERVICE_INTERNAL_AUTH_KEY"),
@@ -260,8 +265,8 @@ fn instance_secrets_are_scoped_but_identity_is_fixed() {
fn fusionauth_public_url_uses_the_instance_host_port() {
let default = Instance::derive(None, None).unwrap();
let named = Instance::derive(Some("2508"), None).unwrap();
- let default_env = LocalEnv::for_instance(Mode::Local, &default, true).to_env();
- let named_env = LocalEnv::for_instance(Mode::Local, &named, true).to_env();
+ let default_env = LocalEnv::for_instance(Mode::Local, &default, true, None).to_env();
+ let named_env = LocalEnv::for_instance(Mode::Local, &named, true, None).to_env();
let named_public_url = format!("http://localhost:{}", named.port(Port::FusionAuth));
assert_eq!(
@@ -286,9 +291,9 @@ fn the_agent_harness_uses_local_containers_and_wipes_daytona() {
Some("true")
);
assert_eq!(env.get("DAYTONA_API_KEY").map(String::as_str), Some(""));
- // Present so `GITHUB_TOKEN=... just run_local` overlays, but empty in a
- // no-Doppler stack. Doppler would supply a real token above this stub.
- assert_eq!(env.get("GITHUB_TOKEN").map(String::as_str), Some(""));
+ // No `GITHUB_TOKEN`: the sandbox clones through the egress proxy, which
+ // holds the credential on its behalf.
+ assert!(!env.contains_key("GITHUB_TOKEN"));
// No `CURSOR_API_KEY`: `@cursor` sessions run on the key each user
// registers in settings, so there is no deployment-wide one to stub.
assert!(!env.contains_key("CURSOR_API_KEY"));
@@ -300,9 +305,14 @@ fn the_agent_harness_uses_local_containers_and_wipes_daytona() {
#[test]
fn local_sandboxes_join_the_instances_compose_network() {
let named = Instance::derive(Some("2508"), None).unwrap();
- let default_env =
- LocalEnv::for_instance(Mode::Local, &Instance::derive(None, None).unwrap(), true).to_env();
- let named_env = LocalEnv::for_instance(Mode::Local, &named, true).to_env();
+ let default_env = LocalEnv::for_instance(
+ Mode::Local,
+ &Instance::derive(None, None).unwrap(),
+ true,
+ None,
+ )
+ .to_env();
+ let named_env = LocalEnv::for_instance(Mode::Local, &named, true, None).to_env();
assert_eq!(
default_env
@@ -319,3 +329,36 @@ fn local_sandboxes_join_the_instances_compose_network() {
Some("macro-agent-harness:latest")
);
}
+
+#[test]
+fn mcp_public_url_uses_the_proxy_cognition_route() {
+ let default = Instance::derive(None, None).unwrap();
+ let named = Instance::derive(Some("2508"), None).unwrap();
+ let default_env = LocalEnv::for_instance(Mode::Local, &default, true, None).to_env();
+ let named_env = LocalEnv::for_instance(Mode::Local, &named, true, None).to_env();
+ let named_public_url = format!("http://localhost:{}/cognition", named.port(Port::Proxy));
+
+ assert_eq!(
+ default_env.get("MCP_PUBLIC_URL").map(String::as_str),
+ Some("http://localhost:8090/cognition")
+ );
+ assert_eq!(
+ named_env.get("MCP_PUBLIC_URL").map(String::as_str),
+ Some(named_public_url.as_str())
+ );
+}
+
+/// In-network address, not localhost: a sandbox's localhost is its own. The
+/// host is hyphenated because a sandbox's git percent-encodes `_` before
+/// matching `credential.<url>.helper`, so the compose service name would leave
+/// the scoped helper silently unfired.
+#[test]
+fn the_egress_base_url_is_the_hyphenated_in_network_alias() {
+ let named = Instance::derive(Some("2508"), None).unwrap();
+ let named_env = LocalEnv::for_instance(Mode::Local, &named, true, None).to_env();
+
+ assert_eq!(
+ named_env.get("EGRESS_BASE_URL").map(String::as_str),
+ Some("http://agent-harness-service:8102")
+ );
+}
diff --git a/tooling/xtask/crates/xtask_local/src/local/snapshot/test.rs b/tooling/xtask/crates/xtask_local/src/local/snapshot/test.rs
index d70024ad7b..77c3fc5c52 100644
--- a/tooling/xtask/crates/xtask_local/src/local/snapshot/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/snapshot/test.rs
@@ -8,7 +8,7 @@ use crate::local::instance::Instance;
#[test]
fn key_is_deterministic_and_kickstart_sensitive() {
let instance = Instance::derive(None, None).unwrap();
- crate::local::fusionauth::write_kickstart(&instance, None).unwrap();
+ crate::local::fusionauth::write_kickstart(&instance, None, None).unwrap();
let a = Plan::compute(&instance).unwrap();
let b = Plan::compute(&instance).unwrap();
@@ -17,7 +17,7 @@ fn key_is_deterministic_and_kickstart_sensitive() {
// A named instance generates a kickstart with different ports → new key.
let other = Instance::derive(Some("snapshot-key-test"), None).unwrap();
- crate::local::fusionauth::write_kickstart(&other, None).unwrap();
+ crate::local::fusionauth::write_kickstart(&other, None, None).unwrap();
let c = Plan::compute(&other).unwrap();
assert_ne!(
a.key, c.key,
diff --git a/tooling/xtask/crates/xtask_local/src/local/stack.rs b/tooling/xtask/crates/xtask_local/src/local/stack.rs
index ecba20a85d..d3c6fe44a9 100644
--- a/tooling/xtask/crates/xtask_local/src/local/stack.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/stack.rs
@@ -165,6 +165,10 @@ pub fn up(mode: Mode, args: &UpArgs) -> Result<Instance> {
static_frontend,
infra_only,
infra_only,
+ // Headless stacks serve agents on Cursor Cloud dev boxes, which have
+ // no cloudflared and no @cursor sessions to feed; the egress stays
+ // in-network.
+ None,
)?;
// Build + stage the frontend bundle in the background: it's pure host-side
@@ -278,7 +282,7 @@ pub fn up(mode: Mode, args: &UpArgs) -> Result<Instance> {
} else {
mailpit::direct_ui_url(&instance)
};
- summary::print(mode, &instance, &env, &frontend_url, &mailpit_url);
+ summary::print(mode, &instance, &env, &frontend_url, &mailpit_url, None);
stage.note(&format!(
" headless: `just stack status`, `just stack update`, `just stack down`{}",
instance_suffix(&instance)
@@ -316,6 +320,7 @@ fn bootstrap_from_update(args: &UpdateArgs) -> Result<()> {
enable_onboarding: false,
verbose: args.verbose,
traces: None,
+ with_cf_tunnel: false,
},
no_snapshot: false,
infra_only: false,
@@ -341,6 +346,7 @@ fn update_running(args: &UpdateArgs) -> Result<()> {
args.env.no_doppler,
args.env.env_file.as_deref(),
state.frontend == "static",
+ None,
)?;
let remounted = if let Some(source) = args.binaries_dir.as_deref() {
let new = super::build::BinariesDir::classify(source)?;
diff --git a/tooling/xtask/crates/xtask_local/src/local/summary.rs b/tooling/xtask/crates/xtask_local/src/local/summary.rs
index 201eb54625..cc20490869 100644
--- a/tooling/xtask/crates/xtask_local/src/local/summary.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/summary.rs
@@ -85,13 +85,16 @@ pub fn stop_command(instance: &Instance) -> String {
/// Print the mode/instance/endpoints block after a successful startup.
/// `frontend_url` differs by flow: the dev-server origin for `run_local`, the
/// proxy-served bundle for headless `stack up`; `mailpit_url` follows the same
-/// direct-versus-single-origin distinction.
+/// direct-versus-single-origin distinction. `shared_app_url` is the public
+/// app tunnel when `--with-cf-tunnel` opened one — passed explicitly because,
+/// unlike the egress tunnel, it is not written into the env.
pub fn print(
mode: Mode,
instance: &Instance,
env: &ResolvedEnv,
frontend_url: &str,
mailpit_url: &str,
+ shared_app_url: Option<&str>,
) {
let key = Style::new().dim();
let link = Style::new().cyan();
@@ -147,6 +150,18 @@ pub fn print(
);
row("Receive webhooks at", sdk_webhook::relay_url().to_string());
}
+ // The Cursor egress tunnel, when one opened this run: a public
+ // `EGRESS_BASE_URL` is always a tunnel, and the in-network default is not
+ // worth a row.
+ if let Some(url) = env.merged.get("EGRESS_BASE_URL")
+ && url.starts_with("https://")
+ {
+ row("cursor egress", url.clone());
+ }
+ // The public app tunnel (`--with-cf-tunnel`) — the URL to hand a friend.
+ if let Some(url) = shared_app_url {
+ row("shared app", url.to_string());
+ }
// The frontend and mailpit rows come from the caller (they differ by
// flow); the rest of the endpoint list is shared with `status-local`.
for (label, url, _port) in endpoint_rows(instance) {
diff --git a/tooling/xtask/crates/xtask_local/src/local/test.rs b/tooling/xtask/crates/xtask_local/src/local/test.rs
index d6fe65c6fa..6d3d338472 100644
--- a/tooling/xtask/crates/xtask_local/src/local/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/test.rs
@@ -36,12 +36,12 @@ fn durable_bake_covers_every_repository_built_local_image() {
.as_mapping()
.unwrap()
.iter()
- .filter_map(|(name, service)| {
+ .filter(|(_, service)| {
service
.as_mapping()
.is_some_and(|service| service.contains_key("build"))
- .then(|| name.as_str().unwrap().to_string())
})
+ .map(|(name, _)| name.as_str().unwrap().to_string())
.collect()
}
diff --git a/tooling/xtask/crates/xtask_local/src/local/validate.rs b/tooling/xtask/crates/xtask_local/src/local/validate.rs
index db1cdfe976..ab7db7e7cd 100644
--- a/tooling/xtask/crates/xtask_local/src/local/validate.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/validate.rs
@@ -43,7 +43,7 @@ fn local_compose_flavor(instance: &Instance, mode: Mode, static_frontend: bool)
// Resolve first: the gmail_forwarder sidecar is gated on the resolved env
// exactly as `prepare` gates it, so the validated compose matches what a
// real bring-up with this env would generate.
- let resolved = env_layer::resolve(mode, instance, true, None, static_frontend)?;
+ let resolved = env_layer::resolve(mode, instance, true, None, static_frontend, None)?;
let gmail_forwarder = resolved
.merged
.get("GMAIL_FORWARDER_SA_KEY")
@@ -177,7 +177,7 @@ fn local_env_flavor(
env_file: Option<&std::path::Path>,
static_frontend: bool,
) -> Result<()> {
- let resolved = env_layer::resolve(mode, instance, no_doppler, env_file, static_frontend)?;
+ let resolved = env_layer::resolve(mode, instance, no_doppler, env_file, static_frontend, None)?;
let env = &resolved.merged;
let mut failures: Vec<String> = Vec::new();