@7h3/protocol 0.1.2 → 0.4.0

package/sdk/rust/src/queue.rs

@@ -0,0 +1,79 @@
+//! Queue binding — signed message envelope for Kafka/SQS/Pub-Sub transit.
+
+use crate::{
+    create_envelope, sign_envelope_ed25519, validate_envelope, verify_envelope_ed25519,
+    ProtocolBody, ProtocolEnvelope,
+};
+use serde::{Deserialize, Serialize};
+
+pub const DEFAULT_TTL_MS: i64 = 3_600_000;
+
+#[derive(Serialize, Deserialize)]
+pub struct QueueMessage<T: Serialize> {
+    pub envelope: ProtocolEnvelope,
+    pub payload: T,
+}
+
+fn now_ms() -> i64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as i64
+}
+
+/// Sign a payload for queue transit. Returns a JSON string.
+pub fn sign_queue_message<T: Serialize>(
+    payload: &T,
+    private_key: &str,
+    key_id: &str,
+    sender: &str,
+    recipient: Option<&str>,
+    ttl_ms: Option<i64>,
+) -> Result<String, Box<dyn std::error::Error>> {
+    let content = serde_json::to_string(payload)?;
+    let now = now_ms();
+    let envelope = create_envelope(
+        sender,
+        recipient,
+        "TASK",
+        &content,
+        None,
+        None,
+        now,
+        ttl_ms.unwrap_or(DEFAULT_TTL_MS),
+    );
+    let signed = sign_envelope_ed25519(&envelope, private_key, key_id)
+        .map_err(|e| -> Box<dyn std::error::Error> { e.into() })?;
+    // Re-serialize payload as Value so the QueueMessage wrapper holds both fields
+    let payload_value = serde_json::to_value(payload)?;
+    let msg = serde_json::json!({
+        "envelope": signed,
+        "payload": payload_value,
+    });
+    Ok(serde_json::to_string(&msg)?)
+}
+
+/// Verify and unwrap a queue message. Returns (payload_json_value, envelope).
+pub fn verify_queue_message(
+    message: &str,
+    public_key: &str,
+) -> Result<(serde_json::Value, ProtocolEnvelope), Box<dyn std::error::Error>> {
+    let wrapper: serde_json::Value = serde_json::from_str(message)?;
+
+    let envelope: ProtocolEnvelope = serde_json::from_value(wrapper["envelope"].clone())
+        .map_err(|e| -> Box<dyn std::error::Error> { format!("malformed envelope: {e}").into() })?;
+
+    let now = now_ms();
+    let diags = validate_envelope(&envelope, Some(now));
+    if diags.iter().any(|d| d.level == "error") {
+        return Err("envelope expired or invalid".into());
+    }
+
+    let valid = verify_envelope_ed25519(&envelope, public_key)
+        .map_err(|e| -> Box<dyn std::error::Error> { e.into() })?;
+    if !valid {
+        return Err("invalid signature".into());
+    }
+
+    Ok((wrapper["payload"].clone(), envelope))
+}

package/sdk/rust/src/webhook.rs

@@ -0,0 +1,86 @@
+//! Webhook binding — lightweight per-payload Ed25519/HMAC signing.
+//! Signs "${timestamp_ms}.${body}" to bind time and content together.
+
+use crate::{
+    sign_canonical_payload_ed25519, sign_canonical_payload_hmac, verify_canonical_payload_ed25519,
+    verify_canonical_payload_hmac,
+};
+
+pub const SIG_HEADER: &str = "x-7h3-sig";
+pub const TS_HEADER: &str = "x-7h3-ts";
+pub const DEFAULT_TTL_MS: u64 = 300_000;
+
+fn signing_payload(timestamp_ms: u64, body: &str) -> String {
+    format!("{timestamp_ms}.{body}")
+}
+
+fn now_ms() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}
+
+/// Sign a webhook payload with Ed25519. Returns (sig_header_value, ts_header_value).
+pub fn sign_webhook(
+    body: &str,
+    private_key: &str,
+) -> Result<(String, String), Box<dyn std::error::Error>> {
+    let ts = now_ms();
+    let payload = signing_payload(ts, body);
+    let sig = sign_canonical_payload_ed25519(&payload, private_key)
+        .map_err(|e| -> Box<dyn std::error::Error> { e.into() })?;
+    Ok((sig, ts.to_string()))
+}
+
+/// Verify a webhook Ed25519 signature. Returns true if valid and not expired.
+pub fn verify_webhook(
+    body: &str,
+    sig: &str,
+    ts_str: &str,
+    public_key: &str,
+    max_age_ms: Option<u64>,
+) -> Result<bool, Box<dyn std::error::Error>> {
+    let ts: u64 = ts_str
+        .parse()
+        .map_err(|_| -> Box<dyn std::error::Error> { "invalid timestamp".into() })?;
+    let max_age = max_age_ms.unwrap_or(DEFAULT_TTL_MS);
+    let now = now_ms();
+    if now.saturating_sub(ts) > max_age {
+        return Ok(false);
+    }
+    let payload = signing_payload(ts, body);
+    verify_canonical_payload_ed25519(&payload, sig, public_key)
+        .map_err(|e| -> Box<dyn std::error::Error> { e.into() })
+}
+
+/// Sign a webhook payload with HMAC-SHA256 shared secret.
+/// Returns (sig_header_value, ts_header_value).
+pub fn sign_webhook_hmac(
+    body: &str,
+    secret: &str,
+) -> Result<(String, String), Box<dyn std::error::Error>> {
+    let ts = now_ms();
+    let payload = signing_payload(ts, body);
+    let sig = sign_canonical_payload_hmac(&payload, secret);
+    Ok((sig, ts.to_string()))
+}
+
+/// Verify an HMAC webhook signature.
+pub fn verify_webhook_hmac(
+    body: &str,
+    sig: &str,
+    ts_str: &str,
+    secret: &str,
+    max_age_ms: Option<u64>,
+) -> Result<bool, Box<dyn std::error::Error>> {
+    let ts: u64 = ts_str
+        .parse()
+        .map_err(|_| -> Box<dyn std::error::Error> { "invalid timestamp".into() })?;
+    let max_age = max_age_ms.unwrap_or(DEFAULT_TTL_MS);
+    if now_ms().saturating_sub(ts) > max_age {
+        return Ok(false);
+    }
+    let payload = signing_payload(ts, body);
+    Ok(verify_canonical_payload_hmac(&payload, sig, secret))
+}

package/sdk/rust/tests/conformance.rs

@@ -0,0 +1,148 @@
+use protocol_7h3::{
+    canonicalize_envelope, decode_envelope, encode_envelope_compact, sign_canonical_payload_hmac,
+    sign_envelope_ed25519, sign_envelope_hmac, validate_envelope, verify_canonical_payload_ed25519,
+    verify_canonical_payload_hmac, verify_envelope_ed25519, verify_envelope_hmac, ProtocolEnvelope,
+};
+use serde::Deserialize;
+use std::fs;
+use std::path::PathBuf;
+
+#[derive(Debug, Deserialize)]
+struct VectorFixture {
+    id: String,
+    secret: String,
+    #[serde(rename = "keyId")]
+    key_id: String,
+    envelope: ProtocolEnvelope,
+    canonical: String,
+    signature: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct Fixtures {
+    vectors: Vec<VectorFixture>,
+    #[serde(rename = "ed25519Vectors", default)]
+    ed25519_vectors: Vec<Ed25519VectorFixture>,
+}
+
+#[derive(Debug, Deserialize)]
+struct Ed25519VectorFixture {
+    id: String,
+    #[serde(rename = "keyId")]
+    key_id: String,
+    #[serde(rename = "publicKey")]
+    public_key: String,
+    #[serde(rename = "privateKey")]
+    private_key: String,
+    envelope: ProtocolEnvelope,
+    canonical: String,
+    signature: String,
+}
+
+fn load_fixtures() -> Fixtures {
+    let mut path = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    path.push("../../conformance/7h3_v0_1.json");
+    let raw = fs::read_to_string(path).expect("conformance fixture should exist");
+    serde_json::from_str(&raw).expect("conformance fixture should be valid JSON")
+}
+
+#[test]
+fn conformance_vectors_match_canonical_and_signatures() {
+    let fixtures = load_fixtures();
+    for vector in fixtures.vectors {
+        let canonical = canonicalize_envelope(&vector.envelope);
+        assert_eq!(
+            canonical, vector.canonical,
+            "canonical mismatch for {}",
+            vector.id
+        );
+
+        let signature = sign_canonical_payload_hmac(&canonical, &vector.secret);
+        assert_eq!(
+            signature, vector.signature,
+            "signature mismatch for {}",
+            vector.id
+        );
+
+        let signed = sign_envelope_hmac(&vector.envelope, &vector.secret, &vector.key_id);
+        assert!(verify_canonical_payload_hmac(
+            &canonical,
+            &vector.signature,
+            &vector.secret
+        ));
+        assert!(verify_envelope_hmac(&signed, &vector.secret));
+        assert!(!verify_envelope_hmac(
+            &signed,
+            &format!("{}-bad", vector.secret)
+        ));
+    }
+}
+
+#[test]
+fn compact_roundtrip_and_ttl_validation() {
+    let fixtures = load_fixtures();
+    for vector in fixtures.vectors {
+        let signed = sign_envelope_hmac(&vector.envelope, &vector.secret, &vector.key_id);
+        let encoded = encode_envelope_compact(&signed);
+        let decoded = decode_envelope(&encoded).expect("compact decode should succeed");
+        assert_eq!(
+            canonicalize_envelope(&decoded),
+            canonicalize_envelope(&signed)
+        );
+        assert_eq!(decoded.signature, signed.signature);
+
+        let valid = validate_envelope(&decoded, Some(decoded.header.timestamp_ms + 1));
+        assert!(
+            valid.iter().all(|d| d.message != "Message TTL expired"),
+            "valid envelope unexpectedly expired for {}",
+            vector.id
+        );
+
+        let expired = validate_envelope(
+            &decoded,
+            Some(decoded.header.timestamp_ms + decoded.header.ttl_ms + 1),
+        );
+        assert!(
+            expired.iter().any(|d| d.message == "Message TTL expired"),
+            "expired envelope missing TTL diagnostic for {}",
+            vector.id
+        );
+    }
+}
+
+#[test]
+fn ed25519_vectors_match_canonical_and_signatures() {
+    let fixtures = load_fixtures();
+    for vector in fixtures.ed25519_vectors {
+        let canonical = canonicalize_envelope(&vector.envelope);
+        assert_eq!(
+            canonical, vector.canonical,
+            "canonical mismatch for {}",
+            vector.id
+        );
+
+        let signature = protocol_7h3::sign_canonical_payload_ed25519(&canonical, &vector.private_key)
+            .expect("ed25519 sign should succeed");
+        assert_eq!(
+            signature, vector.signature,
+            "ed25519 signature mismatch for {}",
+            vector.id
+        );
+
+        assert!(
+            verify_canonical_payload_ed25519(&canonical, &vector.signature, &vector.public_key)
+                .expect("ed25519 verify should succeed"),
+            "ed25519 verify failed for {}",
+            vector.id
+        );
+
+        let signed = sign_envelope_ed25519(&vector.envelope, &vector.private_key, &vector.key_id)
+            .expect("sign envelope ed25519 should succeed");
+        assert!(
+            verify_envelope_ed25519(&signed, &vector.public_key)
+                .expect("verify envelope ed25519 should succeed"),
+            "ed25519 envelope verify failed for {}",
+            vector.id
+        );
+    }
+}

package/sdk/rust/tests/gateway.rs

@@ -0,0 +1,130 @@
+use protocol_7h3::{
+    create_aip_mcp_gateway_runtime, create_signed_task_from_jsonrpc,
+    jsonrpc_response_from_envelope, AipMcpGatewayOptions, JsonRpcBridgeConfig, JsonRpcId,
+    JsonRpcRequestLike,
+};
+use serde_json::json;
+
+#[test]
+fn jsonrpc_bridge_creates_signed_task_with_capability() {
+    let request = JsonRpcRequestLike {
+        jsonrpc: "2.0".to_string(),
+        id: JsonRpcId::Number(7),
+        method: "tools/call".to_string(),
+        params: Some(json!({"name":"planner"})),
+    };
+
+    let config = JsonRpcBridgeConfig {
+        recipient: Some("agent.worker".to_string()),
+        allowed_methods: Some(vec!["tools/call".to_string()]),
+        capability_prefix: "mcp.".to_string(),
+    };
+
+    let envelope = create_signed_task_from_jsonrpc(
+        &request,
+        "agent.gateway",
+        "secret",
+        "gateway-k1",
+        1_700_000_000_000,
+        &config,
+        Option::<fn(&JsonRpcRequestLike, &protocol_7h3::JsonRpcPolicyContext) -> bool>::None,
+        Option::<fn(&str, &JsonRpcRequestLike, &protocol_7h3::JsonRpcPolicyContext) -> bool>::None,
+    )
+    .expect("bridge should produce envelope");
+
+    assert_eq!(envelope.body.intent, "TASK");
+    assert_eq!(envelope.body.capability.as_deref(), Some("mcp.tools/call"));
+    assert_eq!(envelope.body.correlation_id.as_deref(), Some("7"));
+    assert!(envelope.signature.is_some());
+}
+
+#[test]
+fn jsonrpc_bridge_blocks_disallowed_method() {
+    let request = JsonRpcRequestLike {
+        jsonrpc: "2.0".to_string(),
+        id: JsonRpcId::String("abc".to_string()),
+        method: "resources/read".to_string(),
+        params: None,
+    };
+
+    let config = JsonRpcBridgeConfig {
+        recipient: Some("agent.worker".to_string()),
+        allowed_methods: Some(vec!["tools/call".to_string()]),
+        capability_prefix: "mcp.".to_string(),
+    };
+
+    let error = create_signed_task_from_jsonrpc(
+        &request,
+        "agent.gateway",
+        "secret",
+        "gateway-k1",
+        1_700_000_000_000,
+        &config,
+        Option::<fn(&JsonRpcRequestLike, &protocol_7h3::JsonRpcPolicyContext) -> bool>::None,
+        Option::<fn(&str, &JsonRpcRequestLike, &protocol_7h3::JsonRpcPolicyContext) -> bool>::None,
+    )
+    .expect_err("bridge should reject disallowed methods");
+
+    assert!(error.contains("not allowed"));
+}
+
+#[test]
+fn gateway_runtime_handles_line_success_and_errors() {
+    let options = AipMcpGatewayOptions {
+        shared_secret: "gateway-secret".to_string(),
+        ..AipMcpGatewayOptions::default()
+    };
+    let runtime = create_aip_mcp_gateway_runtime(options);
+
+    let ok_line = json!({
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {"name":"planner"}
+    })
+    .to_string();
+    let ok_response = runtime
+        .handle_line(&ok_line, 1_700_000_000_000)
+        .expect("non-empty response expected");
+    let ok_json: serde_json::Value =
+        serde_json::from_str(&ok_response).expect("valid json response");
+    assert_eq!(ok_json["jsonrpc"], "2.0");
+    assert_eq!(ok_json["id"], 1);
+    assert!(ok_json.get("result").is_some());
+
+    let bad_line = json!({"bad":true}).to_string();
+    let bad_response = runtime
+        .handle_line(&bad_line, 1_700_000_000_001)
+        .expect("error response expected");
+    let bad_json: serde_json::Value =
+        serde_json::from_str(&bad_response).expect("valid json response");
+    assert_eq!(bad_json["error"]["code"], -32600);
+}
+
+#[test]
+fn jsonrpc_response_maps_error_intent() {
+    let envelope = protocol_7h3::ProtocolEnvelope {
+        header: protocol_7h3::ProtocolHeader {
+            version: "7h3/0.1".to_string(),
+            message_id: "m1".to_string(),
+            timestamp_ms: 1,
+            ttl_ms: 1,
+            sender: "agent.worker".to_string(),
+            recipient: Some("agent.gateway".to_string()),
+            nonce: "n1".to_string(),
+        },
+        body: protocol_7h3::ProtocolBody {
+            intent: "ERROR".to_string(),
+            content: "permission denied".to_string(),
+            capability: Some("mcp.tools/call".to_string()),
+            correlation_id: Some("7".to_string()),
+        },
+        signature: None,
+    };
+
+    let response = jsonrpc_response_from_envelope(&envelope, JsonRpcId::Number(7));
+    assert_eq!(response.jsonrpc, "2.0");
+    assert_eq!(response.id, JsonRpcId::Number(7));
+    assert!(response.result.is_none());
+    assert_eq!(response.error.expect("error expected").code, -32000);
+}

package/sdk/rust/tests/http_webhook_queue.rs

@@ -0,0 +1,201 @@
+use protocol_7h3::{
+    create_envelope,
+    http::{sign_http_request, verify_http_envelope, EnvelopeInput, StaticKeyRegistry, VerifyFailReason, DEFAULT_HEADER},
+    queue::{sign_queue_message, verify_queue_message},
+    webhook::{sign_webhook, sign_webhook_hmac, verify_webhook, verify_webhook_hmac},
+    ProtocolBody,
+};
+use std::collections::HashMap;
+
+// Ed25519 test keys from the conformance vectors.
+const TEST_PRIVATE_KEY: &str = "MC4CAQAwBQYDK2VwBCIEICheZbQGuDVb6hezIlcs0QnCHGxz6IhiLkC9M0qr8OOZ";
+const TEST_PUBLIC_KEY: &str = "MCowBQYDK2VwAyEA-mUFiTQtcKN4nnD19V_-Wyy4q19OivnAutRUPhOcC78";
+const TEST_SENDER: &str = "agent.ed";
+
+fn make_registry() -> StaticKeyRegistry {
+    let mut keys = HashMap::new();
+    keys.insert(TEST_SENDER.to_string(), TEST_PUBLIC_KEY.to_string());
+    StaticKeyRegistry::new(keys)
+}
+
+fn make_input() -> EnvelopeInput {
+    EnvelopeInput {
+        sender: TEST_SENDER.to_string(),
+        recipient: Some("agent.verify".to_string()),
+        ttl_ms: 60_000,
+        body: ProtocolBody {
+            intent: "TASK".to_string(),
+            content: "hello-http".to_string(),
+            capability: None,
+            correlation_id: None,
+        },
+        key_id: "key-1".to_string(),
+    }
+}
+
+// ── HTTP tests ────────────────────────────────────────────────────────────────
+
+#[test]
+fn http_sign_produces_correct_header() {
+    let (name, value) = sign_http_request(&make_input(), TEST_PRIVATE_KEY, None)
+        .expect("sign_http_request should succeed");
+    assert_eq!(name, DEFAULT_HEADER, "header name should be x-7h3-envelope");
+    // value must be valid JSON containing an ED25519 signature
+    let parsed: serde_json::Value =
+        serde_json::from_str(&value).expect("header value must be valid JSON");
+    assert_eq!(
+        parsed["signature"]["alg"].as_str().unwrap(),
+        "ED25519",
+        "alg must be ED25519"
+    );
+}
+
+#[test]
+fn http_verify_passes_on_valid_envelope() {
+    let (name, value) = sign_http_request(&make_input(), TEST_PRIVATE_KEY, None)
+        .expect("sign should succeed");
+    let mut headers = HashMap::new();
+    headers.insert(name, value);
+
+    let registry = make_registry();
+    let result = verify_http_envelope(&headers, &registry, None, false);
+    assert!(result.is_ok(), "verification should pass: {:?}", result.err());
+    assert_eq!(result.unwrap().header.sender, TEST_SENDER);
+}
+
+#[test]
+fn http_verify_fails_on_missing_header() {
+    let registry = make_registry();
+    let headers = HashMap::new();
+    let result = verify_http_envelope(&headers, &registry, None, false);
+    assert_eq!(result.unwrap_err(), VerifyFailReason::MissingHeader);
+}
+
+#[test]
+fn http_verify_fails_on_tampered_envelope() {
+    let (name, value) = sign_http_request(&make_input(), TEST_PRIVATE_KEY, None)
+        .expect("sign should succeed");
+
+    // Tamper: change the sender in the JSON
+    let mut parsed: serde_json::Value = serde_json::from_str(&value).unwrap();
+    parsed["header"]["sender"] = serde_json::json!("attacker.agent");
+    let tampered = serde_json::to_string(&parsed).unwrap();
+
+    let mut headers = HashMap::new();
+    headers.insert(name, tampered);
+
+    // The registry won't know "attacker.agent"
+    let registry = make_registry();
+    let result = verify_http_envelope(&headers, &registry, None, false);
+    assert!(
+        matches!(
+            result.unwrap_err(),
+            VerifyFailReason::UnknownSender(_) | VerifyFailReason::InvalidSignature
+        ),
+        "expected UnknownSender or InvalidSignature"
+    );
+}
+
+// ── Webhook Ed25519 tests ─────────────────────────────────────────────────────
+
+#[test]
+fn webhook_ed25519_sign_verify_roundtrip() {
+    let body = r#"{"event":"order.created","id":42}"#;
+    let (sig, ts) =
+        sign_webhook(body, TEST_PRIVATE_KEY).expect("sign_webhook should succeed");
+
+    let valid = verify_webhook(body, &sig, &ts, TEST_PUBLIC_KEY, None)
+        .expect("verify_webhook should not error");
+    assert!(valid, "webhook signature should verify");
+}
+
+#[test]
+fn webhook_hmac_sign_verify_roundtrip() {
+    let secret = "shared-hmac-secret-for-test";
+    let body = r#"{"event":"payment.captured"}"#;
+
+    let (sig, ts) = sign_webhook_hmac(body, secret).expect("sign_webhook_hmac should succeed");
+    let valid = verify_webhook_hmac(body, &sig, &ts, secret, None)
+        .expect("verify_webhook_hmac should not error");
+    assert!(valid, "HMAC webhook signature should verify");
+}
+
+#[test]
+fn webhook_expired_timestamp_returns_false() {
+    let body = "test-payload";
+    let secret = "any-secret";
+    // Use a timestamp 10 minutes in the past (600_000 ms), default TTL is 300_000 ms
+    let old_ts = {
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+        now - 600_000
+    };
+    let payload = format!("{old_ts}.{body}");
+    let sig = protocol_7h3::sign_canonical_payload_hmac(&payload, secret);
+
+    let valid = verify_webhook_hmac(body, &sig, &old_ts.to_string(), secret, None)
+        .expect("should not error");
+    assert!(!valid, "expired timestamp should return false");
+}
+
+// ── Queue tests ───────────────────────────────────────────────────────────────
+
+#[derive(serde::Serialize, serde::Deserialize, Debug, PartialEq)]
+struct TestTask {
+    action: String,
+    priority: u32,
+}
+
+#[test]
+fn queue_sign_verify_roundtrip() {
+    let task = TestTask {
+        action: "compute".to_string(),
+        priority: 5,
+    };
+
+    let msg = sign_queue_message(
+        &task,
+        TEST_PRIVATE_KEY,
+        "key-1",
+        TEST_SENDER,
+        Some("agent.worker"),
+        None,
+    )
+    .expect("sign_queue_message should succeed");
+
+    let (payload_val, envelope) =
+        verify_queue_message(&msg, TEST_PUBLIC_KEY).expect("verify_queue_message should succeed");
+
+    assert_eq!(envelope.header.sender, TEST_SENDER);
+
+    let recovered: TestTask =
+        serde_json::from_value(payload_val).expect("payload should deserialize");
+    assert_eq!(recovered, task);
+}
+
+#[test]
+fn queue_fails_on_tampered_message() {
+    let task = TestTask {
+        action: "delete-all".to_string(),
+        priority: 99,
+    };
+    let msg = sign_queue_message(
+        &task,
+        TEST_PRIVATE_KEY,
+        "key-1",
+        TEST_SENDER,
+        None,
+        None,
+    )
+    .expect("sign should succeed");
+
+    // Tamper with the payload section
+    let mut parsed: serde_json::Value = serde_json::from_str(&msg).unwrap();
+    parsed["envelope"]["header"]["sender"] = serde_json::json!("evil-agent");
+    let tampered = serde_json::to_string(&parsed).unwrap();
+
+    let result = verify_queue_message(&tampered, TEST_PUBLIC_KEY);
+    assert!(result.is_err(), "tampered message should fail verification");
+}