Initial public release

Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
Evan Whittaker
2026-10-17 12:08:30 -05:00
commit 09a7de2520
1730 changed files with 412952 additions and 0 deletions

529
crates/luxe-mcp/src/http.rs Normal file
View File

@@ -0,0 +1,529 @@
//! Streamable HTTP transport for remote MCP servers.
//!
//! Speaks the MCP "Streamable HTTP" transport: JSON-RPC is POSTed to the server URL, and the server
//! answers with either `application/json` (one response) or `text/event-stream` (an SSE stream we
//! read until our request id comes back). A server-issued `Mcp-Session-Id` is echoed on later
//! requests. Lives here rather than in `luxe-core` because core carries no HTTP dependency.
//!
//! Auth: a static bearer token (literal or from an env var) plus arbitrary headers, both with
//! `${VAR}` interpolation, or an OAuth bearer from [`crate::oauth`].
use std::sync::atomic::{AtomicI64, Ordering};
use async_trait::async_trait;
use futures_util::StreamExt;
use reqwest::header::{HeaderMap, HeaderName, HeaderValue, ACCEPT, AUTHORIZATION, CONTENT_TYPE};
use reqwest::Client;
use serde_json::{json, Value};
use tokio::sync::Mutex;
use luxe_core::mcp_client::{
McpAuth, McpConnection, McpError, McpServerConfig, McpTool, McpToolResult, McpTransport,
};
use crate::oauth::{OAuthClient, OAuthError, TokenState};
use crate::secret::SecretError;
use std::sync::Arc;
/// How long reaching the server may take
const CONNECT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
/// How long its handshake may take once reached
const HANDSHAKE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
/// Why the HTTP transport could not connect or get an answer.
///
/// Each carries the sentence the reader sees. [`McpError`] is what the engine gets: the variants
/// here are sorted into its four at the boundary.
#[derive(Debug, thiserror::Error)]
pub enum McpHttpError {
/// The configured transport is not HTTP
#[error("server '{0}' is not an HTTP transport")]
NotHttp(String),
/// A header, a bearer token or the client could not be built from the config
#[error("{0}")]
Config(String),
/// An OAuth step refused: usually a URL that would send a credential somewhere it could be read
#[error(transparent)]
OAuth(#[from] OAuthError),
/// A configured secret did not resolve
#[error(transparent)]
Secret(#[from] SecretError),
/// The server needs a sign-in the stored one does not provide
#[error("{0}")]
SignIn(String),
/// The handshake did not finish in time
#[error("'{0}' did not finish its handshake in time")]
HandshakeTimeout(String),
/// The request did not reach the server, or its answer broke off
#[error("{0}")]
Transport(String),
/// The server answered with an HTTP error
#[error("{method} returned HTTP {status}")]
Status {
/// The JSON-RPC method that was sent
method: String,
/// What the server said
status: reqwest::StatusCode,
},
/// The server answered with a JSON-RPC error
#[error("{0}")]
Rpc(String),
/// The answer was not MCP
#[error("{0}")]
Protocol(String),
/// The server answered 404 to the session the request carried
#[error("the server's session expired")]
SessionExpired(String),
}
impl From<McpHttpError> for McpError {
/// Sorted by what went wrong; the text stays this transport's own.
fn from(error: McpHttpError) -> Self {
let text = error.to_string();
match error {
McpHttpError::Rpc(_) => Self::Rpc(text),
McpHttpError::Protocol(_) => Self::Protocol(text),
McpHttpError::SessionExpired(_) => Self::Closed(text),
McpHttpError::NotHttp(_)
| McpHttpError::Config(_)
| McpHttpError::OAuth(_)
| McpHttpError::Secret(_)
| McpHttpError::SignIn(_)
| McpHttpError::HandshakeTimeout(_)
| McpHttpError::Transport(_)
| McpHttpError::Status { .. } => Self::Transport(text),
}
}
}
/// A live Streamable-HTTP connection to a remote MCP server.
pub struct HttpConnection {
server_id: String,
url: String,
client: Client,
session_id: Mutex<Option<String>>,
/// The version the server agreed to in `initialize`, sent on every request after it
protocol_version: Mutex<Option<String>>,
/// Held while an expired session is started again, so concurrent calls restart it once
restarting: Mutex<()>,
next_id: AtomicI64,
/// When set, a fresh OAuth bearer is attached per request (handles expiry/refresh).
oauth: Option<Arc<OAuthClient>>,
}
impl HttpConnection {
/// Build the HTTP client (headers + auth) and run the `initialize` handshake.
pub async fn connect(config: &McpServerConfig) -> Result<Self, McpHttpError> {
Self::connect_within(config, HANDSHAKE_TIMEOUT).await
}
/// [`Self::connect`], with the handshake held to `handshake`.
pub(crate) async fn connect_within(
config: &McpServerConfig,
handshake: std::time::Duration,
) -> Result<Self, McpHttpError> {
let url = match &config.transport {
McpTransport::HttpSse { url } => url.clone(),
McpTransport::Stdio { .. } => return Err(McpHttpError::NotHttp(config.id.clone())),
};
// a token goes nowhere it could be read on the way
if config.auth.is_some() {
crate::oauth::require_secure(&url, "the MCP server")?;
}
let mut headers = HeaderMap::new();
for (name, value) in &config.headers {
let header = HeaderName::from_bytes(name.as_bytes())
.map_err(|e| McpHttpError::Config(format!("invalid header name '{name}': {e}")))?;
let expanded = luxe_core::mcp_client::expand_env(value);
// a header filled from the environment is usually the server's key
if expanded != *value {
crate::secret::remembered(&expanded);
}
let value = HeaderValue::from_str(&expanded).map_err(|e| {
McpHttpError::Config(format!("invalid header value for '{name}': {e}"))
})?;
headers.insert(header, value);
}
let mut oauth = None;
match &config.auth {
Some(McpAuth::Bearer { token, token_env }) => {
let resolved = resolve_bearer(
token.as_deref(),
token_env.as_deref(),
config.declared_by_user,
&config.id,
)
.await?;
let mut value = HeaderValue::from_str(&format!("Bearer {resolved}"))
.map_err(|e| McpHttpError::Config(format!("invalid bearer token: {e}")))?;
value.set_sensitive(true);
headers.insert(AUTHORIZATION, value);
}
Some(McpAuth::OAuth(cfg)) => {
oauth = Some(Arc::new(
OAuthClient::new(config.id.clone(), url.clone(), cfg.clone())
.with_secret_commands(config.declared_by_user),
));
}
None => {}
}
let client = Client::builder()
.default_headers(headers)
.connect_timeout(CONNECT_TIMEOUT)
.build()
.map_err(|e| McpHttpError::Config(format!("http client build failed: {e}")))?;
let conn = Self {
server_id: config.id.clone(),
url,
client,
session_id: Mutex::new(None),
protocol_version: Mutex::new(None),
restarting: Mutex::new(()),
next_id: AtomicI64::new(1),
oauth,
};
tokio::time::timeout(handshake, conn.handshake())
.await
.map_err(|_| McpHttpError::HandshakeTimeout(conn.server_id.clone()))??;
Ok(conn)
}
/// Attach a fresh OAuth bearer (refreshing if needed) to a request builder. A server that still
/// needs interactive login fails the request with an actionable message.
async fn authorize(
&self,
builder: reqwest::RequestBuilder,
) -> Result<reqwest::RequestBuilder, McpHttpError> {
let Some(oauth) = &self.oauth else { return Ok(builder) };
match oauth.access_token().await {
TokenState::Have(token) => Ok(builder.bearer_auth(token)),
TokenState::NeedsLogin(reason) | TokenState::Unavailable(reason) => {
Err(McpHttpError::SignIn(reason))
}
}
}
async fn handshake(&self) -> Result<(), McpHttpError> {
*self.session_id.lock().await = None;
*self.protocol_version.lock().await = None;
let params = json!({
"protocolVersion": luxe_core::mcp_client::MCP_PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": { "name": "luxe", "version": luxe_core::version::VERSION },
});
let result = self.request_once("initialize", &params).await?;
let agreed = result.get("protocolVersion").and_then(Value::as_str);
*self.protocol_version.lock().await = agreed.map(str::to_string);
self.notify("notifications/initialized").await?;
Ok(())
}
/// Send a JSON-RPC request and return its `result`, starting the session again once if the
/// server says it has expired.
async fn request(&self, method: &str, params: Value) -> Result<Value, McpHttpError> {
match self.request_once(method, &params).await {
Err(McpHttpError::SessionExpired(expired)) => {
self.restart_session(&expired).await?;
self.request_once(method, &params).await
}
other => other,
}
}
/// Starts the session again if it is still the one that expired: of calls that all saw it
/// expire, the first restarts it and the rest go out on the new one.
async fn restart_session(&self, expired: &str) -> Result<(), McpHttpError> {
let _restarting = self.restarting.lock().await;
if self.session_id.lock().await.as_deref() == Some(expired) {
tracing::info!(server = %self.server_id, "mcp: session expired; starting a new one");
self.handshake().await?;
}
Ok(())
}
/// Send a JSON-RPC request once and return its `result`, handling json + SSE responses.
async fn request_once(&self, method: &str, params: &Value) -> Result<Value, McpHttpError> {
let id = self.next_id.fetch_add(1, Ordering::Relaxed);
let body = json!({ "jsonrpc": "2.0", "id": id, "method": method, "params": params });
let builder = self
.client
.post(&self.url)
.header(ACCEPT, "application/json, text/event-stream")
.json(&body);
let (builder, sent_session) = self.with_session(builder).await?;
let response = builder
.send()
.await
.map_err(|e| McpHttpError::Transport(format!("{method} request failed: {e}")))?;
if let Some(session) = response.headers().get("mcp-session-id") {
if let Ok(value) = session.to_str() {
*self.session_id.lock().await = Some(value.to_string());
}
}
// the spec's word for an expired session; one without a session is just not found
if let Some(sent) = sent_session.filter(|_| response.status() == 404) {
return Err(McpHttpError::SessionExpired(sent));
}
if !response.status().is_success() {
return Err(McpHttpError::Status {
method: method.to_string(),
status: response.status(),
});
}
let is_sse = response
.headers()
.get(CONTENT_TYPE)
.and_then(|v| v.to_str().ok())
.is_some_and(|ct| ct.contains("text/event-stream"));
if is_sse {
read_sse_response(response, id).await
} else {
let value: Value = response
.json()
.await
.map_err(|e| McpHttpError::Protocol(format!("bad json: {e}")))?;
extract_result(&value)
}
}
/// `builder` with the session, the agreed protocol version and the bearer it carries, and the
/// session it went out on.
async fn with_session(
&self,
mut builder: reqwest::RequestBuilder,
) -> Result<(reqwest::RequestBuilder, Option<String>), McpHttpError> {
let session = self.session_id.lock().await.clone();
if let Some(session) = &session {
builder = builder.header("Mcp-Session-Id", session.as_str());
}
if let Some(version) = self.protocol_version.lock().await.clone() {
builder = builder.header("MCP-Protocol-Version", version);
}
Ok((self.authorize(builder).await?, session))
}
/// Send a JSON-RPC notification (no id, no response expected).
async fn notify(&self, method: &str) -> Result<(), McpHttpError> {
let body = json!({ "jsonrpc": "2.0", "method": method });
let (builder, _) = self.with_session(self.client.post(&self.url).json(&body)).await?;
// Notifications are fire-and-forget; a transport hiccup here shouldn't fail the session.
if let Err(error) = builder.send().await {
tracing::debug!(server = %self.server_id, %error, "mcp: notification send failed");
}
Ok(())
}
}
#[async_trait]
impl McpConnection for HttpConnection {
fn server_id(&self) -> &str {
&self.server_id
}
async fn list_tools(&self) -> Result<Vec<McpTool>, McpError> {
let result = self.request("tools/list", json!({})).await?;
luxe_core::mcp_client::parse_tool_list(&result, &self.server_id)
.ok_or_else(|| McpError::Protocol("tools/list missing `tools` array".to_string()))
}
async fn call_tool(&self, raw_name: &str, arguments: Value) -> Result<McpToolResult, McpError> {
let result =
self.request("tools/call", json!({ "name": raw_name, "arguments": arguments })).await?;
Ok(luxe_core::mcp_client::parse_tool_call_result(&result))
}
}
/// Read an SSE stream until a JSON-RPC message with `id` arrives, returning its `result`.
async fn read_sse_response(response: reqwest::Response, id: i64) -> Result<Value, McpHttpError> {
let mut stream = response.bytes_stream();
let mut buffer = String::new();
while let Some(chunk) = stream.next().await {
let bytes = chunk.map_err(|e| McpHttpError::Transport(format!("sse read error: {e}")))?;
buffer.push_str(&String::from_utf8_lossy(&bytes));
while let Some(newline) = buffer.find('\n') {
let line: String = buffer.drain(..=newline).collect();
let line = line.trim_end();
let Some(data) = line.strip_prefix("data:") else { continue };
let data = data.trim();
if data.is_empty() {
continue;
}
if let Ok(value) = serde_json::from_str::<Value>(data) {
if value.get("id").and_then(Value::as_i64) == Some(id) {
return extract_result(&value);
}
}
}
}
Err(McpHttpError::Protocol("SSE stream ended before a matching response".to_string()))
}
/// Pull `result` out of a JSON-RPC envelope, surfacing an `error` as `Err`.
fn extract_result(message: &Value) -> Result<Value, McpHttpError> {
if let Some(error) = message.get("error") {
let msg = error.get("message").and_then(Value::as_str).unwrap_or("unknown error");
return Err(McpHttpError::Rpc(msg.to_string()));
}
Ok(message.get("result").cloned().unwrap_or(Value::Null))
}
/// Resolve a bearer token from `token` — a value, `${VAR}` or `!command`
/// ([`crate::secret::resolve_secret`]) — or else from the variable `token_env` names.
///
/// Args: `(token, token_env, commands_allowed, server_id)`.
async fn resolve_bearer(
token: Option<&str>,
token_env: Option<&str>,
commands_allowed: bool,
server_id: &str,
) -> Result<String, McpHttpError> {
if let Some(written) = token.filter(|t| !t.is_empty()) {
let what = format!("the bearer token for '{server_id}'");
match crate::secret::resolve_secret(written, commands_allowed, &what).await {
Ok(value) => return Ok(value),
// An unset `${VAR}` falls through to `token_env`, as it always has; a `!command` that
// was refused or failed does not, which would hide that the config asked for one
Err(SecretError::Unset(_)) if token_env.is_some() => {}
Err(error) => return Err(error.into()),
}
}
if let Some(var) = token_env {
let config = |message: String| McpHttpError::Config(message);
let token = std::env::var(var)
.map_err(|_| config(format!("bearer token env var '{var}' is not set")))?;
if token.is_empty() {
return Err(config(format!("env var '{var}' is empty")));
}
return Ok(crate::secret::remembered(&token));
}
Err(McpHttpError::Config("bearer auth needs `token` or `token_env`".to_string()))
}
#[cfg(test)]
mod tests {
use super::*;
/// A token is never sent in the clear: a server reached over plain http off this machine is
/// refused before anything is sent to it when it has auth configured.
#[tokio::test]
async fn a_token_is_not_sent_over_plain_http() {
let config = McpServerConfig {
id: "plain".into(),
transport: McpTransport::HttpSse { url: "http://example.com/mcp".into() },
auth: Some(McpAuth::Bearer { token: Some("plain-text-token".into()), token_env: None }),
..Default::default()
};
let error = HttpConnection::connect(&config).await.err().expect("refused");
assert!(matches!(error, McpHttpError::OAuth(OAuthError::Insecure(_))), "{error:?}");
assert!(error.to_string().contains("not https"), "{error}");
}
/// A header filled from the environment is usually the server's key, so it is remembered for
/// redaction like a bearer token is.
#[tokio::test]
async fn a_header_from_the_environment_is_remembered_for_redaction() {
std::env::set_var("LUXE_MCP_HEADER_KEY_TEST", "mcp-header-secret-91");
let config = McpServerConfig {
id: "h".into(),
transport: McpTransport::HttpSse { url: "http://127.0.0.1:1/mcp".into() },
headers: [("X-API-Key".into(), "${LUXE_MCP_HEADER_KEY_TEST}".into())]
.into_iter()
.collect(),
..Default::default()
};
let _ = HttpConnection::connect(&config).await;
let seen = luxe_core::redact::process_secrets().redact("key mcp-header-secret-91");
assert_eq!(seen, "key [REDACTED]");
}
/// A server that takes the connection and never answers is given up on, not waited for.
#[tokio::test]
async fn a_silent_server_fails_its_handshake_in_time() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let url = format!("http://{}/mcp", listener.local_addr().unwrap());
let held = tokio::spawn(async move {
let (_socket, _) = listener.accept().await.unwrap();
std::future::pending::<()>().await;
});
let config = McpServerConfig {
id: "silent".into(),
transport: McpTransport::HttpSse { url },
..Default::default()
};
let quick = std::time::Duration::from_millis(200);
let connect = HttpConnection::connect_within(&config, quick);
let error = tokio::time::timeout(std::time::Duration::from_secs(5), connect)
.await
.expect("given up on in time")
.err()
.expect("refused");
assert!(matches!(error, McpHttpError::HandshakeTimeout(_)), "{error:?}");
assert!(error.to_string().contains("did not finish its handshake"), "{error}");
held.abort();
}
/// The engine sorts failures by kind and shows the text this transport wrote.
#[test]
fn an_http_error_is_sorted_by_what_went_wrong_and_keeps_its_text() {
let rpc = McpError::from(McpHttpError::Rpc("boom".into()));
assert!(matches!(&rpc, McpError::Rpc(text) if text == "boom"));
let protocol = McpError::from(McpHttpError::Protocol("bad json: eof".into()));
assert!(matches!(protocol, McpError::Protocol(_)));
let expired = McpError::from(McpHttpError::SessionExpired("s1".into()));
assert!(
matches!(&expired, McpError::Closed(text) if text == "the server's session expired")
);
let status = McpHttpError::Status {
method: "tools/call".into(),
status: reqwest::StatusCode::BAD_GATEWAY,
};
let status = McpError::from(status);
assert!(
matches!(&status, McpError::Transport(text) if text == "tools/call returned HTTP 502 Bad Gateway")
);
}
#[test]
fn extract_result_surfaces_errors() {
let ok = json!({ "jsonrpc": "2.0", "id": 1, "result": { "x": 1 } });
assert_eq!(extract_result(&ok).unwrap(), json!({ "x": 1 }));
let err = json!({ "jsonrpc": "2.0", "id": 1, "error": { "message": "boom" } });
let error = extract_result(&err).unwrap_err();
assert!(matches!(&error, McpHttpError::Rpc(message) if message == "boom"), "{error:?}");
}
#[tokio::test]
async fn resolve_bearer_prefers_the_token_then_the_variable() {
assert_eq!(resolve_bearer(Some("abc"), None, false, "s").await.unwrap(), "abc");
std::env::set_var("LUXE_MCP_BEARER_ENV", "fromenv");
let env = Some("LUXE_MCP_BEARER_ENV");
assert_eq!(resolve_bearer(None, env, false, "s").await.unwrap(), "fromenv");
assert_eq!(
resolve_bearer(Some("${LUXE_MCP_BEARER_UNSET}"), env, false, "s").await.unwrap(),
"fromenv",
"an unset variable in `token` falls through to `token_env`"
);
std::env::remove_var("LUXE_MCP_BEARER_ENV");
assert!(resolve_bearer(None, None, false, "s").await.is_err());
}
/// A `!command` token runs for your own config and is refused, not skipped, for a project's:
/// falling through to `token_env` would hide that the config asked for a command.
#[cfg(unix)]
#[tokio::test]
async fn a_command_token_runs_only_for_your_own_config() {
std::env::set_var("LUXE_MCP_BEARER_CMD_ENV", "fromenv");
let env = Some("LUXE_MCP_BEARER_CMD_ENV");
assert_eq!(resolve_bearer(Some("!echo t0k"), env, true, "s").await.unwrap(), "t0k");
let refused =
resolve_bearer(Some("!echo t0k"), env, false, "s").await.unwrap_err().to_string();
assert!(refused.starts_with("the bearer token for 's' is a command"), "{refused}");
std::env::remove_var("LUXE_MCP_BEARER_CMD_ENV");
}
}

View File

@@ -0,0 +1,32 @@
//! luxe-mcp — Model Context Protocol orchestration.
//!
//! The problem this solves: MCP tool definitions are verbose. Registering every tool from every
//! server up front burns thousands of context tokens whether or not the agent uses them, and eager
//! connections spawn processes at launch. Instead Luxe exposes **one** proxy tool ([`McpProxyTool`],
//! `mcp`) — the agent *discovers* tools on demand (`search` → `describe` → `call`) — backed by a
//! [`ServerRegistry`] that connects servers **lazily** and caches their tool metadata so discovery
//! works without a live connection.
//!
//! Architecture: the low-level stdio transport + MCP types live in `luxe-core` (no HTTP dep
//! there); this crate carries the orchestration plus the Streamable-HTTP transport and OAuth that
//! core's no-HTTP rule keeps out of core. MCP servers stay untrusted — calls are permission-gated
//! and results are surfaced as data, never instructions.
//!
//! Both transports are reached through [`connect`], so nothing has to know which one a server
//! uses. A remote server is configured with a URL and, where it needs one, a bearer token or an
//! OAuth flow — which is how a vendor's hosted MCP server (Firecrawl, Exa, and the rest) is used
//! from Luxe without Luxe carrying an adapter for it.
pub mod http;
pub mod oauth;
mod registry;
mod secret;
pub mod token_store;
mod tool;
pub use http::McpHttpError;
pub use oauth::OAuthError;
pub use registry::{open_connection as connect, RegistryError, ServerRegistry, ToolRef};
pub use secret::SecretError;
pub use token_store::TokenStoreError;
pub use tool::McpProxyTool;

View File

@@ -0,0 +1,325 @@
//! OAuth 2.1 client for hosted MCP servers.
//!
//! Covers the MCP auth story: discovery (RFC 9728 protected-resource metadata, then RFC 8414
//! authorization-server metadata), dynamic client registration (RFC 7591) for servers that allow
//! it and a configured client for those that do not, resource indicators (RFC 8707), the
//! authorization-code + PKCE flow (interactive loopback *and* a headless start/complete pair), the
//! client-credentials flow, and refresh. Tokens land in the `0600`
//! [`crate::token_store::TokenStore`]; secrets are never logged.
//!
//! # Discovery
//!
//! The order is the specification's, and it matters more than it looks. A host can serve metadata
//! for more than one server: Asana's MCP host still publishes, at its root, the authorization server
//! of a beta it retired, while its current server's metadata sits at the path the specification
//! names. Reading the root first signs in to the wrong server. So the path the server itself points
//! at wins, then the path form, then the root, and the old origin lookup only when a server
//! publishes no protected-resource metadata at all. What is found is checked before it is used:
//! a protected-resource document must name the server it was fetched for, and an authorization
//! server must be `https` and say it is who it was asked for, so a hostile document cannot send a
//! token anywhere else.
use std::sync::Mutex;
use std::time::{Duration, SystemTime, UNIX_EPOCH};
use luxe_core::mcp_client::{OAuthConfig, OAuthGrant};
use luxe_core::oauth_loopback::{pkce, random_state, LoopbackCallback, Pkce};
use crate::token_store::TokenStore;
mod discovery;
mod endpoints;
mod error;
mod grants;
mod registration;
pub(crate) use endpoints::require_secure;
use endpoints::Endpoints;
pub use error::OAuthError;
/// How long a login waits for the browser to come back before giving up.
pub const LOGIN_TIMEOUT: Duration = Duration::from_secs(5 * 60);
/// How long one discovery or token request may take. Without it a server that accepts the
/// connection and never answers holds a login open forever.
const REQUEST_TIMEOUT: Duration = Duration::from_secs(20);
/// Endpoints plus the resource indicator the tokens are for.
#[derive(Debug, Clone)]
struct Resolved {
endpoints: Endpoints,
/// The protected resource's own identifier when it published one, else the server URL
resource: String,
}
/// Who the client is when it asks for a token.
#[derive(Clone)]
struct Client {
id: String,
/// What is sent, expanded
secret: Option<String>,
/// A secret registration issued, which the token store keeps. A secret from the config is
/// never copied there: it belongs in the config, or the environment variable the config names.
issued_secret: Option<String>,
}
/// In-flight authorization-code state between `auth_start` and `auth_complete`.
struct Pending {
verifier: String,
state: String,
redirect_uri: String,
token_endpoint: String,
resource: String,
client: Client,
}
/// What `access_token` resolved to.
pub enum TokenState {
/// A usable bearer token.
Have(String),
/// Interactive login is required (reason is user-facing).
NeedsLogin(String),
/// A sign-in is stored but could not be refreshed, for a reason signing in again would not
/// fix — a secret that did not resolve, a server that could not be reached (user-facing).
Unavailable(String),
}
/// OAuth client bound to one MCP server.
pub struct OAuthClient {
server_id: String,
server_url: String,
config: OAuthConfig,
http: reqwest::Client,
store: TokenStore,
pending: Mutex<Option<Pending>>,
/// Whether a `!command` client secret may run: only for a server from the reader's own config
secret_commands: bool,
/// Held while a token is read and refreshed, so calls finding it expired refresh it once
refreshing: tokio::sync::Mutex<()>,
}
impl OAuthClient {
/// Build a client for `server_id` (reached at `server_url`), using the default token store.
pub fn new(server_id: String, server_url: String, config: OAuthConfig) -> Self {
let http = reqwest::Client::builder()
.timeout(REQUEST_TIMEOUT)
.build()
.unwrap_or_else(|_| reqwest::Client::new());
Self {
server_id,
server_url,
config,
http,
store: TokenStore::default_path(),
pending: Mutex::new(None),
secret_commands: false,
refreshing: tokio::sync::Mutex::new(()),
}
}
/// Lets a `!command` client secret run, for a server declared in the reader's own config.
pub fn with_secret_commands(mut self, allowed: bool) -> Self {
self.secret_commands = allowed;
self
}
/// Override the token store (tests).
pub fn with_store(mut self, store: TokenStore) -> Self {
self.store = store;
self
}
/// Return a usable access token: stored-and-valid, refreshed, freshly fetched
/// (client-credentials), or what stands in the way.
///
/// A refresh that fails says why, and only a refusal from the server sends the reader back to
/// `luxe mcp login`. A secret that did not resolve is not "needs authorization": signing in
/// again would fail on the same missing variable.
pub async fn access_token(&self) -> TokenState {
// the second caller reads what the first stored, since a rotating server refuses an old
// refresh token the second time
let _one_at_a_time = self.refreshing.lock().await;
// An entry with no access token is a remembered registration from a login that never
// finished, and sending it would be a bearer header with nothing in it
if let Some(token) = self.store.get(&self.server_id).filter(|t| !t.access_token.is_empty())
{
if !token.is_expired() {
return TokenState::Have(crate::secret::remembered(&token.access_token));
}
if let Some(refresh) = token.refresh_token.as_deref().map(crate::secret::remembered) {
match self.refresh(&refresh, &token).await {
Ok(fresh) => return TokenState::Have(crate::secret::remembered(&fresh)),
// Only a refusal is cured by signing in again; a secret that did not resolve,
// a missing client id or the network would fail the same way
Err(OAuthError::Refused(reason)) => {
tracing::warn!(server = %self.server_id, %reason, "mcp: token refresh refused");
return TokenState::NeedsLogin(format!(
"MCP server '{}' needs authorization — the refresh was refused \
({reason}); run `luxe mcp login --id {}`.",
self.server_id, self.server_id
));
}
Err(reason) => {
tracing::warn!(server = %self.server_id, %reason, "mcp: could not refresh the token");
return TokenState::Unavailable(format!(
"MCP server '{}' could not refresh its sign-in: {reason}",
self.server_id
));
}
}
}
}
if self.config.grant_type == OAuthGrant::ClientCredentials {
return match self.client_credentials().await {
Ok(token) => TokenState::Have(crate::secret::remembered(&token)),
Err(error) => TokenState::NeedsLogin(error.to_string()),
};
}
TokenState::NeedsLogin(format!(
"MCP server '{}' needs authorization — run `luxe mcp login --id {}`.",
self.server_id, self.server_id
))
}
/// Begin an authorization-code login: resolve endpoints, register a client if needed, and
/// return the authorize URL the user opens. `redirect_uri` is where the provider will send the
/// code (a loopback the caller listens on, or the configured pre-registered URI).
pub async fn auth_start(&self, redirect_uri: &str) -> Result<String, OAuthError> {
let resolved = self.resolve().await?;
let authorization = resolved.endpoints.authorization.clone().ok_or_else(|| {
OAuthError::Discovery("no authorization endpoint (set it or enable discovery)".into())
})?;
let token = resolved
.endpoints
.token
.clone()
.ok_or_else(|| OAuthError::Discovery("no token endpoint".into()))?;
let client = self.ensure_client(&resolved.endpoints, redirect_uri).await?;
let Pkce { verifier, challenge } = pkce();
let state = random_state();
let mut url = url::Url::parse(&authorization)
.map_err(|e| OAuthError::Discovery(format!("bad authorization endpoint: {e}")))?;
{
let mut q = url.query_pairs_mut();
q.append_pair("response_type", "code");
q.append_pair("client_id", &client.id);
q.append_pair("redirect_uri", redirect_uri);
q.append_pair("state", &state);
q.append_pair("code_challenge", &challenge);
q.append_pair("code_challenge_method", "S256");
q.append_pair("resource", &resolved.resource);
if let Some(scope) = &self.config.scope {
q.append_pair("scope", scope);
}
}
*self.pending.lock().expect("oauth pending poisoned") = Some(Pending {
verifier,
state,
redirect_uri: redirect_uri.to_string(),
token_endpoint: token,
resource: resolved.resource,
client,
});
Ok(url.to_string())
}
/// Complete an authorization-code login from the provider's redirect URL (contains `code` +
/// `state`, or `error`). Validates `state`, exchanges the code, and stores the token.
pub async fn auth_complete(&self, redirect_url: &str) -> Result<(), OAuthError> {
let pending =
self.pending.lock().expect("oauth pending poisoned").take().ok_or_else(|| {
OAuthError::Config("no login in progress — call auth_start first".into())
})?;
let parsed = url::Url::parse(redirect_url)
.map_err(|e| OAuthError::Config(format!("bad redirect url: {e}")))?;
let field =
|name: &str| parsed.query_pairs().find(|(k, _)| k == name).map(|(_, v)| v.into_owned());
// Checked first: a redirect that does not carry our state is not an answer to our request,
// whatever else it says
if field("state").as_deref() != Some(pending.state.as_str()) {
return Err(OAuthError::StateMismatch);
}
if let Some(error) = field("error") {
return Err(OAuthError::Refused(match field("error_description") {
Some(description) => format!("the server refused: {error} — {description}"),
None => format!("the server refused: {error}"),
}));
}
let code =
field("code").ok_or_else(|| OAuthError::Config("redirect url has no `code`".into()))?;
let token = self.exchange_code(&code, &pending).await?;
Ok(self.store.put(&self.server_id, token)?)
}
/// Interactive loopback login for the CLI: print the authorize URL, wait for the browser to
/// come back, exchange, and store the token.
pub async fn interactive_login(&self) -> Result<(), OAuthError> {
let server = self.server_id.clone();
self.login_with(
|url, redirect| {
println!("\nOpen this URL to authorize '{server}':\n\n {url}\n");
println!("Waiting for the browser redirect on {redirect} …");
},
LOGIN_TIMEOUT,
)
.await?;
println!("Authorized '{}'. Token stored.", self.server_id);
Ok(())
}
/// A loopback login that hands the authorize URL to `show` rather than printing it.
///
/// Args: `(show, timeout)` — `show` gets `(authorize URL, redirect URI)`. The page the browser
/// lands on is written after the exchange, so it says whether signing in worked rather than
/// promising it did.
pub async fn login_with(
&self,
show: impl FnOnce(&str, &str),
timeout: Duration,
) -> Result<(), OAuthError> {
let redirect = self.config.redirect_uri.as_deref().unwrap_or("http://127.0.0.1:0/callback");
let callback = LoopbackCallback::bind(redirect)
.await
.map_err(|e| OAuthError::Callback(e.to_string()))?;
let url = self.auth_start(callback.redirect_uri()).await?;
show(&url, callback.redirect_uri());
let state =
self.pending.lock().expect("oauth pending poisoned").as_ref().map(|p| p.state.clone());
let arrival = tokio::time::timeout(timeout, callback.wait(state.as_deref()))
.await
.map_err(|_| {
OAuthError::Callback(format!(
"no answer from the browser within {} seconds — run the login again",
timeout.as_secs()
))
})?
.map_err(|e| OAuthError::Callback(e.to_string()))?;
let outcome = self.auth_complete(&arrival.redirect_url()).await;
let (status, title, message) = landing(&self.server_id, &outcome);
arrival.answer(status, title, &message).await;
outcome
}
}
/// What the browser tab says once the exchange has run, so a refusal does not read as success:
/// `(status, title, message)`, for [`luxe_core::oauth_loopback::Arrival::answer`] to escape.
fn landing(server: &str, outcome: &Result<(), OAuthError>) -> (u16, &'static str, String) {
match outcome {
Ok(()) => {
(200, "Signed in", format!("Luxe signed in to {server}. You can close this tab."))
}
Err(error) => (
400,
"Luxe couldn't finish the sign-in",
format!("Luxe could not sign in to {server}: {error}"),
),
}
}
fn now_secs() -> u64 {
SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_secs()).unwrap_or(0)
}
#[cfg(test)]
mod tests;

View File

@@ -0,0 +1,237 @@
//! Discovery paths — where the specifications put each metadata document, and how to read
//! what a server's challenge points at.
use serde_json::Value;
use super::endpoints::{endpoints_from, is_loopback, require_secure, Endpoints};
use super::{OAuthClient, OAuthError, Resolved};
impl OAuthClient {
/// Endpoints and resource: configured ones win, then discovery.
pub(super) async fn resolve(&self) -> Result<Resolved, OAuthError> {
let configured = Endpoints {
authorization: self.config.authorization_endpoint.clone(),
token: self.config.token_endpoint.clone(),
registration: self.config.registration_endpoint.clone(),
}
.checked()?;
if configured.authorization.is_some() && configured.token.is_some() {
return Ok(Resolved { endpoints: configured, resource: self.server_url.clone() });
}
let (discovered, resource) = match self.discover().await? {
Some((endpoints, resource)) => (endpoints, resource),
None => (Endpoints::default(), None),
};
Ok(Resolved {
endpoints: Endpoints {
authorization: configured.authorization.or(discovered.authorization),
token: configured.token.or(discovered.token),
registration: configured.registration.or(discovered.registration),
},
resource: resource.unwrap_or_else(|| self.server_url.clone()),
})
}
/// Discovery in the specification's order; see the module docs for why the order matters.
///
/// `Err` when metadata was found and failed its checks, or pointed at an authorization server
/// that would not describe itself: falling back from there would be exactly how the wrong server
/// gets used.
async fn discover(&self) -> Result<Option<(Endpoints, Option<String>)>, OAuthError> {
require_secure(&self.server_url, "the MCP server")?;
let server = url::Url::parse(&self.server_url)
.map_err(|e| OAuthError::Discovery(format!("bad server url: {e}")))?;
if let Some((resource, issuer)) = self.protected_resource(&server).await? {
let endpoints = self.authorization_server(&issuer).await?;
return Ok(Some((endpoints, Some(resource))));
}
Ok(self.origin_metadata(&server).await?.map(|endpoints| (endpoints, None)))
}
/// The protected-resource document (RFC 9728): `(resource, first authorization server)`.
async fn protected_resource(
&self,
server: &url::Url,
) -> Result<Option<(String, String)>, OAuthError> {
// The server's own pointer is an instruction, not a hint: when it names a document, that
// document or nothing
if let Some(pointed) = self.resource_metadata_pointer().await {
return match self.fetch_protected_resource(&pointed, server).await? {
Some(found) => Ok(Some(found)),
None => Err(OAuthError::Discovery(format!(
"{pointed} did not return protected-resource metadata"
))),
};
}
for candidate in protected_resource_candidates(server) {
if let Some(found) = self.fetch_protected_resource(&candidate, server).await? {
return Ok(Some(found));
}
}
Ok(None)
}
/// `resource_metadata` from the `WWW-Authenticate` header an unauthenticated request draws.
async fn resource_metadata_pointer(&self) -> Option<String> {
let initialize = serde_json::json!({
"jsonrpc": "2.0", "id": 0, "method": "initialize",
"params": {
"protocolVersion": luxe_core::mcp_client::MCP_PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": { "name": "luxe", "version": env!("CARGO_PKG_VERSION") }
}
});
let response = self
.http
.post(&self.server_url)
.header(reqwest::header::ACCEPT, "application/json, text/event-stream")
.json(&initialize)
.send()
.await
.ok()?;
if response.status() != reqwest::StatusCode::UNAUTHORIZED {
return None;
}
let header = response.headers().get(reqwest::header::WWW_AUTHENTICATE)?.to_str().ok()?;
auth_param(header, "resource_metadata")
}
/// One protected-resource document, checked. `Ok(None)` when there is none at `url`.
async fn fetch_protected_resource(
&self,
url: &str,
server: &url::Url,
) -> Result<Option<(String, String)>, OAuthError> {
let Some(doc) = self.fetch_json(url).await else {
return Ok(None);
};
let Some(issuer) = doc
.get("authorization_servers")
.and_then(Value::as_array)
.and_then(|servers| servers.first())
.and_then(Value::as_str)
else {
return Ok(None);
};
let resource = doc.get("resource").and_then(Value::as_str).unwrap_or_default();
if !names_the_server(resource, server) {
return Err(OAuthError::Discovery(format!(
"{url} describes {resource:?}, not {server} — refusing to send a token for it"
)));
}
Ok(Some((resource.to_string(), issuer.to_string())))
}
/// Authorization-server metadata for `issuer` (RFC 8414, then OpenID discovery), checked.
async fn authorization_server(&self, issuer: &str) -> Result<Endpoints, OAuthError> {
let url = url::Url::parse(issuer)
.map_err(|e| OAuthError::Discovery(format!("bad authorization server: {e}")))?;
if url.scheme() != "https" && !is_loopback(&url) {
return Err(OAuthError::Insecure(format!(
"the authorization server {issuer} is not https"
)));
}
for candidate in authorization_server_candidates(&url) {
let Some(doc) = self.fetch_json(&candidate).await else {
continue;
};
let endpoints = endpoints_from(&doc, &candidate, issuer)?;
if endpoints.authorization.is_some() || endpoints.token.is_some() {
return Ok(endpoints);
}
}
Err(OAuthError::Discovery(format!("{issuer} publishes no authorization server metadata")))
}
/// The origin lookup, for a server that publishes no protected-resource metadata.
async fn origin_metadata(&self, server: &url::Url) -> Result<Option<Endpoints>, OAuthError> {
let Some(origin) = origin_of(server) else { return Ok(None) };
for suffix in
["/.well-known/oauth-authorization-server", "/.well-known/openid-configuration"]
{
let candidate = format!("{origin}{suffix}");
let Some(doc) = self.fetch_json(&candidate).await else {
continue;
};
let endpoints = endpoints_from(&doc, &candidate, &origin)?;
if endpoints.authorization.is_some() || endpoints.token.is_some() {
return Ok(Some(endpoints));
}
}
Ok(None)
}
/// GET `url` as JSON, or `None` for anything other than a successful JSON answer.
async fn fetch_json(&self, url: &str) -> Option<Value> {
let response = self.http.get(url).send().await.ok()?;
if !response.status().is_success() {
return None;
}
response.json::<Value>().await.ok()
}
}
/// Where RFC 9728 puts the protected-resource document for `server`: the path form, then the root.
pub(super) fn protected_resource_candidates(server: &url::Url) -> Vec<String> {
let Some(origin) = origin_of(server) else {
return Vec::new();
};
let path = server.path().trim_end_matches('/');
let mut candidates = Vec::new();
if !path.is_empty() {
candidates.push(format!("{origin}/.well-known/oauth-protected-resource{path}"));
}
candidates.push(format!("{origin}/.well-known/oauth-protected-resource"));
candidates
}
/// Where RFC 8414 and OpenID discovery put an issuer's metadata, in that order.
pub(super) fn authorization_server_candidates(issuer: &url::Url) -> Vec<String> {
let Some(origin) = origin_of(issuer) else {
return Vec::new();
};
let path = issuer.path().trim_end_matches('/');
let mut candidates = vec![format!("{origin}/.well-known/oauth-authorization-server{path}")];
candidates.push(format!("{origin}{path}/.well-known/openid-configuration"));
if !path.is_empty() {
candidates.push(format!("{origin}/.well-known/openid-configuration{path}"));
}
candidates.dedup();
candidates
}
/// Whether a protected-resource document's `resource` names the server it was fetched for: the
/// same origin, and the server's path at or under the resource's, a whole segment at a time.
pub(super) fn names_the_server(resource: &str, server: &url::Url) -> bool {
let Ok(resource) = url::Url::parse(resource) else {
return false;
};
if origin_of(&resource) != origin_of(server) {
return false;
}
let owned = resource.path().trim_end_matches('/');
let path = server.path().trim_end_matches('/');
owned.is_empty() || path == owned || path.starts_with(&format!("{owned}/"))
}
/// `scheme://host[:port]`, the part of a URL two documents must share to describe one server.
pub(super) fn origin_of(url: &url::Url) -> Option<String> {
// Already bracketed for an IPv6 literal
let host = url.host_str()?;
Some(format!(
"{}://{host}{}",
url.scheme(),
url.port().map(|port| format!(":{port}")).unwrap_or_default()
))
}
/// One parameter of a `WWW-Authenticate` challenge: `resource_metadata="…"`, quoted or bare.
pub(super) fn auth_param(header: &str, name: &str) -> Option<String> {
let at = header.find(&format!("{name}="))? + name.len() + 1;
let rest = &header[at..];
let value = match rest.strip_prefix('"') {
Some(quoted) => quoted.split('"').next()?,
None => rest.split([',', ' ']).next()?,
};
(!value.is_empty()).then(|| value.to_string())
}

View File

@@ -0,0 +1,77 @@
//! Endpoints — where an authorization code, a client secret or a token may be sent.
//!
//! Every endpoint is checked before it is used, discovered or configured: https, or plain http on
//! this machine. A metadata document must also name its issuer and be the one it was asked for,
//! so a document served from one place cannot send a token somewhere else.
use serde_json::Value;
use super::OAuthError;
/// The resolved OAuth endpoints for a server.
#[derive(Debug, Clone, Default)]
pub(super) struct Endpoints {
pub(super) authorization: Option<String>,
pub(super) token: Option<String>,
pub(super) registration: Option<String>,
}
impl Endpoints {
/// These endpoints, once every one of them is somewhere a secret may go.
pub(super) fn checked(self) -> Result<Self, OAuthError> {
for (endpoint, what) in [
(&self.authorization, "the authorization endpoint"),
(&self.token, "the token endpoint"),
(&self.registration, "the registration endpoint"),
] {
if let Some(endpoint) = endpoint {
require_secure(endpoint, what)?;
}
}
Ok(self)
}
}
/// `url` is somewhere a code or a token may go: https, or plain http on this machine.
pub(crate) fn require_secure(url: &str, what: &str) -> Result<(), OAuthError> {
let parsed = url::Url::parse(url)
.map_err(|e| OAuthError::Insecure(format!("{what} {url} is not a URL: {e}")))?;
match parsed.scheme() {
"https" => Ok(()),
"http" if is_loopback(&parsed) => Ok(()),
_ => Err(OAuthError::Insecure(format!(
"{what} {url} is not https, so nothing will be sent to it"
))),
}
}
pub(super) fn is_loopback(url: &url::Url) -> bool {
matches!(url.host_str(), Some("127.0.0.1" | "localhost" | "[::1]"))
}
/// The endpoints the authorization-server document at `candidate` describes, refused unless it
/// names `issuer` as itself (RFC 8414 requires the field) and every endpoint is secure.
pub(super) fn endpoints_from(
doc: &Value,
candidate: &str,
issuer: &str,
) -> Result<Endpoints, OAuthError> {
match doc.get("issuer").and_then(Value::as_str) {
Some(claimed) if claimed.trim_end_matches('/') == issuer.trim_end_matches('/') => {}
Some(claimed) => {
return Err(OAuthError::Discovery(format!(
"{candidate} says it is {claimed:?}, not {issuer} — refusing it"
)))
}
None => {
return Err(OAuthError::Discovery(format!("{candidate} names no issuer — refusing it")))
}
}
let field = |k: &str| doc.get(k).and_then(Value::as_str).map(str::to_string);
Endpoints {
authorization: field("authorization_endpoint"),
token: field("token_endpoint"),
registration: field("registration_endpoint"),
}
.checked()
}

View File

@@ -0,0 +1,40 @@
//! Errors — why a sign-in, a refresh or a discovery produced no token.
use crate::secret::SecretError;
use crate::token_store::TokenStoreError;
/// Why an OAuth step did not work out.
///
/// Each variant carries the sentence the reader sees, so a caller shows it as it is. What the
/// variants are for is the caller that has to act differently: a refresh the server
/// [refused](Self::Refused) sends the reader back to `luxe mcp login`, and nothing else does.
#[derive(Debug, thiserror::Error)]
pub enum OAuthError {
/// Discovery found nothing, or a document that failed its checks
#[error("{0}")]
Discovery(String),
/// An endpoint that would send a code or a token somewhere it could be read
#[error("{0}")]
Insecure(String),
/// The redirect was not an answer to this login's request
#[error("state mismatch — possible CSRF; login aborted")]
StateMismatch,
/// The server answered and said no: an error redirect, an error status from the token endpoint
#[error("{0}")]
Refused(String),
/// The server could not be reached, or its answer could not be read
#[error("{0}")]
Network(String),
/// The login cannot go on as configured or as called
#[error("{0}")]
Config(String),
/// The browser leg: the loopback listener, or nobody coming back to it
#[error("{0}")]
Callback(String),
/// The token store could not be written
#[error(transparent)]
Storage(#[from] TokenStoreError),
/// A configured secret did not resolve
#[error(transparent)]
Secret(#[from] SecretError),
}

View File

@@ -0,0 +1,159 @@
//! Grants — the token endpoint: a code exchange, client credentials and a refresh.
use serde_json::Value;
use super::endpoints::require_secure;
use super::{now_secs, Client, OAuthClient, OAuthError, Pending};
use crate::token_store::StoredToken;
impl OAuthClient {
/// Exchange an authorization code for tokens.
pub(super) async fn exchange_code(
&self,
code: &str,
pending: &Pending,
) -> Result<StoredToken, OAuthError> {
let mut form = vec![
("grant_type", "authorization_code".to_string()),
("code", code.to_string()),
("redirect_uri", pending.redirect_uri.clone()),
("client_id", pending.client.id.clone()),
("code_verifier", pending.verifier.clone()),
("resource", pending.resource.clone()),
];
if let Some(secret) = &pending.client.secret {
form.push(("client_secret", secret.clone()));
}
self.token_request(&pending.token_endpoint, &form, &pending.client, &pending.resource).await
}
/// The client-credentials grant.
pub(super) async fn client_credentials(&self) -> Result<String, OAuthError> {
let resolved = self.resolve().await?;
let token_endpoint = resolved
.endpoints
.token
.ok_or_else(|| OAuthError::Discovery("no token endpoint".into()))?;
let id = self
.config
.client_id
.clone()
.ok_or_else(|| OAuthError::Config("client_credentials needs a client_id".into()))?;
let client = Client { id, secret: self.configured_secret().await?, issued_secret: None };
let mut form = vec![
("grant_type", "client_credentials".to_string()),
("client_id", client.id.clone()),
("resource", resolved.resource.clone()),
];
if let Some(secret) = &client.secret {
form.push(("client_secret", secret.clone()));
}
if let Some(scope) = &self.config.scope {
form.push(("scope", scope.clone()));
}
let token = self.token_request(&token_endpoint, &form, &client, &resolved.resource).await?;
self.store.put(&self.server_id, token.clone())?;
Ok(token.access_token.clone())
}
/// Refresh an access token; stores and returns the new access token.
///
/// Against the token endpoint and resource the token was issued for, when it recorded them:
/// a refresh that re-ran discovery could land somewhere the token never came from.
pub(super) async fn refresh(
&self,
refresh_token: &str,
prior: &StoredToken,
) -> Result<String, OAuthError> {
let (token_endpoint, resource) = match (&prior.token_endpoint, &prior.resource) {
(Some(endpoint), Some(resource)) => {
require_secure(endpoint, "the token endpoint")?;
(endpoint.clone(), resource.clone())
}
_ => {
let resolved = self.resolve().await?;
let token = resolved
.endpoints
.token
.ok_or_else(|| OAuthError::Discovery("no token endpoint".into()))?;
(token, resolved.resource)
}
};
let id = self
.config
.client_id
.clone()
.or_else(|| prior.client_id.clone())
.ok_or_else(|| OAuthError::Config("no client_id for refresh".into()))?;
// A configured client's secret comes from the config; only a registered one's is stored
let issued =
if self.config.client_id.is_some() { None } else { prior.client_secret.clone() };
let secret = self.configured_secret().await?.or_else(|| issued.clone());
let client = Client { id, secret, issued_secret: issued };
let mut form = vec![
("grant_type", "refresh_token".to_string()),
("refresh_token", refresh_token.to_string()),
("client_id", client.id.clone()),
("resource", resource.clone()),
];
if let Some(secret) = &client.secret {
form.push(("client_secret", secret.clone()));
}
let mut token = self.token_request(&token_endpoint, &form, &client, &resource).await?;
// Providers may omit a new refresh token; keep the old one.
if token.refresh_token.is_none() {
token.refresh_token = Some(refresh_token.to_string());
}
let access = token.access_token.clone();
self.store.put(&self.server_id, token)?;
Ok(access)
}
/// POST a token request and parse the response into a [`StoredToken`], recording where it came
/// from and carrying a registration's issued secret forward.
async fn token_request(
&self,
endpoint: &str,
form: &[(&str, String)],
client: &Client,
resource: &str,
) -> Result<StoredToken, OAuthError> {
use OAuthError::{Network, Refused};
let resp = self
.http
.post(endpoint)
.form(form)
.send()
.await
.map_err(|e| Network(format!("token request failed: {e}")))?;
let status = resp.status();
// An error status is a refusal whatever its body, so the body is read leniently for it
let doc: Result<Value, _> = resp.json().await;
if !status.is_success() {
let doc = doc.unwrap_or_default();
let err = doc.get("error").and_then(Value::as_str).unwrap_or(status.as_str());
return Err(Refused(match doc.get("error_description").and_then(Value::as_str) {
Some(description) => format!("token endpoint error: {err} — {description}"),
None => format!("token endpoint error: {err}"),
}));
}
let doc = doc.map_err(|e| Network(format!("bad token response: {e}")))?;
let access_token = doc
.get("access_token")
.and_then(Value::as_str)
.ok_or_else(|| Network("token response missing access_token".into()))?
.to_string();
let refresh_token = doc.get("refresh_token").and_then(Value::as_str).map(str::to_string);
let expires_at_secs =
doc.get("expires_in").and_then(Value::as_u64).map(|secs| now_secs() + secs);
Ok(StoredToken {
access_token,
refresh_token,
expires_at_secs,
client_id: Some(client.id.clone()),
client_secret: client.issued_secret.clone(),
token_endpoint: Some(endpoint.to_string()),
resource: Some(resource.to_string()),
})
}
}

View File

@@ -0,0 +1,98 @@
//! Registration — which client the login is, and registering one when it has none.
use serde_json::Value;
use super::endpoints::Endpoints;
use super::{Client, OAuthClient, OAuthError};
use crate::secret::SecretError;
impl OAuthClient {
/// Use the configured client id, a previously-registered one from the store, or register a new
/// client dynamically (RFC 7591).
pub(super) async fn ensure_client(
&self,
endpoints: &Endpoints,
redirect_uri: &str,
) -> Result<Client, OAuthError> {
if let Some(id) = self.config.client_id.clone() {
return Ok(Client { id, secret: self.configured_secret().await?, issued_secret: None });
}
if let Some(token) = self.store.get(&self.server_id) {
if let Some(id) = token.client_id.clone() {
let issued = token.client_secret.clone();
return Ok(Client { id, secret: issued.clone(), issued_secret: issued });
}
}
let endpoint = endpoints.registration.clone().ok_or_else(|| {
OAuthError::Config(
"no client_id configured and no dynamic registration endpoint — register a \
client with the provider and set `client_id` (and `client_secret`) in the \
server's auth"
.into(),
)
})?;
self.register_client(&endpoint, redirect_uri).await
}
/// The configured secret, resolved ([`crate::secret::resolve_secret`]), or `None` when there
/// is none.
///
/// The one place a configured secret is read, so every flow — the code exchange, a refresh,
/// client credentials — sends the same thing, with `${VAR}` expanded rather than the reference
/// itself.
pub(super) async fn configured_secret(&self) -> Result<Option<String>, SecretError> {
let Some(secret) = &self.config.client_secret else {
return Ok(None);
};
let what = format!("the client secret for '{}'", self.server_id);
crate::secret::resolve_secret(secret.as_written(), self.secret_commands, &what)
.await
.map(Some)
}
/// Dynamic client registration (RFC 7591). Persists the issued client id/secret in the store.
async fn register_client(
&self,
endpoint: &str,
redirect_uri: &str,
) -> Result<Client, OAuthError> {
let body = serde_json::json!({
"client_name": "luxe",
"redirect_uris": [redirect_uri],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "none",
});
let resp = self
.http
.post(endpoint)
.json(&body)
.send()
.await
.map_err(|e| OAuthError::Network(format!("client registration failed: {e}")))?;
if !resp.status().is_success() {
return Err(OAuthError::Refused(format!(
"client registration returned HTTP {}",
resp.status()
)));
}
let doc: Value = resp
.json()
.await
.map_err(|e| OAuthError::Network(format!("bad registration response: {e}")))?;
let client_id = doc
.get("client_id")
.and_then(Value::as_str)
.ok_or_else(|| OAuthError::Network("registration response missing client_id".into()))?
.to_string();
let client_secret = doc.get("client_secret").and_then(Value::as_str).map(str::to_string);
// Remember the registration so we don't re-register on every login.
let mut token = self.store.get(&self.server_id).unwrap_or_default();
token.client_id = Some(client_id.clone());
token.client_secret = client_secret.clone();
if let Err(error) = self.store.put(&self.server_id, token) {
tracing::warn!(server = %self.server_id, %error, "mcp: could not remember the registered client");
}
Ok(Client { id: client_id, secret: client_secret.clone(), issued_secret: client_secret })
}
}

View File

@@ -0,0 +1,284 @@
use super::discovery::{
auth_param, authorization_server_candidates, names_the_server, origin_of,
protected_resource_candidates,
};
use super::endpoints::is_loopback;
use super::*;
use crate::token_store::StoredToken;
fn url(text: &str) -> url::Url {
url::Url::parse(text).expect("a URL")
}
/// RFC 9728 puts the document between the host and the path, and the path form is tried before
/// the root — which is the whole of the Asana case: its root describes a retired server.
#[test]
fn protected_resource_is_looked_for_at_the_path_first() {
assert_eq!(
protected_resource_candidates(&url("https://mcp.asana.com/v2/mcp")),
[
"https://mcp.asana.com/.well-known/oauth-protected-resource/v2/mcp",
"https://mcp.asana.com/.well-known/oauth-protected-resource",
]
);
assert_eq!(
protected_resource_candidates(&url("http://127.0.0.1:9000/")),
["http://127.0.0.1:9000/.well-known/oauth-protected-resource"],
"a server at the root has one place to look, with its port"
);
}
#[test]
fn authorization_server_metadata_follows_rfc_8414_then_openid() {
assert_eq!(
authorization_server_candidates(&url("https://app.asana.com")),
[
"https://app.asana.com/.well-known/oauth-authorization-server",
"https://app.asana.com/.well-known/openid-configuration",
]
);
assert_eq!(
authorization_server_candidates(&url("https://id.example.com/tenant/7")),
[
"https://id.example.com/.well-known/oauth-authorization-server/tenant/7",
"https://id.example.com/tenant/7/.well-known/openid-configuration",
"https://id.example.com/.well-known/openid-configuration/tenant/7",
]
);
}
/// A document may describe the server or a resource above it, never a different one.
#[test]
fn a_resource_must_name_the_server_it_was_fetched_for() {
let server = url("https://mcp.asana.com/v2/mcp");
for resource in
["https://mcp.asana.com/v2/mcp", "https://mcp.asana.com/v2", "https://mcp.asana.com"]
{
assert!(names_the_server(resource, &server), "{resource}");
}
for resource in [
"https://evil.example.com/v2/mcp",
"http://mcp.asana.com/v2/mcp",
"https://mcp.asana.com:8443/v2/mcp",
"https://mcp.asana.com/v2/mcp/deeper",
"https://mcp.asana.com/v",
"not a url",
"",
] {
assert!(!names_the_server(resource, &server), "{resource}");
}
}
#[test]
fn the_metadata_pointer_is_read_from_the_challenge() {
let asana = r#"Bearer realm="Asana MCP", resource_metadata="https://mcp.asana.com/.well-known/oauth-protected-resource/v2", error="invalid_request""#;
assert_eq!(
auth_param(asana, "resource_metadata").as_deref(),
Some("https://mcp.asana.com/.well-known/oauth-protected-resource/v2")
);
assert_eq!(
auth_param("Bearer resource_metadata=https://x.example/m, realm=y", "resource_metadata")
.as_deref(),
Some("https://x.example/m"),
"an unquoted value ends at the next parameter"
);
assert_eq!(auth_param(r#"Bearer realm="x""#, "resource_metadata"), None);
assert_eq!(auth_param(r#"Bearer resource_metadata="""#, "resource_metadata"), None);
}
#[test]
fn loopback_is_the_three_hosts_a_browser_can_hand_a_code_to() {
for host in ["http://127.0.0.1:1/", "http://localhost:1/", "http://[::1]:1/"] {
assert!(is_loopback(&url(host)), "{host}");
}
for host in ["http://127.0.0.2:1/", "http://example.com:1/", "http://0.0.0.0:1/"] {
assert!(!is_loopback(&url(host)), "{host}");
}
assert_eq!(origin_of(&url("http://[::1]:8765/x")).as_deref(), Some("http://[::1]:8765"));
}
/// What the tab says is what happened, and what a provider wrote in an error cannot become markup.
#[test]
fn the_landing_page_says_what_happened() {
let (status, _, signed_in) = landing("asana", &Ok(()));
assert_eq!(status, 200);
assert!(signed_in.contains("signed in to asana"), "{signed_in}");
let (status, title, refused) = landing(
"asana",
&Err(OAuthError::Refused("the server refused: <script>x</script>".into())),
);
assert_eq!(status, 400);
assert!(refused.contains("could not sign in"), "{refused}");
let page = luxe_core::oauth_loopback::page(title, &refused, "#b45309");
assert!(page.contains("&lt;script&gt;") && !page.contains("<script>"), "{page}");
}
/// https anywhere, plain http only on this machine, and nothing else.
#[test]
fn only_https_or_loopback_http_is_secure() {
for ok in [
"https://auth.example.com/t",
"http://127.0.0.1:9/t",
"http://localhost/t",
"http://[::1]:8/t",
] {
assert!(require_secure(ok, "the token endpoint").is_ok(), "{ok}");
}
for bad in ["http://auth.example.com/t", "ftp://auth.example.com/t", "not a url"] {
let error = require_secure(bad, "the token endpoint").unwrap_err();
assert!(matches!(error, OAuthError::Insecure(_)), "{error:?}");
assert!(error.to_string().contains("the token endpoint"), "{error}");
}
}
/// A loopback server answering every authorization-server metadata path with `doc`, and nothing
/// else; returns its base URL.
async fn serve_origin_metadata(doc: impl Fn(&str) -> serde_json::Value + Send + 'static) -> String {
use tokio::io::{AsyncReadExt, AsyncWriteExt};
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let base = format!("http://{}", listener.local_addr().unwrap());
let served = base.clone();
tokio::spawn(async move {
while let Ok((mut socket, _)) = listener.accept().await {
let mut request = [0u8; 4096];
let read = socket.read(&mut request).await.unwrap_or(0);
let request = String::from_utf8_lossy(&request[..read]).into_owned();
let (status, body) = if request.contains("/.well-known/oauth-authorization-server") {
("200 OK", doc(&served).to_string())
} else {
("404 Not Found", "{}".to_string())
};
let response = format!(
"HTTP/1.1 {status}\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\
Connection: close\r\n\r\n{body}",
body.len()
);
let _ = socket.write_all(response.as_bytes()).await;
}
});
base
}
/// The origin fallback gets the checks discovery gets: a document must name its issuer, and an
/// endpoint in it must be secure.
#[tokio::test]
async fn the_origin_fallback_is_checked_like_discovery() {
for (doc, refusal) in [
(
(|base: &str| serde_json::json!({"issuer": base, "token_endpoint": "http://evil.example/t"}))
as fn(&str) -> serde_json::Value,
"not https",
),
(
|base: &str| serde_json::json!({"token_endpoint": format!("{base}/t")}),
"names no issuer",
),
] {
let base = serve_origin_metadata(doc).await;
let client =
OAuthClient::new("legacy".into(), format!("{base}/v2/mcp"), OAuthConfig::default());
let error = client.auth_start("http://127.0.0.1:9/callback").await.unwrap_err().to_string();
assert!(error.contains(refusal), "{error}");
}
}
/// A server reached over plain http off this machine has nothing it says trusted: its metadata
/// could be anyone's, so sign-in stops before discovery.
#[tokio::test]
async fn a_plain_http_server_is_not_signed_in_to() {
let client = OAuthClient::new(
"plain".into(),
"http://mcp.example.test/v2/mcp".into(),
OAuthConfig::default(),
);
let error = client.auth_start("http://127.0.0.1:9/callback").await.unwrap_err().to_string();
assert!(error.contains("not https"), "{error}");
}
/// A sign-in stored before endpoints were checked is checked on refresh: its refresh token does
/// not go to a plain-http endpoint.
#[tokio::test]
async fn a_stored_plain_http_token_endpoint_is_not_refreshed_against() {
let dir = tempfile::tempdir().unwrap();
let store = TokenStore::new(dir.path().join("t.json"));
let token = StoredToken {
access_token: "AT-old".into(),
refresh_token: Some("RT-old".into()),
expires_at_secs: Some(1),
client_id: Some("1234".into()),
client_secret: None,
token_endpoint: Some("http://evil.example/t".into()),
resource: Some("https://mcp.example.test/v2/mcp".into()),
};
store.put("old", token).unwrap();
let client = OAuthClient::new(
"old".into(),
"https://mcp.example.test/v2/mcp".into(),
OAuthConfig::default(),
)
.with_store(store);
let TokenState::Unavailable(reason) = client.access_token().await else {
panic!("a plain-http endpoint must not be refreshed against");
};
assert!(reason.contains("not https"), "{reason}");
}
/// Two calls that find the token expired refresh it once: the second waits for the first and reads
/// what it stored. A server rotating refresh tokens would refuse the second use of the old one and
/// send the reader to sign in again for nothing.
#[tokio::test]
async fn two_concurrent_refreshes_hit_the_endpoint_once() {
use std::sync::atomic::{AtomicUsize, Ordering};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let base = format!("http://{}", listener.local_addr().unwrap());
let refreshes = std::sync::Arc::new(AtomicUsize::new(0));
let counted = refreshes.clone();
tokio::spawn(async move {
while let Ok((mut socket, _)) = listener.accept().await {
let mut request = [0u8; 4096];
let read = socket.read(&mut request).await.unwrap_or(0);
let request = String::from_utf8_lossy(&request[..read]).into_owned();
// the old refresh token is good once, as a rotating server has it
let body = if request.contains("refresh_token=RT-1")
&& counted.fetch_add(1, Ordering::SeqCst) == 0
{
r#"{"access_token":"AT-2","token_type":"Bearer","expires_in":3600,"refresh_token":"RT-2"}"#
} else {
r#"{"error":"invalid_grant"}"#
};
let status = if body.contains("AT-2") { "200 OK" } else { "400 Bad Request" };
let response = format!(
"HTTP/1.1 {status}\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\
Connection: close\r\n\r\n{body}",
body.len()
);
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
let _ = socket.write_all(response.as_bytes()).await;
}
});
let dir = tempfile::tempdir().unwrap();
let store = TokenStore::new(dir.path().join("t.json"));
let token = StoredToken {
access_token: "AT-1".into(),
refresh_token: Some("RT-1".into()),
expires_at_secs: Some(1),
client_id: Some("1234".into()),
client_secret: None,
token_endpoint: Some(format!("{base}/token")),
resource: Some("https://mcp.example.test/v2/mcp".into()),
};
store.put("rotating", token).unwrap();
let client = OAuthClient::new(
"rotating".into(),
"https://mcp.example.test/v2/mcp".into(),
OAuthConfig::default(),
)
.with_store(store);
let (one, two) = tokio::join!(client.access_token(), client.access_token());
for state in [one, two] {
let TokenState::Have(token) = state else { panic!("a refresh was refused") };
assert_eq!(token, "AT-2");
}
assert_eq!(refreshes.load(Ordering::SeqCst), 1);
}

View File

@@ -0,0 +1,598 @@
//! Server registry — lazy MCP connections + a persisted tool-metadata cache.
//!
//! Connects servers on demand (or eagerly / keep-alive per config), remembers each server's tools
//! in a disk cache so `search`/`describe` work with no live connection, and idle-disconnects lazy
//! servers. All the state the [`crate::tool::McpProxyTool`] needs lives here.
use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;
use std::time::{Duration, Instant};
use serde::{Deserialize, Serialize};
use tokio::sync::Mutex;
use luxe_core::mcp_client::{
McpAuth, McpConnection, McpError, McpLifecycle, McpServerConfig, McpTool, McpToolResult,
McpTransport,
};
use luxe_core::mcp_stdio::McpStdioClient;
use crate::oauth::OAuthClient;
/// Default idle window before a lazy server disconnects.
const DEFAULT_IDLE: Duration = Duration::from_secs(10 * 60);
/// How long a call may take when its server does not say (`timeout_secs`).
const DEFAULT_CALL_TIMEOUT: Duration = luxe_core::tool::NETWORK_TOOL_TIMEOUT;
/// Why a tool could not be found, reached or finished.
#[derive(Debug, thiserror::Error)]
pub enum RegistryError {
/// No server offers a tool by that name
#[error("unknown MCP tool '{0}' — use mcp({{ search: \"...\" }}) to discover tools")]
UnknownTool(String),
/// A bare name that two or more servers offer
#[error("'{name}' is ambiguous: say which, one of {}", .candidates.join(", "))]
Ambiguous {
/// What was asked for
name: String,
/// Each server's `server/name` for it
candidates: Vec<String>,
},
/// No server by that id is configured
#[error("no such MCP server '{0}'")]
NoSuchServer(String),
/// The call outlived its server's deadline, so its server was stopped
#[error(
"`{tool}` did not answer within {secs}s, so its server was stopped with its process \
group; it restarts on the next call. Anything it launched in a group of its own \
— a nested agent's shell command — may still finish, so check before retrying. \
A server that is slow by design can declare `timeout_secs` in its MCP config."
)]
TimedOut {
/// What was called
tool: String,
/// The deadline it missed
secs: u64,
},
/// The server could not be reached, or said no
#[error(transparent)]
Server(#[from] McpError),
}
/// A resolved tool: which server owns it, its server-side name, and its schema. `presented` is the
/// discovery-facing `server_id/raw_name` the agent passes back to `describe`/`call`.
#[derive(Debug, Clone)]
pub struct ToolRef {
/// The server that owns the tool
pub server_id: String,
/// The tool's name on that server
pub raw_name: String,
/// `server_id/raw_name`, as the agent passes it back
pub presented: String,
/// What the server says the tool does
pub description: String,
/// The tool's JSON input schema, as the server declared it
pub input_schema: serde_json::Value,
}
/// One server's cached tool list, tagged with the transport hash it was captured under (so a
/// changed command/url invalidates it).
#[derive(Debug, Clone, Serialize, Deserialize)]
struct CachedMeta {
config_hash: u64,
tools: Vec<McpTool>,
}
/// A live connection plus the bookkeeping for idle-disconnect.
struct Live {
conn: Arc<dyn McpConnection>,
last_used: Instant,
idle: Option<Duration>,
}
/// Lazy MCP server manager: owns configs, live connections, and the metadata cache.
pub struct ServerRegistry {
servers: Vec<McpServerConfig>,
live: Mutex<HashMap<String, Live>>,
/// One lock per server, held while connecting it
connecting: Mutex<HashMap<String, Arc<Mutex<()>>>>,
metadata: Mutex<HashMap<String, CachedMeta>>,
cache_path: Option<PathBuf>,
}
impl ServerRegistry {
/// Build a manager over the enabled servers, persisting tool metadata to `cache_path` (e.g.
/// `.luxe/mcp-metadata.json`). MCP *calls* are permission-gated at the engine dispatch
/// choke point (keyed by the `mcp` tool's `server/name` target), so the manager itself does
/// not re-gate.
pub fn new(servers: Vec<McpServerConfig>, cache_path: Option<PathBuf>) -> Self {
let metadata = cache_path
.as_ref()
.and_then(|p| std::fs::read_to_string(p).ok())
.and_then(|s| serde_json::from_str(&s).ok())
.unwrap_or_default();
Self {
servers: servers.into_iter().filter(|s| s.enabled).collect(),
live: Mutex::new(HashMap::new()),
connecting: Mutex::new(HashMap::new()),
metadata: Mutex::new(metadata),
cache_path,
}
}
/// Whether any servers are configured (the proxy tool registers only when true).
pub fn has_servers(&self) -> bool {
!self.servers.is_empty()
}
/// Server ids, for status surfaces.
pub fn server_ids(&self) -> Vec<String> {
self.servers.iter().map(|s| s.id.clone()).collect()
}
/// Connect eager/keep-alive servers now and spawn the idle sweeper. Lazy servers stay cold.
pub async fn start(self: &Arc<Self>) {
for server in &self.servers {
if matches!(server.lifecycle, McpLifecycle::Eager | McpLifecycle::KeepAlive) {
if let Err(error) = self.ensure_connected(&server.id).await {
tracing::warn!(server = %server.id, %error, "mcp: eager connect failed");
}
}
}
let weak = Arc::downgrade(self);
tokio::spawn(async move {
let mut tick = tokio::time::interval(Duration::from_secs(30));
loop {
tick.tick().await;
match weak.upgrade() {
Some(manager) => manager.sweep_idle().await,
None => break, // manager dropped — stop sweeping
}
}
});
}
/// Search cached tool metadata across all servers, returning matches (name/description
/// substring, case-insensitive; empty query = everything). Populates the cache lazily.
pub async fn search(&self, query: &str) -> Vec<ToolRef> {
let needle = query.trim().to_lowercase();
let mut hits = Vec::new();
for server in &self.servers {
let refs = match self.tool_refs(server).await {
Ok(refs) => refs,
Err(error) => {
tracing::warn!(server = %server.id, %error, "mcp: metadata unavailable");
continue;
}
};
hits.extend(refs.into_iter().filter(|r| matches(r, &needle)));
}
hits
}
/// Resolve `server_id/raw_name`, or a bare `raw_name` exactly one server offers, to its
/// [`ToolRef`].
///
/// A named server is the only one consulted, so calling its tool starts no other server just
/// to list theirs. A bare name has to ask them all, and two answers are an error naming both.
pub async fn describe(&self, name: &str) -> Result<ToolRef, RegistryError> {
let unknown = || RegistryError::UnknownTool(name.to_string());
if let Some((id, raw)) = name.split_once('/') {
if let Some(server) = self.servers.iter().find(|server| server.id == id) {
let refs = self.tool_refs(server).await?;
return refs.into_iter().find(|r| r.raw_name == raw).ok_or_else(unknown);
}
}
let mut found = Vec::new();
for server in &self.servers {
if let Ok(refs) = self.tool_refs(server).await {
found
.extend(refs.into_iter().filter(|r| r.presented == name || r.raw_name == name));
}
}
match found.len() {
0 => Err(unknown()),
1 => Ok(found.remove(0)),
_ => {
let candidates = found.into_iter().map(|r| r.presented).collect();
Err(RegistryError::Ambiguous { name: name.to_string(), candidates })
}
}
}
/// Call a tool (resolved from `name`) with `arguments`. Connects the owning server lazily.
/// Returns the server's result text (as data — never interpreted). Permission gating happens
/// upstream at engine dispatch.
///
/// Bounded by the server's `timeout_secs`. A call given up on — by that deadline, or because
/// the turn was cancelled and this future dropped — is [abandoned](McpConnection::abandon),
/// which for stdio stops the server's whole tree; the next call starts it fresh.
pub async fn call(
&self,
name: &str,
arguments: serde_json::Value,
) -> Result<McpToolResult, RegistryError> {
let target = self.describe(name).await?;
let conn = self.ensure_connected(&target.server_id).await?;
let deadline = self.call_timeout(&target.server_id);
let mut abandon = AbandonOnDrop(Some(conn.clone()));
let result =
tokio::time::timeout(deadline, conn.call_tool(&target.raw_name, arguments)).await;
match result {
Ok(result) => {
abandon.0 = None;
Ok(result?)
}
Err(_) => {
Err(RegistryError::TimedOut { tool: name.to_string(), secs: deadline.as_secs() })
}
}
}
/// The deadline for one call to `server_id`.
fn call_timeout(&self, server_id: &str) -> Duration {
self.servers
.iter()
.find(|server| server.id == server_id)
.and_then(|server| server.timeout_secs)
.filter(|secs| *secs > 0)
.map_or(DEFAULT_CALL_TIMEOUT, Duration::from_secs)
}
/// The longest any configured server's call may take — the ceiling the engine's own deadline
/// for the `mcp` tool has to clear, so the server's deadline is the one that fires.
pub fn longest_call_timeout(&self) -> Duration {
self.servers
.iter()
.map(|server| self.call_timeout(&server.id))
.max()
.unwrap_or(DEFAULT_CALL_TIMEOUT)
}
/// Cached (or freshly listed) tool refs for one server, honoring its `exclude_tools`.
async fn tool_refs(&self, server: &McpServerConfig) -> Result<Vec<ToolRef>, RegistryError> {
let tools = self.ensure_metadata(server).await?;
Ok(tools
.into_iter()
.filter(|t| !server.exclude_tools.iter().any(|x| x == &t.name))
.map(|t| ToolRef {
presented: format!("{}/{}", server.id, t.name),
server_id: server.id.clone(),
raw_name: t.name,
description: t.description,
input_schema: t.input_schema,
})
.collect())
}
/// Return a server's tools from cache, or connect once to list + cache them (memory + disk).
async fn ensure_metadata(
&self,
server: &McpServerConfig,
) -> Result<Vec<McpTool>, RegistryError> {
let hash = transport_hash(&server.transport);
if let Some(meta) = self.metadata.lock().await.get(&server.id) {
if meta.config_hash == hash {
return Ok(meta.tools.clone());
}
}
let conn = self.ensure_connected(&server.id).await?;
let tools = conn.list_tools().await?;
self.metadata
.lock()
.await
.insert(server.id.clone(), CachedMeta { config_hash: hash, tools: tools.clone() });
self.persist_metadata().await;
Ok(tools)
}
/// Get (or open) the live connection for a server, refreshing its idle clock.
///
/// Connecting holds that server's own lock, so calls arriving together at a cold server wait
/// for one connection instead of each starting a server and the last one replacing the rest.
async fn ensure_connected(
&self,
server_id: &str,
) -> Result<Arc<dyn McpConnection>, RegistryError> {
let connecting =
self.connecting.lock().await.entry(server_id.to_string()).or_default().clone();
let _connecting = connecting.lock().await;
{
let mut live = self.live.lock().await;
// An abandoned connection is dead weight; replacing it is what "restarts on the next
// call" means.
if live.get(server_id).is_some_and(|entry| entry.conn.is_closed()) {
live.remove(server_id);
}
if let Some(entry) = live.get_mut(server_id) {
entry.last_used = Instant::now();
return Ok(entry.conn.clone());
}
}
let server = self
.servers
.iter()
.find(|s| s.id == server_id)
.ok_or_else(|| RegistryError::NoSuchServer(server_id.to_string()))?;
let conn = open_connection(server).await?;
let idle = match server.lifecycle {
McpLifecycle::KeepAlive => None,
_ => Some(
server
.idle_timeout_mins
.map(|m| Duration::from_secs(m * 60))
.unwrap_or(DEFAULT_IDLE),
),
};
self.live.lock().await.insert(
server_id.to_string(),
Live { conn: conn.clone(), last_used: Instant::now(), idle },
);
Ok(conn)
}
/// Drop live connections idle past their timeout (keep-alive servers have `idle == None`).
async fn sweep_idle(&self) {
let now = Instant::now();
self.live.lock().await.retain(|server_id, entry| {
let expired = entry.idle.is_some_and(|idle| now.duration_since(entry.last_used) > idle);
if expired {
tracing::debug!(server = %server_id, "mcp: idle-disconnecting");
}
!expired // dropping the entry drops the connection → transport reaps the process
});
}
/// Gracefully drop every live connection (used when leaving a project).
pub async fn shutdown_all(&self) {
self.live.lock().await.clear();
}
/// Build an [`OAuthClient`] for an OAuth-configured HTTP server (for the `mcp login` CLI flow).
pub fn oauth_client(&self, server_id: &str) -> Option<OAuthClient> {
let server = self.servers.iter().find(|s| s.id == server_id)?;
let url = match &server.transport {
McpTransport::HttpSse { url } => url.clone(),
McpTransport::Stdio { .. } => return None,
};
match &server.auth {
Some(McpAuth::OAuth(config)) => Some(
OAuthClient::new(server.id.clone(), url, config.clone())
.with_secret_commands(server.declared_by_user),
),
_ => None,
}
}
async fn persist_metadata(&self) {
let Some(path) = &self.cache_path else { return };
let snapshot = self.metadata.lock().await.clone();
if let Ok(json) = serde_json::to_string_pretty(&snapshot) {
let path = path.clone();
let written = tokio::task::spawn_blocking(move || {
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)?;
}
luxe_core::fs_atomic::replace(&path, json.as_bytes())
});
match written.await {
Ok(Ok(())) => {}
Ok(Err(error)) => tracing::warn!(%error, "mcp: failed to persist metadata cache"),
Err(error) => tracing::warn!(%error, "mcp: metadata cache write did not finish"),
}
}
}
}
/// Abandons its connection when dropped armed: the call it guards was given up on.
struct AbandonOnDrop(Option<Arc<dyn McpConnection>>);
impl Drop for AbandonOnDrop {
fn drop(&mut self) {
if let Some(conn) = self.0.take() {
tracing::warn!(server = %conn.server_id(), "mcp: abandoning a call; stopping its server");
conn.abandon();
}
}
}
/// Open a live connection for a server's transport: stdio through core, HTTP through
/// [`crate::http`].
///
/// Public because the registry is not the only caller that needs a connection: `luxe mcp tools`
/// lists a server without registering it, and has to reach either transport the same way.
pub async fn open_connection(server: &McpServerConfig) -> Result<Arc<dyn McpConnection>, McpError> {
match &server.transport {
McpTransport::Stdio { .. } => {
let client = McpStdioClient::connect(server).await?;
Ok(Arc::new(client))
}
McpTransport::HttpSse { .. } => {
let client = crate::http::HttpConnection::connect(server).await?;
Ok(Arc::new(client))
}
}
}
/// Hash a transport config so a changed command/url invalidates the cached metadata.
///
/// FNV-1a over a spelled-out key rather than `DefaultHasher`, whose output std does not promise to
/// keep between releases: the hash is written to disk, and a new toolchain would otherwise empty
/// every cache it reads.
fn transport_hash(transport: &McpTransport) -> u64 {
let key = match transport {
McpTransport::Stdio { command, args, cwd, .. } => {
let cwd = cwd.as_deref().map(std::path::Path::to_string_lossy).unwrap_or_default();
format!("stdio\0{command}\0{}\0{cwd}", args.join("\0"))
}
McpTransport::HttpSse { url } => format!("http\0{url}"),
};
key.bytes().fold(0xcbf2_9ce4_8422_2325, |hash, byte| {
(hash ^ u64::from(byte)).wrapping_mul(0x0000_0100_0000_01b3)
})
}
/// Whether a tool answers a search for `needle` (already lowercased): its name, what it says it
/// does, or the server it belongs to.
///
/// The server's id is what a reference to one names — `@[mcp:asana]` — so `search: "asana"` must
/// list that server's tools even when none of them happens to say the word.
fn matches(tool: &ToolRef, needle: &str) -> bool {
needle.is_empty()
|| tool.raw_name.to_lowercase().contains(needle)
|| tool.description.to_lowercase().contains(needle)
|| tool.server_id.to_lowercase().contains(needle)
}
#[cfg(test)]
mod tests {
use super::*;
/// The hash a cache on disk was written under is the one a later build computes.
///
/// The break this catches: `DefaultHasher`, which std may change between releases, so an
/// upgrade emptied every server's cached tool list.
#[test]
fn a_transport_hashes_the_same_in_every_build() {
let stdio = McpTransport::Stdio {
command: "npx".into(),
args: vec!["-y".into(), "asana-mcp".into()],
cwd: None,
env: Default::default(),
};
assert_eq!(transport_hash(&stdio), 0xcb0d_a7d1_8332_65b3);
let McpTransport::Stdio { command, args, env, .. } = stdio.clone() else { unreachable!() };
let placed = McpTransport::Stdio { command, args, cwd: Some("/srv/mcp".into()), env };
assert_eq!(transport_hash(&placed), 0xfe38_673c_a328_0a9e);
let http = McpTransport::HttpSse { url: "https://mcp.example/sse".into() };
assert_ne!(transport_hash(&http), transport_hash(&stdio));
}
/// A search finds a tool by its name, by what it does, and by its server.
#[test]
fn a_search_matches_the_name_the_description_or_the_server() {
let tool = ToolRef {
server_id: "Asana".into(),
raw_name: "get_tasks".into(),
presented: "Asana/get_tasks".into(),
description: "List the tasks in a project.".into(),
input_schema: serde_json::Value::Null,
};
for needle in ["", "get_tasks", "project", "asana", "sana"] {
assert!(matches(&tool, needle), "{needle:?}");
}
for needle in ["jira", "create"] {
assert!(!matches(&tool, needle), "{needle:?}");
}
}
fn manager_with(servers: Vec<McpServerConfig>) -> Arc<ServerRegistry> {
Arc::new(ServerRegistry::new(servers, None))
}
#[tokio::test]
async fn empty_manager_has_no_servers() {
let manager = manager_with(vec![]);
assert!(!manager.has_servers());
assert!(manager.search("anything").await.is_empty());
}
#[tokio::test]
async fn disabled_servers_are_filtered_out() {
let manager = manager_with(vec![McpServerConfig {
id: "off".into(),
name: "Off".into(),
enabled: false,
..Default::default()
}]);
assert!(!manager.has_servers());
}
/// A stdio server that spawns a grandchild on `slow` and never answers, and answers `fast`.
#[cfg(unix)]
const SLOW_SERVER: &str = r#"
import json, subprocess, sys
pidfile = sys.argv[1]
for line in sys.stdin:
msg = json.loads(line)
method, id = msg.get("method"), msg.get("id")
if method == "initialize":
result = {"protocolVersion": "2025-06-18", "capabilities": {"tools": {}}, "serverInfo": {"name": "slow"}}
elif method == "tools/list":
result = {"tools": [{"name": n, "description": n, "inputSchema": {"type": "object"}} for n in ("slow", "fast")]}
elif method == "tools/call" and msg["params"]["name"] == "slow":
child = subprocess.Popen(["sleep", "60"])
open(pidfile, "w").write(str(child.pid))
continue
elif method == "tools/call":
result = {"content": [{"type": "text", "text": "fast"}]}
else:
continue
sys.stdout.write(json.dumps({"jsonrpc": "2.0", "id": id, "result": result}) + "\n")
sys.stdout.flush()
"#;
/// A call past its server's deadline stops the server *and what it started*, and the next call
/// gets a fresh server.
///
/// Against a real model, a delegating server's subagent went on writing files after the model
/// was told the call "was stopped" — and after the session had exited, because killing the
/// server left its child behind.
#[cfg(unix)]
#[tokio::test]
async fn an_abandoned_call_stops_the_whole_server_tree() {
if std::process::Command::new("python3").arg("--version").output().is_err() {
eprintln!("skipping: python3 not available");
return;
}
let dir = tempfile::tempdir().unwrap();
let script = dir.path().join("slow.py");
let pidfile = dir.path().join("grandchild.pid");
std::fs::write(&script, SLOW_SERVER).unwrap();
let manager = manager_with(vec![McpServerConfig {
id: "srv".into(),
name: "srv".into(),
enabled: true,
timeout_secs: Some(1),
transport: McpTransport::Stdio {
command: "python3".into(),
args: vec![script.display().to_string(), pidfile.display().to_string()],
cwd: None,
env: Default::default(),
},
..Default::default()
}]);
let error = manager.call("srv/slow", serde_json::json!({})).await.unwrap_err();
assert!(matches!(&error, RegistryError::TimedOut { secs: 1, .. }), "{error:?}");
assert!(error.to_string().contains("did not answer within 1s"), "{error}");
let grandchild: u32 = std::fs::read_to_string(&pidfile).unwrap().trim().parse().unwrap();
let deadline = Instant::now() + Duration::from_secs(5);
while luxe_core::program::process_is_alive(grandchild) && Instant::now() < deadline {
tokio::time::sleep(Duration::from_millis(50)).await;
}
assert!(!luxe_core::program::process_is_alive(grandchild), "the grandchild outlived it");
let result = manager.call("srv/fast", serde_json::json!({})).await.unwrap();
assert_eq!(result.output.as_deref(), Some("fast"), "a fresh server answered");
}
#[tokio::test]
async fn transport_hash_changes_with_command() {
let a = transport_hash(&McpTransport::Stdio {
command: "a".into(),
args: vec![],
cwd: None,
env: Default::default(),
});
let b = transport_hash(&McpTransport::Stdio {
command: "b".into(),
args: vec![],
cwd: None,
env: Default::default(),
});
assert_ne!(a, b);
}
}

View File

@@ -0,0 +1,182 @@
//! Secrets — what a client secret or bearer token written in an MCP config resolves to.
//!
//! Three forms, the ones a provider key in `auth.json` accepts: the value itself, `${VAR}` (or
//! `$env:VAR`) for an environment variable, and `!command` for a program that prints it — a
//! password manager, usually, so the secret is on disk in plain text nowhere and in no process's
//! environment. Resolved when it is needed, at sign-in and on a refresh, never when the config is
//! read: the config is read on every workspace snapshot, and a password manager asked for a secret
//! that often would ask the reader for a passphrase that often.
use luxe_core::secret_command::SECRET_COMMAND_TIMEOUT;
/// Why a secret written in a config did not resolve to anything.
///
/// Each carries the sentence that says what to do about it, with the secret's own name in it.
#[derive(Debug, thiserror::Error)]
pub enum SecretError {
/// Nothing there: it is empty, or a `${VAR}` that is not set where Luxe runs
#[error("{0}")]
Unset(String),
/// A `!command` in a config that may not run one
#[error("{0}")]
CommandRefused(String),
/// The command ran, and did not print a secret
#[error("{0}")]
Command(String),
}
/// Resolves a secret as written in the config.
///
/// Args: `(written, commands_allowed, what)` — whether this server was declared in the reader's own
/// config, and what the secret is, for the error (`"the client secret for 'asana'"`).
///
/// A `!command` from a project's config is refused rather than run. A secret has no business in a
/// file a repository ships, and running one would make `luxe mcp login` — which reads as "open a
/// browser" — run whatever a cloned repository named. The error names the file it belongs in.
/// What the command printed never appears in an error, since a command that fails halfway may
/// still have printed the secret.
pub(crate) async fn resolve_secret(
written: &str,
commands_allowed: bool,
what: &str,
) -> Result<String, SecretError> {
resolve(written, commands_allowed, what).await.map(|secret| remembered(&secret))
}
/// `secret`, once remembered for redaction: a resolved secret or a token about to ride a request
/// has no shape a pattern could know.
pub(crate) fn remembered(secret: &str) -> String {
luxe_core::redact::process_secrets().add(secret);
secret.to_string()
}
async fn resolve(written: &str, commands_allowed: bool, what: &str) -> Result<String, SecretError> {
let Some(command) = written.trim().strip_prefix('!') else {
let expanded = luxe_core::mcp_client::expand_env(written);
if expanded.trim().is_empty() {
return Err(SecretError::Unset(match named_variable(written) {
Some(name) => format!(
"{what} is `${{{name}}}`, and {name} is not set where Luxe is running — export \
it, or add the export to your shell profile so every terminal has it"
),
None => format!("{what} is empty"),
}));
}
return Ok(expanded);
};
if !commands_allowed {
return Err(SecretError::CommandRefused(format!(
"{what} is a command, and only your own config runs one — a project's config may \
not. Move the server's auth to {}",
luxe_core::user_dirs::config_path_display("mcp.json")
)));
}
luxe_core::secret_command::run(command.trim(), what, SECRET_COMMAND_TIMEOUT)
.await
.map_err(SecretError::Command)
}
/// The variable `written` names, as `${VAR}` or `$env:VAR`, when it names one.
///
/// Asked only once the secret has expanded to nothing, so whatever it names is unset or blank, and
/// the first is the one to name: a secret that expands to nothing is nearly always a variable
/// exported in one terminal and not the one Luxe runs in, and saying which is the whole of the fix.
/// Whichever marker comes first, the order [`luxe_core::mcp_client::expand_env`] reads them in.
fn named_variable(written: &str) -> Option<&str> {
let braced = written.find("${");
let env = written.find("$env:");
let name = match (braced, env) {
(Some(at), env) if env.is_none_or(|env| at < env) => written[at + 2..].split_once('}')?.0,
(_, Some(at)) => {
let body = &written[at + 5..];
body.split(|c: char| !c.is_ascii_alphanumeric() && c != '_').next()?
}
_ => return None,
};
(!name.is_empty()).then_some(name)
}
#[cfg(test)]
mod tests {
use super::*;
const WHAT: &str = "the client secret for 'asana'";
/// A resolved secret is remembered, so a tool that prints it is scrubbed whatever its shape.
#[tokio::test]
async fn a_resolved_secret_is_remembered_for_redaction() {
resolve_secret("mcp-plain-secret-5521", false, WHAT).await.unwrap();
let seen = luxe_core::redact::process_secrets().redact("seen mcp-plain-secret-5521");
assert_eq!(seen, "seen [REDACTED]");
}
#[tokio::test]
async fn a_value_or_a_variable_resolves_as_before() {
std::env::set_var("LUXE_MCP_SECRET_TEST", "from-env");
assert_eq!(resolve_secret("literal", false, WHAT).await.unwrap(), "literal");
assert_eq!(
resolve_secret("${LUXE_MCP_SECRET_TEST}", false, WHAT).await.unwrap(),
"from-env"
);
let unset = resolve_secret("${LUXE_MCP_SECRET_UNSET}", true, WHAT).await.unwrap_err();
assert!(matches!(unset, SecretError::Unset(_)), "{unset:?}");
assert_eq!(
unset.to_string(),
format!(
"{WHAT} is `${{LUXE_MCP_SECRET_UNSET}}`, and LUXE_MCP_SECRET_UNSET is not set where \
Luxe is running — export it, or add the export to your shell profile so every \
terminal has it"
)
);
let second =
resolve_secret("$env:LUXE_MCP_SECRET_TEST$env:LUXE_MCP_SECRET_GONE", true, WHAT).await;
assert_eq!(second.unwrap(), "from-env", "one variable set is a secret");
let blank = resolve_secret(" ", true, WHAT).await.unwrap_err().to_string();
assert_eq!(blank, format!("{WHAT} is empty"), "no variable to name");
let nameless = resolve_secret("${}", true, WHAT).await.unwrap_err().to_string();
assert_eq!(nameless, format!("{WHAT} is empty"), "nor here");
let windows =
resolve_secret("$env:LUXE_MCP_SECRET_GONE", true, WHAT).await.unwrap_err().to_string();
assert!(windows.contains("and LUXE_MCP_SECRET_GONE is not set"), "{windows}");
// the first marker is the one named, as the expander reads them left to right
let mixed = "$env:LUXE_MCP_SECRET_FIRST${LUXE_MCP_SECRET_SECOND}";
let first = resolve_secret(mixed, true, WHAT).await.unwrap_err().to_string();
assert!(first.contains("and LUXE_MCP_SECRET_FIRST is not set"), "{first}");
std::env::remove_var("LUXE_MCP_SECRET_TEST");
}
/// The first line of what the command prints is the secret — `pass show` puts the rest of
/// the entry after it — and a project's config may not run one at all.
#[cfg(unix)]
#[tokio::test]
async fn a_command_prints_the_secret_and_only_your_config_runs_one() {
let secret = resolve_secret("!printf 's3cret\\nurl: x\\n'", true, WHAT).await;
assert_eq!(secret.unwrap(), "s3cret");
let marker = tempfile::tempdir().unwrap();
let path = marker.path().join("ran");
let command = format!("!touch {} && echo s3cret", path.display());
let refused = resolve_secret(&command, false, WHAT).await.unwrap_err();
assert!(matches!(refused, SecretError::CommandRefused(_)), "{refused:?}");
let refused = refused.to_string();
assert!(refused.starts_with(&format!("{WHAT} is a command")), "{refused}");
assert!(refused.contains("mcp.json"), "and says where it belongs: {refused}");
assert!(!path.exists(), "a refused command never runs");
}
/// A failure says why in the command's own words and never repeats what it printed, which
/// may be the secret.
#[cfg(unix)]
#[tokio::test]
async fn a_failing_command_says_why_without_what_it_printed() {
let failed = resolve_secret("!echo s3cret; echo 'no such entry' >&2; exit 3", true, WHAT)
.await
.unwrap_err()
.to_string();
assert!(failed.contains("failed") && failed.ends_with(": no such entry"), "{failed}");
assert!(!failed.contains("s3cret"), "{failed}");
let silent = resolve_secret("!true", true, WHAT).await.unwrap_err().to_string();
assert!(silent.ends_with("printed nothing"), "{silent}");
}
}

View File

@@ -0,0 +1,241 @@
//! OAuth token store — per-server tokens persisted with `0600` perms.
//!
//! Access and refresh tokens for hosted MCP servers live in the **state** directory —
//! `$XDG_STATE_HOME/luxe/mcp-auth.json`, `~/.local/state/…`, or `%LOCALAPPDATA%` on Windows —
//! readable only by the owner. They are machine-written and refreshed every hour, which is state by
//! the line `runtime_state` draws, and the config directory is the wrong home for it twice over:
//! it is what people keep in a dotfiles repository, and on Windows it is `%APPDATA%`, which roams
//! between machines. A store found in the config-directory location is moved on first read.
//!
//! Tokens are zeroized on drop, redacted from `Debug`, and never logged.
use std::collections::HashMap;
use std::path::PathBuf;
use luxe_core::json_file::{FileError, FileMode, JsonFile};
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use zeroize::Zeroize;
/// Why the token store could not be written.
#[derive(Debug, thiserror::Error)]
pub enum TokenStoreError {
/// A token that would not serialize
#[error(transparent)]
Encode(#[from] serde_json::Error),
/// The file could not be locked, read or replaced
#[error(transparent)]
File(#[from] FileError),
}
/// A stored token set for one server. `Zeroize` clears the secret material on drop.
#[derive(Clone, Serialize, Deserialize, Default)]
pub struct StoredToken {
pub access_token: String,
#[serde(default)]
pub refresh_token: Option<String>,
/// Unix seconds when the access token expires (`None` = no known expiry).
#[serde(default)]
pub expires_at_secs: Option<u64>,
/// The (possibly dynamically-registered) client id this token belongs to.
#[serde(default)]
pub client_id: Option<String>,
/// A confidential client's secret, when one was issued at registration. A configured client's
/// secret is never copied here: it stays in the config, or the variable the config names.
#[serde(default)]
pub client_secret: Option<String>,
/// The token endpoint that issued it, so a refresh goes back to the same place
#[serde(default)]
pub token_endpoint: Option<String>,
/// The resource indicator it was issued for (RFC 8707)
#[serde(default)]
pub resource: Option<String>,
}
impl std::fmt::Debug for StoredToken {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let shown = |present: bool| if present { "[redacted]" } else { "none" };
formatter
.debug_struct("StoredToken")
.field("access_token", &shown(!self.access_token.is_empty()))
.field("refresh_token", &shown(self.refresh_token.is_some()))
.field("expires_at_secs", &self.expires_at_secs)
.field("client_id", &self.client_id)
.field("client_secret", &shown(self.client_secret.is_some()))
.field("token_endpoint", &self.token_endpoint)
.field("resource", &self.resource)
.finish()
}
}
impl StoredToken {
/// Whether the access token is expired (or within a 60s safety margin).
pub fn is_expired(&self) -> bool {
match self.expires_at_secs {
Some(exp) => now_secs() + 60 >= exp,
None => false,
}
}
}
impl Drop for StoredToken {
fn drop(&mut self) {
self.access_token.zeroize();
if let Some(t) = self.refresh_token.as_mut() {
t.zeroize();
}
if let Some(s) = self.client_secret.as_mut() {
s.zeroize();
}
}
}
/// File-backed map of `server_id -> StoredToken`.
pub struct TokenStore {
path: PathBuf,
/// Where a store written before the move lives, read once and removed
legacy: Option<PathBuf>,
}
impl TokenStore {
/// Store at an explicit path.
pub fn new(path: PathBuf) -> Self {
Self { path, legacy: None }
}
/// Store at `path`, moving one found at `legacy` into it on first read.
pub fn migrating(path: PathBuf, legacy: PathBuf) -> Self {
Self { path, legacy: Some(legacy) }
}
/// The default store in the state directory, taking over one left in the config directory.
pub fn default_path() -> Self {
Self::migrating(
luxe_core::user_dirs::luxe_state_dir().join("mcp-auth.json"),
luxe_core::user_dirs::luxe_config_dir().join("mcp-auth.json"),
)
}
/// Where the store is written.
pub fn path(&self) -> &std::path::Path {
&self.path
}
/// Load the token for one server.
pub fn get(&self, server_id: &str) -> Option<StoredToken> {
self.load().remove(server_id)
}
/// The servers a token is stored for, read without migrating and without holding one secret.
///
/// For a status line that is redrawn on every snapshot: it must not write — the migration in
/// [`Self::get`] is for a sign-in or a call — and has no business decoding a token to count it,
/// so the values are skipped unparsed. Stored is not valid: an expired token with no refresh
/// still counts, which is why the word the tab uses is "signed in" and not "working".
pub fn signed_in_ids(&self) -> std::collections::HashSet<String> {
let ids = |path: &std::path::Path| {
Some(file(path).read()?.into_iter().map(|(id, _)| id).collect())
};
ids(&self.path).or_else(|| self.legacy.as_deref().and_then(ids)).unwrap_or_default()
}
/// Insert/replace the token for one server and persist (`0600`).
pub fn put(&self, server_id: &str, token: StoredToken) -> Result<(), TokenStoreError> {
let value = serde_json::to_value(&token)?;
self.modify(|all| {
all.insert(server_id.to_string(), value.clone());
})
}
/// Remove one server's token (e.g. on logout).
pub fn remove(&self, server_id: &str) -> Result<(), TokenStoreError> {
self.modify(|all| {
all.remove(server_id);
})
}
/// Change the store under its lock, keeping every entry this version cannot read as written.
///
/// A file that does not parse at all is moved aside with a warning, never written over:
/// emptying it would sign the reader out of every server for one bad edit.
fn modify(&self, edit: impl FnOnce(&mut Map<String, Value>)) -> Result<(), TokenStoreError> {
let ((), aside) = file(&self.path).modify_setting_aside(|all| {
edit(all);
Ok(())
})?;
if let Some(aside) = aside {
tracing::warn!(kept = %aside.display(), "mcp: the token store did not parse; moved it aside");
}
Ok(())
}
/// Every server's token that parses. When only the config-directory location has a store, it is
/// written to the state directory and the old file removed — only after the write, so a failure
/// loses nothing. With both present the new one wins and the old is left for the reader to
/// inspect.
fn load(&self) -> HashMap<String, StoredToken> {
if let Some(all) = read(&self.path) {
return tokens(all);
}
let Some(legacy) = self.legacy.as_ref() else {
return HashMap::new();
};
let Some(all) = read(legacy) else {
return HashMap::new();
};
match self.modify(|stored| stored.extend(all.clone())) {
Ok(()) => {
if let Err(error) = std::fs::remove_file(legacy) {
tracing::warn!(%error, path = %legacy.display(), "mcp: could not remove the old token store");
} else {
tracing::info!(to = %self.path.display(), "mcp: moved the token store to the state directory");
}
}
Err(error) => {
tracing::warn!(%error, "mcp: could not move the token store; reading it in place")
}
}
tokens(all)
}
}
/// The store at `path`: one JSON object, owner-only, edited under a cross-process lock.
fn file(path: &std::path::Path) -> JsonFile {
JsonFile::new(path.to_path_buf(), FileMode::OwnerOnly)
}
/// The store's object, or `None` when it is missing or does not parse. Quiet, since it runs on
/// every request and every status redraw; the write that moves a broken file aside is what warns.
fn read(path: &std::path::Path) -> Option<Map<String, Value>> {
let text = std::fs::read_to_string(path).ok()?;
match serde_json::from_str(&text) {
Ok(all) => Some(all),
Err(error) => {
tracing::debug!(path = %path.display(), %error, "mcp: the token store does not parse");
None
}
}
}
/// The entries that parse as tokens; one that does not is skipped, not allowed to hide the rest.
fn tokens(all: Map<String, Value>) -> HashMap<String, StoredToken> {
all.into_iter()
.filter_map(|(id, value)| match serde_json::from_value(value) {
Ok(token) => Some((id, token)),
Err(error) => {
tracing::debug!(server = %id, %error, "mcp: a stored token does not parse; skipping it");
None
}
})
.collect()
}
fn now_secs() -> u64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0)
}
#[cfg(test)]
mod tests;

View File

@@ -0,0 +1,229 @@
use super::*;
/// The status read names the servers with a token, falls back to the old store, and leaves
/// both files exactly as it found them.
#[test]
fn signed_in_ids_reads_names_and_writes_nothing() {
let dir = tempfile::tempdir().unwrap();
let (path, legacy) = (dir.path().join("state.json"), dir.path().join("config.json"));
let store = TokenStore::migrating(path.clone(), legacy.clone());
assert!(store.signed_in_ids().is_empty(), "no store: nobody is signed in");
std::fs::write(&legacy, r#"{"asana": {"access_token": "a"}, "linear": {"access_token": "b"}}"#)
.unwrap();
let ids = store.signed_in_ids();
assert_eq!(ids, ["asana", "linear"].map(String::from).into_iter().collect());
assert!(!path.exists() && legacy.exists(), "reading a status migrated the store");
std::fs::write(&path, r#"{"github": {"access_token": "c"}}"#).unwrap();
assert_eq!(store.signed_in_ids(), ["github"].map(String::from).into_iter().collect());
std::fs::write(&path, "not json").unwrap();
assert_eq!(store.signed_in_ids().len(), 2, "an unreadable store falls back, like `get`");
}
#[test]
fn round_trips_and_sets_owner_only_perms() {
let dir = tempfile::tempdir().unwrap();
let store = TokenStore::new(dir.path().join("mcp-auth.json"));
assert!(store.get("srv").is_none());
store
.put(
"srv",
StoredToken {
access_token: "tok".into(),
refresh_token: Some("refresh".into()),
expires_at_secs: None,
client_id: Some("cid".into()),
client_secret: None,
token_endpoint: None,
resource: None,
},
)
.unwrap();
let got = store.get("srv").expect("token present");
assert_eq!(got.access_token, "tok");
assert_eq!(got.client_id.as_deref(), Some("cid"));
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let mode =
std::fs::metadata(dir.path().join("mcp-auth.json")).unwrap().permissions().mode();
assert_eq!(mode & 0o777, 0o600, "auth file must be owner-only");
}
store.remove("srv").unwrap();
assert!(store.get("srv").is_none());
}
#[test]
fn expiry_uses_safety_margin() {
let mut t = StoredToken {
access_token: "x".into(),
refresh_token: None,
expires_at_secs: None,
client_id: None,
client_secret: None,
token_endpoint: None,
resource: None,
};
assert!(!t.is_expired(), "no expiry = not expired");
// The clock is read here independently: reading it through `now_secs` would move the test
// with the code it is testing
let now = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs();
t.expires_at_secs = Some(now + 10); // within 60s margin
assert!(t.is_expired());
t.expires_at_secs = Some(now + 3600);
assert!(!t.is_expired());
t.expires_at_secs = Some(now.saturating_sub(10));
assert!(t.is_expired(), "in the past is expired");
}
fn token(access: &str) -> StoredToken {
StoredToken {
access_token: access.into(),
refresh_token: Some("refresh-secret".into()),
expires_at_secs: None,
client_id: Some("cid".into()),
client_secret: Some("issued-secret".into()),
token_endpoint: Some("https://app.asana.com/-/oauth_token".into()),
resource: Some("https://mcp.asana.com/v2/mcp".into()),
}
}
/// A store left in the config directory is read once, lands in the state directory, and the
/// old file is gone — after the write, so nothing is lost if it fails.
#[test]
fn a_store_in_the_old_place_moves_on_first_read() {
let dir = tempfile::tempdir().unwrap();
let old = dir.path().join("config").join("luxe").join("mcp-auth.json");
let new = dir.path().join("state").join("luxe").join("mcp-auth.json");
TokenStore::new(old.clone()).put("asana", token("at-old")).unwrap();
let store = TokenStore::migrating(new.clone(), old.clone());
assert_eq!(store.get("asana").map(|t| t.access_token.clone()).as_deref(), Some("at-old"));
assert!(new.exists(), "written to the state directory");
assert!(!old.exists(), "and the config directory no longer holds tokens");
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
assert_eq!(std::fs::metadata(&new).unwrap().permissions().mode() & 0o777, 0o600);
}
assert_eq!(store.get("asana").map(|t| t.access_token.clone()).as_deref(), Some("at-old"));
}
/// With both present the new store wins, and the old one is left alone rather than merged or
/// deleted: it is somebody's file, and it is no longer read.
#[test]
fn the_new_store_wins_over_the_old() {
let dir = tempfile::tempdir().unwrap();
let old = dir.path().join("old.json");
let new = dir.path().join("new.json");
TokenStore::new(old.clone()).put("asana", token("at-old")).unwrap();
TokenStore::new(new.clone()).put("asana", token("at-new")).unwrap();
let store = TokenStore::migrating(new, old.clone());
assert_eq!(store.get("asana").map(|t| t.access_token.clone()).as_deref(), Some("at-new"));
assert!(old.exists());
}
/// If the new store cannot be written the old one is read in place and kept.
#[cfg(unix)]
#[test]
fn a_failed_move_keeps_the_old_store() {
use std::os::unix::fs::PermissionsExt;
let dir = tempfile::tempdir().unwrap();
let old = dir.path().join("old.json");
TokenStore::new(old.clone()).put("asana", token("at-old")).unwrap();
let locked = dir.path().join("locked");
std::fs::create_dir(&locked).unwrap();
std::fs::set_permissions(&locked, std::fs::Permissions::from_mode(0o500)).unwrap();
let store = TokenStore::migrating(locked.join("new.json"), old.clone());
let read = store.get("asana").map(|t| t.access_token.clone());
std::fs::set_permissions(&locked, std::fs::Permissions::from_mode(0o700)).unwrap();
// Running as root writes anyway; the promise is only that nothing is lost
assert_eq!(read.as_deref(), Some("at-old"));
assert!(old.exists() || locked.join("new.json").exists(), "the tokens are somewhere");
}
#[test]
fn debug_never_shows_a_token_or_a_secret() {
let shown = format!("{:?}", token("at-live"));
for secret in ["at-live", "refresh-secret", "issued-secret"] {
assert!(!shown.contains(secret), "{secret} leaked: {shown}");
}
assert!(shown.contains("[redacted]") && shown.contains("cid"), "{shown}");
let empty = StoredToken::default();
assert!(format!("{empty:?}").contains("access_token: \"none\""));
}
/// The default store is in the state directory, and takes over the one in the config directory.
#[test]
fn the_default_store_is_state_not_configuration() {
let store = TokenStore::default_path();
let path = luxe_core::paths::display(store.path());
assert!(path.ends_with("luxe/mcp-auth.json"), "{path}");
assert_eq!(store.path(), luxe_core::user_dirs::luxe_state_dir().join("mcp-auth.json"));
assert_eq!(
store.legacy.as_deref(),
Some(luxe_core::user_dirs::luxe_config_dir().join("mcp-auth.json").as_path())
);
}
/// Two servers signing in at once keep both tokens: each write reads, changes and writes under the
/// file's lock, so neither overwrites the other with what it read before.
#[test]
fn concurrent_sign_ins_keep_every_token() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("mcp-auth.json");
let writers: Vec<_> = (0..16)
.map(|n| {
let path = path.clone();
std::thread::spawn(move || {
TokenStore::new(path).put(&format!("server-{n}"), token("at")).unwrap()
})
})
.collect();
for writer in writers {
writer.join().unwrap();
}
let store = TokenStore::new(path);
for n in 0..16 {
assert!(store.get(&format!("server-{n}")).is_some(), "server-{n} was lost");
}
}
/// A store that does not parse is not emptied by the next write: it is moved to `.bad` for the
/// reader, and the new store holds only the new token, since nothing could be read from the old.
#[test]
fn an_unreadable_store_is_not_overwritten() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("mcp-auth.json");
std::fs::write(&path, "{ \"asana\": { not json").unwrap();
TokenStore::new(path.clone()).put("linear", token("at-linear")).unwrap();
let kept = std::fs::read_to_string(dir.path().join("mcp-auth.json.bad")).unwrap();
assert_eq!(kept, "{ \"asana\": { not json");
let store = TokenStore::new(path);
assert_eq!(store.get("linear").map(|t| t.access_token.clone()).as_deref(), Some("at-linear"));
assert_eq!(store.signed_in_ids(), ["linear".to_string()].into_iter().collect());
}
/// One entry an older or newer Luxe wrote differently does not hide the others, and survives a
/// write for another server.
#[test]
fn an_entry_that_does_not_parse_hides_nothing_else() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("mcp-auth.json");
let store = TokenStore::new(path.clone());
store.put("asana", token("at-asana")).unwrap();
let mut raw: serde_json::Value =
serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
raw["odd"] = serde_json::json!({"no_access_token": true});
std::fs::write(&path, raw.to_string()).unwrap();
assert_eq!(store.get("asana").map(|t| t.access_token.clone()).as_deref(), Some("at-asana"));
store.put("linear", token("at-linear")).unwrap();
let raw: serde_json::Value =
serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
assert_eq!(raw["odd"], serde_json::json!({"no_access_token": true}), "kept as written");
}

249
crates/luxe-mcp/src/tool.rs Normal file
View File

@@ -0,0 +1,249 @@
//! The `mcp` proxy tool — one tool, on-demand discovery.
//!
//! Instead of registering every MCP tool (and its verbose schema) up front, the agent gets a single
//! ~200-token tool and discovers what it needs: `search` → `describe` → `call`. Backed by the
//! [`ServerRegistry`], which connects servers lazily and serves discovery from a cached metadata
//! snapshot. Results come back as data, never interpreted as instructions.
use std::sync::Arc;
use async_trait::async_trait;
use serde_json::Value;
use luxe_core::provider::ToolSchema;
use luxe_core::tool::{Tool, ToolContext, ToolResultData};
use crate::registry::ServerRegistry;
/// How many search hits to show before advising a narrower query.
const MAX_HITS: usize = 40;
/// The single gateway tool to all configured MCP servers.
pub struct McpProxyTool {
manager: Arc<ServerRegistry>,
}
impl McpProxyTool {
/// Wrap a [`ServerRegistry`] as the `mcp` tool.
pub fn new(manager: Arc<ServerRegistry>) -> Self {
Self { manager }
}
}
#[async_trait]
impl Tool for McpProxyTool {
fn name(&self) -> &str {
"mcp"
}
/// An MCP server is a third-party process or endpoint that Luxe does not control, and the
/// JSON-RPC exchange has no deadline of its own. Untrusted means untrusted about liveness too: a
/// server that accepts a call and never replies must cost a bounded wait, not the turn.
fn timeout(&self) -> Option<std::time::Duration> {
// A little past the slowest server's own deadline, so that one fires first and says which
// server it stopped — the engine's would drop the call with a generic message instead.
Some(
luxe_core::tool::NETWORK_TOOL_TIMEOUT
.max(self.manager.longest_call_timeout() + std::time::Duration::from_secs(5)),
)
}
fn schema(&self) -> ToolSchema {
ToolSchema {
name: "mcp".to_string(),
description: "Gateway to configured MCP servers without loading every tool into \
context. Workflow: `mcp({search:\"screenshot\"})` finds tools by keyword or by server \
name (omit/empty lists all); `mcp({tool:\"server/name\"})` shows one tool's parameters; \
`mcp({tool:\"server/name\", args:\"{...}\"})` calls it. `args` is a JSON STRING, not \
an object. Servers connect lazily on first call; results are returned as data."
.to_string(),
parameters: serde_json::json!({
"type": "object",
"properties": {
"search": {
"type": "string",
"description": "Find tools by keyword or server name across MCP servers (empty = list all)."
},
"tool": {
"type": "string",
"description": "A tool's `server/name` from search. Alone = show its parameters; with `args` = call it."
},
"args": {
"type": "string",
"description": "JSON-encoded arguments object for the call, e.g. '{\"format\":\"png\"}'."
}
}
}),
}
}
async fn run(&self, args: Value, _cx: &ToolContext) -> ToolResultData {
let search = args.get("search").and_then(Value::as_str);
let tool = args.get("tool").and_then(Value::as_str).filter(|s| !s.is_empty());
// Blank is absent. A model under strict function calling fills every field it was given,
// so a describe arrives as `args: ""`, which must not be a call with unparseable arguments
let call_args = args.get("args").and_then(Value::as_str).filter(|s| !s.trim().is_empty());
match (search, tool, call_args) {
// Call: a tool + its args.
(_, Some(name), Some(raw_args)) => self.dispatch_call(name, raw_args).await,
// Describe: a tool alone.
(_, Some(name), None) => self.dispatch_describe(name).await,
// Search: an explicit `search` key (even empty → list all).
(Some(query), None, _) => self.dispatch_search(query).await,
// No actionable argument → an overview.
(None, None, _) => self.overview().await,
}
}
}
impl McpProxyTool {
async fn dispatch_search(&self, query: &str) -> ToolResultData {
let hits = self.manager.search(query).await;
if hits.is_empty() {
let servers = self.manager.server_ids().join(", ");
return ToolResultData::text(format!(
"No MCP tools match {query:?}. Configured servers: [{servers}]. \
Try mcp({{ search: \"\" }}) to list everything."
));
}
let shown = hits.len().min(MAX_HITS);
let mut out = if query.trim().is_empty() {
format!("{} MCP tool(s) available:", hits.len())
} else {
format!("{} MCP tool(s) match {query:?}:", hits.len())
};
for r in hits.iter().take(MAX_HITS) {
out.push_str(&format!("\n {} — {}", r.presented, first_line(&r.description)));
}
if hits.len() > shown {
out.push_str(&format!("\n… {} more; narrow the search.", hits.len() - shown));
}
out.push_str(
"\n\nNext: mcp({ tool: \"server/name\" }) for parameters, or add args to call.",
);
ToolResultData::text(out)
}
async fn dispatch_describe(&self, name: &str) -> ToolResultData {
match self.manager.describe(name).await {
Ok(r) => {
// Compact: the indentation of a pretty schema is a third of it, and a schema is
// read by the model rather than by a person
let schema = r.input_schema.to_string();
ToolResultData::text(format!(
"{}\n{}\n\nParameters:\n{}\n\nCall with mcp({{ tool: \"{}\", args: \"{{...}}\" }}).",
r.presented, r.description, schema, r.presented
))
}
Err(error) => ToolResultData::error(error.to_string()),
}
}
async fn dispatch_call(&self, name: &str, raw_args: &str) -> ToolResultData {
let arguments: Value = match serde_json::from_str(raw_args) {
Ok(value) => value,
Err(error) => {
return ToolResultData::error(format!(
"`args` must be a JSON object string: {error}. Got: {raw_args}"
))
}
};
match self.manager.call(name, arguments).await {
Ok(result) => {
let body = result.output.or(result.error).unwrap_or_default();
if result.success {
ToolResultData::text(body)
} else {
ToolResultData::error(body)
}
}
Err(error) => ToolResultData::error(error.to_string()),
}
}
async fn overview(&self) -> ToolResultData {
let servers = self.manager.server_ids();
if servers.is_empty() {
return ToolResultData::text("No MCP servers configured.");
}
ToolResultData::text(format!(
"MCP servers configured ({}): {}.\nDiscover tools with mcp({{ search: \"...\" }}).",
servers.len(),
servers.join(", ")
))
}
}
/// First non-empty line of a description, trimmed for the search listing.
fn first_line(description: &str) -> String {
let line = description.lines().find(|l| !l.trim().is_empty()).unwrap_or("").trim();
if line.chars().count() > 100 {
format!("{}…", line.chars().take(99).collect::<String>())
} else {
line.to_string()
}
}
#[cfg(test)]
mod tests {
use super::*;
use luxe_core::message::ContentBlock;
use tokio::sync::{mpsc, watch};
fn proxy() -> McpProxyTool {
let manager = Arc::new(ServerRegistry::new(vec![], None));
McpProxyTool::new(manager)
}
fn cx() -> ToolContext {
let (event_tx, _rx) = mpsc::channel(8);
let (_tx, cancel_rx) = watch::channel(false);
ToolContext {
cwd: std::path::PathBuf::from("."),
session_id: "test".to_string(),
cancelled: Arc::new(cancel_rx),
event_tx,
hook_ctx: None,
question_broker: None,
}
}
#[tokio::test]
async fn overview_when_no_servers() {
let out = proxy().run(serde_json::json!({}), &cx()).await;
assert!(!out.is_error);
match &out.content[0] {
ContentBlock::Text(t) => assert!(t.contains("No MCP servers configured")),
_ => panic!("expected text"),
}
}
#[tokio::test]
async fn call_rejects_non_json_args() {
let out =
proxy().run(serde_json::json!({ "tool": "x/y", "args": "not json" }), &cx()).await;
assert!(out.is_error);
}
/// A describe from a model that fills every field is still a describe.
///
/// Against a real model the first `mcp({tool, args: ""})` failed with "`args` must be a JSON
/// object string" and the model had to guess its way to a call.
#[tokio::test]
async fn blank_args_mean_describe_not_call() {
let out = proxy()
.run(serde_json::json!({ "search": "", "tool": "x/y", "args": " " }), &cx())
.await;
match &out.content[0] {
ContentBlock::Text(t) => assert!(t.contains("unknown MCP tool"), "{t}"),
_ => panic!("expected text"),
}
}
#[tokio::test]
async fn describe_unknown_tool_errors() {
let out = proxy().run(serde_json::json!({ "tool": "x/y" }), &cx()).await;
assert!(out.is_error);
}
}