use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum FederatedPeerClass {
Computer,
Phone,
Sim,
Unknown,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
#[non_exhaustive]
pub enum RemoteClaim {
#[non_exhaustive]
Agent { agent_id: String },
#[non_exhaustive]
Worker {
owner_module_id: String,
worker_ref: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
on_behalf_of: Option<String>,
},
#[non_exhaustive]
Run { agent_id: String },
#[non_exhaustive]
Flow {
flow_id: String,
flow_version: u64,
flow_install_id: String,
flow_code_hash: String,
},
}
impl RemoteClaim {
pub fn agent(agent_id: impl Into<String>) -> Self {
Self::Agent {
agent_id: agent_id.into(),
}
}
pub fn worker(
owner_module_id: impl Into<String>,
worker_ref: impl Into<String>,
on_behalf_of: Option<String>,
) -> Self {
Self::Worker {
owner_module_id: owner_module_id.into(),
worker_ref: worker_ref.into(),
on_behalf_of,
}
}
pub fn run(agent_id: impl Into<String>) -> Self {
Self::Run {
agent_id: agent_id.into(),
}
}
pub fn flow(
flow_id: impl Into<String>,
flow_version: u64,
flow_install_id: impl Into<String>,
flow_code_hash: impl Into<String>,
) -> Self {
Self::Flow {
flow_id: flow_id.into(),
flow_version,
flow_install_id: flow_install_id.into(),
flow_code_hash: flow_code_hash.into(),
}
}
pub fn validate(&self) -> Result<(), String> {
let token = |name, value: &str| {
crate::tool_call::validate_opaque_field(name, value).map_err(|e| e.to_string())
};
match self {
Self::Agent { agent_id } | Self::Run { agent_id } => token("agent_id", agent_id),
Self::Worker {
owner_module_id,
worker_ref,
on_behalf_of,
} => {
crate::manifest::validate_module_id(owner_module_id).map_err(|e| e.to_string())?;
hex("worker_ref", worker_ref, 64)?;
if let Some(agent) = on_behalf_of {
token("on_behalf_of", agent)?;
}
Ok(())
}
Self::Flow {
flow_id,
flow_version,
flow_install_id,
flow_code_hash,
} => {
token("flow_id", flow_id)?;
super::validate_flow_version(*flow_version).map_err(str::to_string)?;
token("flow_install_id", flow_install_id)?;
hex("flow_code_hash", flow_code_hash, 64)
}
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct FederatedAttributes {
pub peer_class: FederatedPeerClass,
pub peer_fingerprint: String,
pub pairing_id: String,
pub peer_name: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub remote_claim: Option<RemoteClaim>,
}
impl FederatedAttributes {
pub fn new(
peer_class: FederatedPeerClass,
peer_fingerprint: String,
pairing_id: String,
peer_name: String,
) -> Self {
Self {
peer_class,
peer_fingerprint,
pairing_id,
peer_name,
remote_claim: None,
}
}
#[must_use]
pub fn with_remote_claim(mut self, claim: Option<RemoteClaim>) -> Self {
self.remote_claim = claim;
self
}
pub fn validate(&self) -> Result<(), String> {
hex("peer_fingerprint", &self.peer_fingerprint, 32)?;
crate::tool_call::validate_opaque_field("pairing_id", &self.pairing_id)
.map_err(|e| e.to_string())?;
crate::manifest::validate_plain_text(&self.peer_name, 80)
.map_err(|e| format!("peer_name {e}"))?;
if let Some(claim) = &self.remote_claim {
claim.validate()?;
}
Ok(())
}
}
fn hex(name: &str, value: &str, length: usize) -> Result<(), String> {
if value.len() != length
|| !value
.bytes()
.all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
{
return Err(format!(
"{name} must contain exactly {length} lowercase hex characters"
));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn attributes() -> FederatedAttributes {
FederatedAttributes::new(
FederatedPeerClass::Computer,
"a".repeat(32),
"pairing".into(),
"Peer".into(),
)
}
#[test]
fn federated_claim_roundtrips_and_enforces_every_field_bound() {
for claim in [
RemoteClaim::Agent {
agent_id: "a".repeat(256),
},
RemoteClaim::Run {
agent_id: "a".repeat(256),
},
RemoteClaim::Worker {
owner_module_id: "mcp:module".into(),
worker_ref: "a".repeat(64),
on_behalf_of: Some("a".repeat(256)),
},
RemoteClaim::Flow {
flow_id: "a".repeat(256),
flow_version: 9_007_199_254_740_991,
flow_install_id: "b".repeat(256),
flow_code_hash: "f".repeat(64),
},
] {
claim.validate().unwrap();
let value = serde_json::to_value(&claim).unwrap();
assert_eq!(
serde_json::from_value::<RemoteClaim>(value.clone()).unwrap(),
claim
);
let mut unknown = value.clone();
unknown["unexpected"] = json!(true);
assert!(serde_json::from_value::<RemoteClaim>(unknown).is_err());
for key in ["agent_id", "flow_id", "flow_install_id", "on_behalf_of"] {
if value.get(key).is_some() {
for bad in [
"".to_string(),
"x".repeat(257),
"with space".into(),
"\n".into(),
"é".into(),
] {
let mut invalid = value.clone();
invalid[key] = json!(bad);
assert!(
serde_json::from_value::<RemoteClaim>(invalid)
.unwrap()
.validate()
.is_err(),
"{key}"
);
}
}
}
for key in ["worker_ref", "flow_code_hash"] {
if value.get(key).is_some() {
for bad in [
"a".repeat(63),
"A".repeat(64),
"g".repeat(64),
"a".repeat(65),
] {
let mut invalid = value.clone();
invalid[key] = json!(bad);
assert!(serde_json::from_value::<RemoteClaim>(invalid)
.unwrap()
.validate()
.is_err());
}
}
}
if value.get("flow_version").is_some() {
for bad in [0u64, 9_007_199_254_740_992] {
let mut invalid = value.clone();
invalid["flow_version"] = json!(bad);
assert!(serde_json::from_value::<RemoteClaim>(invalid)
.unwrap()
.validate()
.is_err());
}
}
if value.get("owner_module_id").is_some() {
for bad in ["", "..", "a/b", "a\\b", "\n"] {
let mut invalid = value.clone();
invalid["owner_module_id"] = json!(bad);
assert!(serde_json::from_value::<RemoteClaim>(invalid)
.unwrap()
.validate()
.is_err());
}
}
}
assert!(serde_json::from_value::<RemoteClaim>(json!({"kind":"future"})).is_err());
}
#[test]
fn federated_attributes_roundtrip_classes_and_enforce_limits_and_unknown_members() {
for class in [
FederatedPeerClass::Computer,
FederatedPeerClass::Phone,
FederatedPeerClass::Sim,
FederatedPeerClass::Unknown,
] {
let mut facts = attributes();
facts.peer_class = class;
facts.peer_name = "界".repeat(80);
facts.validate().unwrap();
let value = serde_json::to_value(&facts).unwrap();
assert_eq!(
serde_json::from_value::<FederatedAttributes>(value.clone()).unwrap(),
facts
);
let mut unknown = value;
unknown["unexpected"] = json!(true);
assert!(serde_json::from_value::<FederatedAttributes>(unknown).is_err());
}
for bad in [
"",
"a\n",
"a\u{061c}",
"a\u{200e}",
"a\u{202e}",
"a\u{2069}",
&"a".repeat(81),
] {
let mut facts = attributes();
facts.peer_name = bad.into();
assert!(facts.validate().is_err());
}
for bad in [
"A".repeat(32),
"a".repeat(31),
"a".repeat(33),
"g".repeat(32),
] {
let mut facts = attributes();
facts.peer_fingerprint = bad;
assert!(facts.validate().is_err());
}
for bad in ["".to_string(), "x".repeat(257), "space here".into()] {
let mut facts = attributes();
facts.pairing_id = bad;
assert!(facts.validate().is_err());
}
let mut facts = attributes();
facts.pairing_id = "x".repeat(256);
facts.validate().unwrap();
}
#[test]
fn federated_absent_keeps_nonfederated_stamps_readable_by_the_strict_034_attributes_decoder() {
#[derive(Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
#[allow(dead_code)]
struct Attributes034 {
agent_id: Option<String>,
delegates: bool,
on_behalf_of_agent: Option<String>,
flow_id: Option<String>,
flow_version: Option<u64>,
flow_code_hash: Option<String>,
flow_install_id: Option<String>,
run_id: Option<String>,
}
#[derive(Deserialize)]
#[serde(rename_all = "snake_case")]
enum Kind034 {
Head,
Worker,
Ephemeral,
}
#[derive(Deserialize)]
struct Stamp034 {
kind: Kind034,
#[serde(default)]
attributes: Attributes034,
}
for (kind, wire_kind) in [
(crate::scope::ScopeKind::Head, "head"),
(crate::scope::ScopeKind::Worker, "worker"),
(crate::scope::ScopeKind::Ephemeral, "ephemeral"),
] {
let stamp = crate::scope::ScopeStamp::new(crate::Principal::Direct, "legacy", 1, kind)
.with_attributes(
crate::scope::ScopeAttributes::new()
.with_agent_id(Some("agent".into()))
.with_delegates(true),
);
let value = serde_json::to_value(stamp).unwrap();
assert!(value["attributes"].get("federated").is_none());
assert_eq!(value["kind"], wire_kind);
let old: Stamp034 = serde_json::from_value(value.clone()).unwrap();
assert!(matches!(
old.kind,
Kind034::Head | Kind034::Worker | Kind034::Ephemeral
));
assert_eq!(old.attributes.agent_id.as_deref(), Some("agent"));
assert!(old.attributes.delegates);
let mut bad = value["attributes"].clone();
bad["federated"] = serde_json::to_value(attributes()).unwrap();
assert!(serde_json::from_value::<Attributes034>(bad).is_err());
}
}
}