use {
anyhow::Context as _,
ed25519_dalek::SigningKey,
nexus_sdk::signed_http::{
keys::parse_ed25519_signing_key,
v3::wire::{AllowedLeaders, AllowedLeadersFileV1},
},
notify::{Event, RecommendedWatcher, RecursiveMode, Watcher},
serde::Deserialize,
std::{
collections::BTreeMap,
fs,
path::{Path, PathBuf},
sync::{Arc, RwLock},
time::Duration,
},
};
pub const ENV_TOOLKIT_CONFIG_PATH: &str = "NEXUS_TOOLKIT_CONFIG_PATH";
const DEFAULT_INVOKE_MAX_BODY_BYTES: u64 = 10 * 1024 * 1024;
#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum SignedHttpMode {
Disabled,
#[default]
Required,
}
#[derive(Clone)]
pub struct ToolkitRuntimeConfig {
invoke_max_body_bytes: u64,
signed_http: Option<SignedHttpRuntimeConfig>,
source_path: Option<PathBuf>,
}
#[derive(Clone)]
pub(crate) struct SignedHttpRuntimeConfig {
pub(crate) allowed_leaders: Arc<AllowedLeaders>,
pub(crate) tools: BTreeMap<String, SignedHttpToolRuntimeConfig>,
}
#[derive(Clone)]
pub(crate) struct SignedHttpToolRuntimeConfig {
pub(crate) response_signing_key: Option<SigningKey>,
pub(crate) replay_cache_ttl_ms: u64,
}
pub(crate) const DEFAULT_REPLAY_CACHE_TTL_MS: u64 = 300_000;
impl ToolkitRuntimeConfig {
pub fn from_env() -> anyhow::Result<Self> {
let Some(path) = std::env::var(ENV_TOOLKIT_CONFIG_PATH).ok() else {
return Ok(Self::default_for_runtime());
};
Self::from_path(path)
}
pub fn from_path(path: impl AsRef<Path>) -> anyhow::Result<Self> {
let path = path.as_ref();
let bytes = fs::read(path).with_context(|| format!("failed to read {}", path.display()))?;
let mut cfg = Self::from_json_bytes(&bytes).with_context(|| {
format!(
"failed to parse toolkit runtime config at {}",
path.display()
)
})?;
cfg.source_path = Some(path.to_path_buf());
Ok(cfg)
}
pub fn from_json_bytes(bytes: &[u8]) -> anyhow::Result<Self> {
let file: ToolkitRuntimeConfigFile =
serde_json::from_slice(bytes).context("invalid JSON")?;
Self::try_from(file)
}
pub fn from_json_str(json: &str) -> anyhow::Result<Self> {
Self::from_json_bytes(json.as_bytes())
}
pub fn invoke_max_body_bytes(&self) -> u64 {
self.invoke_max_body_bytes
}
pub fn signed_http_is_required(&self) -> bool {
self.signed_http.is_some()
}
pub fn has_tool(&self, tool_id: &str) -> bool {
self.signed_http
.as_ref()
.is_some_and(|s| s.tools.contains_key(tool_id))
}
pub(crate) fn signed_http(&self) -> Option<&SignedHttpRuntimeConfig> {
self.signed_http.as_ref()
}
fn default_for_runtime() -> Self {
Self {
invoke_max_body_bytes: DEFAULT_INVOKE_MAX_BODY_BYTES,
signed_http: None,
source_path: None,
}
}
pub(crate) fn source_path(&self) -> Option<&Path> {
self.source_path.as_deref()
}
}
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ToolkitRuntimeConfigFile {
#[serde(default)]
pub invoke_max_body_bytes: Option<u64>,
#[serde(default)]
pub signed_http: Option<SignedHttpConfigFile>,
}
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct SignedHttpConfigFile {
#[serde(default)]
pub mode: SignedHttpMode,
#[serde(default)]
pub allowed_leaders_path: Option<String>,
#[serde(default)]
pub allowed_leaders: Option<AllowedLeadersFileV1>,
#[serde(default)]
pub tools: BTreeMap<String, SignedHttpToolConfigFile>,
}
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct SignedHttpToolConfigFile {
#[serde(default)]
pub response_signing_key: Option<String>,
#[serde(default)]
pub replay_cache_ttl_ms: Option<u64>,
}
impl TryFrom<ToolkitRuntimeConfigFile> for ToolkitRuntimeConfig {
type Error = anyhow::Error;
fn try_from(file: ToolkitRuntimeConfigFile) -> Result<Self, Self::Error> {
let invoke_max_body_bytes = file
.invoke_max_body_bytes
.unwrap_or(DEFAULT_INVOKE_MAX_BODY_BYTES);
let signed_http = match file.signed_http {
None => None,
Some(s) if s.mode == SignedHttpMode::Disabled => None,
Some(s) => Some(load_signed_http_config(s)?),
};
Ok(Self {
invoke_max_body_bytes,
signed_http,
source_path: None,
})
}
}
fn load_signed_http_config(file: SignedHttpConfigFile) -> anyhow::Result<SignedHttpRuntimeConfig> {
let allowed_leaders = match (file.allowed_leaders, file.allowed_leaders_path) {
(Some(inline), _) => AllowedLeaders::try_from(inline).map_err(anyhow::Error::new)?,
(None, Some(path)) => AllowedLeaders::from_path(path).map_err(anyhow::Error::new)?,
(None, None) => {
anyhow::bail!("signed_http requires either allowed_leaders or allowed_leaders_path")
}
};
let allowed_leaders = Arc::new(allowed_leaders);
if file.tools.is_empty() {
anyhow::bail!("signed_http.tools must contain at least one tool entry");
}
let mut tools: BTreeMap<String, SignedHttpToolRuntimeConfig> = BTreeMap::new();
for (tool_id, tool) in file.tools {
let replay_cache_ttl_ms = tool
.replay_cache_ttl_ms
.unwrap_or(DEFAULT_REPLAY_CACHE_TTL_MS);
if replay_cache_ttl_ms == 0 {
anyhow::bail!(
"invalid signed_http.tools[\"{tool_id}\"].replay_cache_ttl_ms: must be greater than zero"
);
}
let response_signing_key = tool
.response_signing_key
.as_deref()
.map(parse_ed25519_signing_key)
.transpose()
.map_err(|e| {
anyhow::anyhow!(
"invalid signed_http.tools[\"{tool_id}\"].response_signing_key: {e}"
)
})?;
tools.insert(
tool_id,
SignedHttpToolRuntimeConfig {
response_signing_key,
replay_cache_ttl_ms,
},
);
}
Ok(SignedHttpRuntimeConfig {
allowed_leaders,
tools,
})
}
#[doc(hidden)]
pub struct Config {
config: Arc<RwLock<Arc<ToolkitRuntimeConfig>>>,
_watcher: Option<RecommendedWatcher>,
}
impl Config {
#[doc(hidden)]
#[cfg(test)]
pub async fn from_env() -> anyhow::Result<Arc<Self>> {
let path = std::env::var(ENV_TOOLKIT_CONFIG_PATH)
.ok()
.map(PathBuf::from);
let initial_config = match &path {
Some(p) => ToolkitRuntimeConfig::from_path(p)?,
None => ToolkitRuntimeConfig::default_for_runtime(),
};
let config = Arc::new(RwLock::new(Arc::new(initial_config)));
let watcher = if let Some(ref p) = path {
Some(Self::start_watcher(p.clone(), Arc::clone(&config))?)
} else {
None
};
Ok(Arc::new(Self {
config,
_watcher: watcher,
}))
}
#[doc(hidden)]
pub fn from_config(config: Arc<ToolkitRuntimeConfig>) -> Arc<Self> {
let path = config.source_path().map(|p| p.to_path_buf());
let config_holder = Arc::new(RwLock::new(config));
let watcher = path.and_then(|p| {
Self::start_watcher(p, Arc::clone(&config_holder))
.map_err(|e| {
tracing::warn!("Failed to start config file watcher: {e}");
e
})
.ok()
});
Arc::new(Self {
config: config_holder,
_watcher: watcher,
})
}
#[doc(hidden)]
pub fn current(&self) -> Arc<ToolkitRuntimeConfig> {
self.config.read().unwrap().clone()
}
fn start_watcher(
path: PathBuf,
config: Arc<RwLock<Arc<ToolkitRuntimeConfig>>>,
) -> anyhow::Result<RecommendedWatcher> {
let (tx, mut rx) = tokio::sync::mpsc::channel::<()>(1);
let mut watcher = notify::recommended_watcher(move |res: Result<Event, notify::Error>| {
if let Ok(event) = res {
if event.kind.is_modify() || event.kind.is_create() {
let _ = tx.try_send(());
}
}
})?;
let watch_path = path.parent().unwrap_or(&path);
watcher.watch(watch_path, RecursiveMode::NonRecursive)?;
tracing::info!("Started config file watcher for {}", path.display());
let reload_path = path.clone();
tokio::spawn(async move {
let debounce_duration = Duration::from_millis(500);
let poll_interval = Duration::from_secs(2);
let mut poll_tick = tokio::time::interval(poll_interval);
let mut last_modified = file_modified(reload_path.clone()).await;
loop {
tokio::select! {
maybe_event = rx.recv() => {
if maybe_event.is_none() {
break;
}
tokio::time::sleep(debounce_duration).await;
while rx.try_recv().is_ok() {}
}
_ = poll_tick.tick() => {
let current_modified = file_modified(reload_path.clone()).await;
if current_modified == last_modified {
continue;
}
}
}
match reload_config(reload_path.clone()).await {
Ok((new_config, current_modified)) => {
last_modified = current_modified;
let mut guard = config.write().unwrap();
*guard = Arc::new(new_config);
tracing::info!("Reloaded toolkit config from {}", reload_path.display());
}
Err(e) => {
tracing::error!(
"Failed to reload toolkit config from {}: {e}",
reload_path.display()
);
}
}
}
});
Ok(watcher)
}
}
async fn file_modified(path: PathBuf) -> Option<std::time::SystemTime> {
tokio::task::spawn_blocking(move || fs::metadata(path).and_then(|meta| meta.modified()).ok())
.await
.unwrap_or(None)
}
async fn reload_config(
path: PathBuf,
) -> anyhow::Result<(ToolkitRuntimeConfig, Option<std::time::SystemTime>)> {
tokio::task::spawn_blocking(move || {
let config = ToolkitRuntimeConfig::from_path(&path)?;
let modified = fs::metadata(&path).and_then(|meta| meta.modified()).ok();
Ok((config, modified))
})
.await
.context("config reload task failed")?
}
#[cfg(test)]
mod tests {
use {
super::*,
crate::test_utils::ENV_VAR_LOCK,
serde_json::{json, Map},
};
fn make_config_json(
tool_id: &str,
tool_sk_hex: &str,
leader_id: &str,
leader_pk_hex: &str,
) -> String {
let mut tools = Map::new();
tools.insert(
tool_id.to_string(),
json!({
"response_signing_key": tool_sk_hex,
}),
);
serde_json::to_string(&json!({
"invoke_max_body_bytes": 123,
"signed_http": {
"mode": "required",
"allowed_leaders": {
"version": 1,
"leaders": [{
"leader_id": leader_id,
"keys": [{
"kid": 0,
"public_key": leader_pk_hex,
}],
}],
},
"tools": tools,
},
}))
.unwrap()
}
#[test]
fn parse_signed_http_inline_config() {
let leader_sk = SigningKey::from_bytes(&[7u8; 32]);
let leader_pk_hex = hex::encode(leader_sk.verifying_key().to_bytes());
let tool_id = "xyz.demo.tool@1";
let tool_sk_hex = hex::encode([9u8; 32]);
let cfg_json = make_config_json(tool_id, &tool_sk_hex, "0x1111", &leader_pk_hex);
let cfg = ToolkitRuntimeConfig::from_json_str(&cfg_json).unwrap();
assert_eq!(cfg.invoke_max_body_bytes(), 123);
assert!(cfg.signed_http_is_required());
assert!(cfg.has_tool(tool_id));
assert!(cfg.signed_http().unwrap().tools[tool_id]
.response_signing_key
.is_some());
assert!(cfg
.signed_http()
.unwrap()
.allowed_leaders
.source_path()
.is_none());
}
#[test]
fn parse_verification_only_tool_config() {
let leader_sk = SigningKey::from_bytes(&[7u8; 32]);
let leader_pk_hex = hex::encode(leader_sk.verifying_key().to_bytes());
let tool_id = "xyz.demo.tool@1";
let cfg_json = serde_json::to_string(&json!({
"signed_http": {
"mode": "required",
"allowed_leaders": {
"version": 1,
"leaders": [{
"leader_id": "0x1111",
"keys": [{
"kid": 0,
"public_key": leader_pk_hex,
}],
}],
},
"tools": {
tool_id: {
"replay_cache_ttl_ms": 60_000,
},
},
},
}))
.unwrap();
let cfg = ToolkitRuntimeConfig::from_json_str(&cfg_json).unwrap();
let tool = &cfg.signed_http().unwrap().tools[tool_id];
assert!(tool.response_signing_key.is_none());
assert_eq!(tool.replay_cache_ttl_ms, 60_000);
}
#[test]
fn parse_signed_http_from_path() {
let leader_sk = SigningKey::from_bytes(&[5u8; 32]);
let leader_pk_hex = hex::encode(leader_sk.verifying_key().to_bytes());
let tool_sk_hex = hex::encode([6u8; 32]);
let allowlist_json = serde_json::to_string(&json!({
"version": 1,
"leaders": [{
"leader_id": "0x9999",
"keys": [{
"kid": 0,
"public_key": leader_pk_hex,
}],
}],
}))
.unwrap();
let file_name = format!(
"nexus-allowlist-{}.json",
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
);
let path = std::env::temp_dir().join(file_name);
fs::write(&path, allowlist_json).unwrap();
let cfg_json = serde_json::to_string(&json!({
"signed_http": {
"mode": "required",
"allowed_leaders_path": path.display().to_string(),
"tools": {
"xyz.demo.tool@1": {
"response_signing_key": tool_sk_hex,
},
},
},
}))
.unwrap();
let cfg = ToolkitRuntimeConfig::from_json_str(&cfg_json).unwrap();
assert!(cfg.signed_http_is_required());
assert!(cfg.has_tool("xyz.demo.tool@1"));
assert_eq!(
cfg.signed_http().unwrap().allowed_leaders.source_path(),
Some(path.as_path())
);
}
#[test]
fn signed_http_disabled_is_ignored() {
let cfg_json = serde_json::to_string(&json!({
"signed_http": {
"mode": "disabled",
},
}))
.unwrap();
let cfg = ToolkitRuntimeConfig::from_json_str(&cfg_json).unwrap();
assert!(!cfg.signed_http_is_required());
}
#[test]
fn signed_http_requires_allowlist() {
let cfg_json = serde_json::to_string(&json!({
"signed_http": {
"mode": "required",
"tools": {
"demo": {},
},
},
}))
.unwrap();
assert!(ToolkitRuntimeConfig::from_json_str(&cfg_json).is_err());
}
#[test]
fn signed_http_requires_tool_entries() {
let cfg_json = serde_json::to_string(&json!({
"signed_http": {
"mode": "required",
"allowed_leaders": {
"version": 1,
"leaders": [],
},
},
}))
.unwrap();
assert!(ToolkitRuntimeConfig::from_json_str(&cfg_json).is_err());
}
#[test]
fn removed_signed_http_claim_fields_are_rejected() {
let cfg_json = serde_json::to_string(&json!({
"signed_http": {
"mode": "disabled",
"max_clock_skew_ms": 10,
},
}))
.unwrap();
assert!(ToolkitRuntimeConfig::from_json_str(&cfg_json).is_err());
let cfg_json = serde_json::to_string(&json!({
"signed_http": {
"mode": "required",
"allowed_leaders": { "version": 1, "leaders": [] },
"tools": {
"demo": {
"tool_kid": 0,
"response_signing_key": hex::encode([7; 32]),
},
},
},
}))
.unwrap();
assert!(ToolkitRuntimeConfig::from_json_str(&cfg_json).is_err());
}
#[test]
fn rejects_obsolete_top_level_version() {
let cfg_json = serde_json::to_string(&json!({
"version": 1,
}))
.unwrap();
assert!(ToolkitRuntimeConfig::from_json_str(&cfg_json).is_err());
}
#[test]
fn from_path_sets_source_path() {
let leader_sk = SigningKey::from_bytes(&[7u8; 32]);
let leader_pk_hex = hex::encode(leader_sk.verifying_key().to_bytes());
let tool_id = "xyz.demo.tool@1";
let tool_sk_hex = hex::encode([9u8; 32]);
let file_name = format!(
"nexus-source-path-test-{}.json",
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
);
let path = std::env::temp_dir().join(&file_name);
let cfg_json = make_config_json(tool_id, &tool_sk_hex, "0x1111", &leader_pk_hex);
fs::write(&path, &cfg_json).unwrap();
let cfg = ToolkitRuntimeConfig::from_path(&path).unwrap();
assert_eq!(cfg.source_path(), Some(path.as_path()));
let _ = fs::remove_file(&path);
}
#[test]
fn from_path_error_on_missing_file() {
let result = ToolkitRuntimeConfig::from_path("/nonexistent/path/config.json");
assert!(result.is_err());
let err = format!("{:?}", result.err().unwrap());
assert!(err.contains("failed to read"));
}
#[test]
fn from_path_error_on_invalid_json() {
let file_name = format!(
"nexus-invalid-json-test-{}.json",
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
);
let path = std::env::temp_dir().join(&file_name);
fs::write(&path, "{ not valid json }").unwrap();
let result = ToolkitRuntimeConfig::from_path(&path);
assert!(result.is_err());
let err = format!("{:?}", result.err().unwrap());
assert!(err.contains("failed to parse"));
let _ = fs::remove_file(&path);
}
#[test]
fn from_json_str_has_no_source_path() {
let cfg_json = serde_json::to_string(&json!({})).unwrap();
let cfg = ToolkitRuntimeConfig::from_json_str(&cfg_json).unwrap();
assert!(cfg.source_path().is_none());
}
#[allow(clippy::await_holding_lock)]
#[tokio::test]
async fn config_watcher_loads_default_without_env_var() {
let _guard = ENV_VAR_LOCK.lock().unwrap();
std::env::remove_var(ENV_TOOLKIT_CONFIG_PATH);
let watcher = Config::from_env().await.unwrap();
let config = watcher.current();
assert!(!config.signed_http_is_required());
assert_eq!(config.invoke_max_body_bytes(), 10 * 1024 * 1024);
}
#[allow(clippy::await_holding_lock)]
#[tokio::test]
async fn config_watcher_loads_from_file() {
let _guard = ENV_VAR_LOCK.lock().unwrap();
let leader_sk = SigningKey::from_bytes(&[7u8; 32]);
let leader_pk_hex = hex::encode(leader_sk.verifying_key().to_bytes());
let tool_id = "xyz.demo.tool@1";
let tool_sk_hex = hex::encode([9u8; 32]);
let file_name = format!(
"nexus-watcher-test-{}.json",
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
);
let path = std::env::temp_dir().join(&file_name);
let cfg_json = make_config_json(tool_id, &tool_sk_hex, "0x1111", &leader_pk_hex);
fs::write(&path, &cfg_json).unwrap();
std::env::set_var(ENV_TOOLKIT_CONFIG_PATH, path.display().to_string());
let watcher = Config::from_env().await.unwrap();
let config = watcher.current();
assert_eq!(config.invoke_max_body_bytes(), 123);
assert!(config.signed_http_is_required());
assert!(config.has_tool(tool_id));
std::env::remove_var(ENV_TOOLKIT_CONFIG_PATH);
let _ = fs::remove_file(&path);
}
#[allow(clippy::await_holding_lock)]
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn config_watcher_reloads_on_file_change() {
let _guard = ENV_VAR_LOCK.lock().unwrap();
let leader_sk = SigningKey::from_bytes(&[7u8; 32]);
let leader_pk_hex = hex::encode(leader_sk.verifying_key().to_bytes());
let tool_id = "xyz.demo.tool@1";
let tool_sk_hex = hex::encode([9u8; 32]);
let file_name = format!(
"nexus-watcher-reload-test-{}.json",
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
);
let path = std::env::temp_dir().join(&file_name);
let cfg_json = make_config_json(tool_id, &tool_sk_hex, "0x1111", &leader_pk_hex);
fs::write(&path, &cfg_json).unwrap();
std::env::set_var(ENV_TOOLKIT_CONFIG_PATH, path.display().to_string());
let watcher = Config::from_env().await.unwrap();
let config = watcher.current();
assert_eq!(config.invoke_max_body_bytes(), 123);
let new_cfg_json = serde_json::to_string(&json!({
"invoke_max_body_bytes": 456,
"signed_http": {
"mode": "required",
"allowed_leaders": {
"version": 1,
"leaders": [{
"leader_id": "0x1111",
"keys": [{
"kid": 0,
"public_key": leader_pk_hex,
}],
}],
},
"tools": {
"xyz.demo.tool@1": {
"response_signing_key": tool_sk_hex,
},
},
},
}))
.unwrap();
fs::write(&path, &new_cfg_json).unwrap();
tokio::time::sleep(std::time::Duration::from_millis(700)).await;
let config = watcher.current();
assert_eq!(config.invoke_max_body_bytes(), 456);
std::env::remove_var(ENV_TOOLKIT_CONFIG_PATH);
let _ = fs::remove_file(&path);
}
#[allow(clippy::await_holding_lock)]
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn config_watcher_keeps_old_on_invalid_update() {
let _guard = ENV_VAR_LOCK.lock().unwrap();
let leader_sk = SigningKey::from_bytes(&[7u8; 32]);
let leader_pk_hex = hex::encode(leader_sk.verifying_key().to_bytes());
let tool_id = "xyz.demo.tool@1";
let tool_sk_hex = hex::encode([9u8; 32]);
let file_name = format!(
"nexus-watcher-invalid-test-{}.json",
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
);
let path = std::env::temp_dir().join(&file_name);
let cfg_json = make_config_json(tool_id, &tool_sk_hex, "0x1111", &leader_pk_hex);
fs::write(&path, &cfg_json).unwrap();
std::env::set_var(ENV_TOOLKIT_CONFIG_PATH, path.display().to_string());
let watcher = Config::from_env().await.unwrap();
let config = watcher.current();
assert_eq!(config.invoke_max_body_bytes(), 123);
fs::write(&path, "{ invalid json }").unwrap();
tokio::time::sleep(std::time::Duration::from_millis(700)).await;
let config = watcher.current();
assert_eq!(config.invoke_max_body_bytes(), 123);
std::env::remove_var(ENV_TOOLKIT_CONFIG_PATH);
let _ = fs::remove_file(&path);
}
}