Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! 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::BodyExt;
use http_body_util::Full;
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;
pub use agent_session::domain::model::TurnPrompter;
#[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. The third is the absence of either: a custom MCP server the
/// owner added by URL without connecting an account is dialed bare, exactly
/// as the in-process client dials it, and the proxy still strips the
/// sandbox's own token off the way through.
#[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,
},
/// No `Authorization` at all.
Anonymous,
}
impl UpstreamCredential {
/// This credential as an `Authorization` header value, marked sensitive
/// so the http stack keeps it out of its own logging. `None` for
/// [`UpstreamCredential::Anonymous`], which stamps nothing.
///
/// 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<Option<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}")))
}
Self::Anonymous => return Ok(None),
};
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(Some(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])"),
Self::Anonymous => f.write_str("Anonymous"),
}
}
}
/// 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. The listed
/// servers are not a permission - any slug resolves against the owner's own
/// connections - only the names the agent's author gave the apps it was
/// handed, so a refusal can call an app what the person knows it as.
#[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 agent the session is bound to. Macro's own tools write as it,
/// never as a bot the sandbox names.
pub agent: bot_id::BotId,
/// The repository git egress is pinned to, if this session chose one.
pub repo: Option<RepoSlug>,
/// The apps the agent listed for this session, for naming only.
pub mcp_servers: Vec<McpServerListing>,
/// Who prompted the turn the session is running; `None` before its
/// first dispatch.
pub prompter: Option<TurnPrompter>,
}
impl SessionGrant {
/// The prompter of a turn whose MCP tool calls must wait for the
/// owner's approval: anyone but the owner, a bot on nobody's behalf
/// included. `None` when the owner prompted it, or nobody has yet.
pub fn held_prompter(&self) -> Option<&TurnPrompter> {
self.prompter
.as_ref()
.filter(|prompter| prompter.acting_user() != Some(&self.owner))
}
/// What to call `slug` when speaking to the model: the agent's own name
/// for it when the agent listed it, otherwise the slug made readable
/// (`google_sheets` → `Google Sheets`).
pub fn display_name(&self, slug: &McpServerSlug) -> String {
self.mcp_servers
.iter()
.find(|listing| listing.slug == *slug)
.map(|listing| listing.name.clone())
.unwrap_or_else(|| readable_slug(slug))
}
}
/// `google_sheets` → `Google Sheets`: the fallback name for an app nobody
/// gave a display name.
fn readable_slug(slug: &McpServerSlug) -> String {
slug.as_str()
.split(['_', '-'])
.filter(|word| !word.is_empty())
.map(|word| {
let mut chars = word.chars();
match chars.next() {
Some(first) => first.to_uppercase().chain(chars).collect::<String>(),
None => String::new(),
}
})
.collect::<Vec<_>>()
.join(" ")
}
/// One app an agent listed for its sessions: the slug the proxy routes on and
/// the name anything human-facing calls it.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct McpServerListing {
/// Pipedream's app slug, verbatim.
pub slug: McpServerSlug,
/// Display name, e.g. `Linear`.
pub name: String,
}
/// One of the owner's custom MCP servers, as the harness advertises it: the
/// key the proxy routes on and the name the owner gave the server.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CustomMcpServerListing {
/// The key derived from the server's URL; see [`CustomMcpServerKey`].
pub key: CustomMcpServerKey,
/// The owner's display name for it, e.g. `Internal wiki`.
pub name: String,
}
/// How a destination resolved: to a call the owner's grant backs, to one
/// that can be addressed for the owner without any grant behind it, or to
/// one whose grant has died.
///
/// The second exists because Pipedream scopes a call by user id and app slug
/// alone, so an app the owner never connected is still *addressable* - and
/// listing its tools works, only calling them does not. The third is a custom
/// server's: the owner connected it once, and the stored grant no longer
/// yields a token - expired with no refresh token, or refused on refresh. The
/// service decides what to do with either; the resolver only reports it.
#[derive(Clone, Debug)]
pub enum McpResolution {
/// The owner holds an enabled connection for this destination.
Connected(UpstreamCall),
/// The owner holds no enabled connection, but the upstream can be
/// addressed for them anyway.
Unconnected(UpstreamCall),
/// The owner's connection exists but its grant is dead, so nothing can
/// be stamped. The call is bare; the name is what the owner calls the
/// server, carried here because nothing else on the path knows it.
Disconnected {
/// The upstream, with no credential.
call: UpstreamCall,
/// The owner's display name for the server.
name: String,
},
}
/// The most a JSON-RPC request body may be for the proxy to read it.
///
/// Only read on the unconnected path, where the proxy has to know the method
/// to answer `tools/call` itself. MCP requests are small
/// JSON; the streaming rationale on [`ProxyBody`] is about responses and
/// packfiles, neither of which is a request body on the MCP route.
pub const MAX_MCP_REQUEST_BYTES: usize = 1 << 20;
/// The MCP method whose result the model reads as a tool's own answer.
pub const TOOLS_CALL_METHOD: &str = "tools/call";
/// The parts of a JSON-RPC request the proxy cares about.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct JsonRpcCall {
/// The method name.
pub method: String,
/// The request id, echoed on the response. Absent on notifications,
/// which get no response at all.
pub id: serde_json::Value,
}
/// Reads the method and id off a single JSON-RPC request.
///
/// `None` for anything else - a notification (no id), a batch, or a body
/// that is not JSON - all of which the caller forwards untouched, since
/// there is nothing here to answer in their place.
pub fn peek_json_rpc(body: &[u8]) -> Option<JsonRpcCall> {
let value: serde_json::Value = serde_json::from_slice(body).ok()?;
let object = value.as_object()?;
let method = object.get("method")?.as_str()?.to_owned();
let id = object.get("id")?.clone();
if id.is_null() {
return None;
}
Some(JsonRpcCall { method, id })
}
/// The markup an agent includes in a reply to give the reader a button that
/// connects the app. Mirrors the frontend's `m-connect-app` Lexical node; the
/// payload shape is `{"appSlug": ..., "name": ...}`.
pub const CONNECT_APP_TAG: &str = "m-connect-app";
/// The tool result the proxy answers a `tools/call` with when the session
/// owner has not connected the app.
///
/// A `result` with `isError: true`, not a JSON-RPC `error`: the former is
/// what MCP clients hand the model as the tool's own answer, the latter is
/// rendered as a transport failure the model never sees. The wording is our
/// own fixed text plus the app's slug and display name - the slug already
/// validated by [`McpServerSlug::parse`], the name from the agent's own
/// configuration or derived from that slug.
pub fn not_connected_tool_result(
slug: &McpServerSlug,
name: &str,
id: serde_json::Value,
) -> ProxyResponse {
tool_result_response(id, not_connected_text(slug, name))
}
/// What [`not_connected_tool_result`] tells the model, for callers that
/// answer outside JSON-RPC.
pub fn not_connected_text(slug: &McpServerSlug, name: &str) -> String {
let payload = serde_json::json!({
"appSlug": slug.as_str(),
"name": name,
});
format!(
"{name} is not connected for the selected acting_as account, or they have it turned off, so this tool cannot run yet. Tell them so in your reply, and include this exact markup so they get a button that connects it: <{tag}>{payload}</{tag}> Close your reply by asking them to let you know once they have connected {name} so \
you can try again - when they do, call this tool again; nothing else needs to change.",
name = name,
tag = CONNECT_APP_TAG,
)
}
/// The tool result the proxy answers a `tools/call` with when the session
/// owner's grant for a custom MCP server has died.
///
/// No connect-button markup: that chip opens the Pipedream catalog, and a
/// custom server is reconnected from its own row under Agents → Connections.
/// Same shape as [`not_connected_tool_result`] otherwise, for the same
/// reason - a `result` the model reads, not a transport error it never sees.
/// The name is the owner's own, off their row, never anything the request
/// carried.
pub fn disconnected_tool_result(name: &str, id: serde_json::Value) -> ProxyResponse {
tool_result_response(id, disconnected_text(name))
}
/// What [`disconnected_tool_result`] tells the model, for callers that answer
/// outside JSON-RPC.
pub fn disconnected_text(name: &str) -> String {
format!(
"{name} is a custom MCP server the selected acting_as account added, but its \
connection has expired, so this tool cannot run yet. Tell them so in your reply, \
and ask them to open Agents → Connections, find {name} under Custom MCP, and use \
Reconnect. Close your reply by asking them to let you know once they have done so \
- when they do, call this tool again; nothing else needs to change.",
)
}
/// An MCP tool result carrying `text` as its `isError` answer.
pub fn tool_error_result(text: String) -> serde_json::Value {
serde_json::json!({
"isError": true,
"content": [{ "type": "text", "text": text }],
})
}
/// A JSON-RPC response carrying `text` as an `isError` tool result for `id`.
pub(crate) fn tool_result_response(id: serde_json::Value, text: String) -> ProxyResponse {
let body = serde_json::json!({
"jsonrpc": "2.0",
"id": id,
"result": tool_error_result(text),
});
let bytes = Bytes::from(serde_json::to_vec(&body).expect("a JSON value serializes"));
let mut response = http::Response::new(
Full::new(bytes)
.map_err(|never| match never {})
.boxed_unsync(),
);
response.headers_mut().insert(
header::CONTENT_TYPE,
HeaderValue::from_static("application/json"),
);
response
}
/// 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)
}
}
/// How many hex characters of the URL digest a [`CustomMcpServerKey`] keeps.
///
/// 128 bits: the namespace is one owner's handful of rows, so this is far
/// past where two of their URLs could meet, and short enough to read in a
/// log line.
const CUSTOM_KEY_HEX_LEN: usize = 32;
/// The identifier a sandbox calls one of its owner's custom MCP servers by.
///
/// A custom server is a row keyed by the URL the owner typed in, and a URL is
/// not a path segment - so the key is the SHA-256 digest of that URL,
/// lowercase hex, truncated to [`CUSTOM_KEY_HEX_LEN`]. Derived, unlike
/// [`McpServerSlug`], but derived in exactly one place: the harness
/// advertises [`CustomMcpServerKey::for_url`] of each row's URL and the
/// resolver matches the same function against the owner's rows, so there is
/// no second reading for the two ends to disagree over.
///
/// One-way on purpose. The sandbox cannot turn a key back into a URL, and the
/// resolver never parses one out of it: a key names nothing until it meets
/// the owner's own rows, which is the property every other destination here
/// has too.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct CustomMcpServerKey(String);
impl CustomMcpServerKey {
/// The key for a server stored under `url`, verbatim as the row holds it.
pub fn for_url(url: &str) -> Self {
let digest: String = Sha256::digest(url.as_bytes())
.iter()
.map(|byte| format!("{byte:02x}"))
.collect();
Self(digest[..CUSTOM_KEY_HEX_LEN].to_owned())
}
/// Accept a key from a request path.
///
/// Exactly the shape [`Self::for_url`] produces and nothing else;
/// rejected rather than normalized, like every other path segment here.
pub fn parse(segment: &str) -> Option<Self> {
let valid = segment.len() == CUSTOM_KEY_HEX_LEN
&& segment
.chars()
.all(|character| matches!(character, '0'..='9' | 'a'..='f'));
valid.then(|| Self(segment.to_owned()))
}
/// The key as it appears in a path.
pub fn as_str(&self) -> &str {
&self.0
}
}
impl fmt::Display for CustomMcpServerKey {
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::Preview) => "macro-preview".to_owned(),
Self::McpServer(McpDestination::Connected(slug)) => slug.as_str().to_owned(),
Self::McpServer(McpDestination::Custom(key)) => format!("custom {key}"),
Self::GitHubGit { endpoint } => format!("git {}", endpoint.path_and_query()),
}
}
}
/// Which MCP server a request names.
///
/// Macro's own server, the owner's connected apps, and the owner's custom
/// servers live on different routes (`/mcp-macro`, `/mcp/{slug}`,
/// `/mcp-custom/{key}`), 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 {
/// Internal, session-scoped live preview tools.
Preview,
/// Macro's own MCP server, available to every session.
Macro,
/// One of the owner's Pipedream-connected apps.
Connected(McpServerSlug),
/// One of the owner's custom MCP servers - added by URL, with Macro's
/// own OAuth client holding the grant.
Custom(CustomMcpServerKey),
}
/// The route Macro's own MCP server is served on.
pub const MACRO_MCP_PATH: &str = "/mcp-macro";
/// The route prefix a connected app's slug follows.
pub const CONNECTED_MCP_PATH_PREFIX: &str = "/mcp/";
/// The route prefix a custom server's key follows.
pub const CUSTOM_MCP_PATH_PREFIX: &str = "/mcp-custom/";
impl McpDestination {
/// Read a destination off a proxy URL's path.
///
/// This is how an in-process client names its server: it is handed the
/// same egress URLs a sandbox is, so it reads them the same way the
/// router does rather than being told the answer a second way.
pub fn from_path(path: &str) -> Option<Self> {
if path == "/mcp-preview" {
return Some(Self::Preview);
}
if path == MACRO_MCP_PATH {
return Some(Self::Macro);
}
if let Some(key) = path.strip_prefix(CUSTOM_MCP_PATH_PREFIX) {
return CustomMcpServerKey::parse(key).map(Self::Custom);
}
let slug = path.strip_prefix(CONNECTED_MCP_PATH_PREFIX)?;
McpServerSlug::parse(slug).map(Self::Connected)
}
}
/// 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(),
},
)
}
/// A call with no credential at all.
///
/// For a custom MCP server the owner added without connecting an
/// account. Still https-only: nothing of the owner's rides on this call,
/// but the MCP session id and whatever the server answers do, and the
/// URL is typed in by a person.
pub fn anonymous(url: Url) -> Result<Self, EgressError> {
Self::new(url, UpstreamCredential::Anonymous)
}
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() {}
}
}