hecks 3.0.3 → 3.0.5

data/rust/host/src/dispatch.rs

@@ -14,6 +14,61 @@ pub struct Outcome {
     pub accepted: bool,
 }
 
+/// Who a command is dispatched for: the role they state and, when the host knows who they are, the
+/// actor Governance holds assignments for. Both absent is an unidentified caller.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct Caller<'a> {
+    pub role: Option<&'a str>,
+    pub actor_id: Option<&'a str>,
+}
+
+/// The role an unidentified caller is dispatched under when roles are enforced: no command declares
+/// it, so a command that declares any role refuses it.
+pub const ANONYMOUS_ROLE: &str = "Anonymous";
+
+/// What the host does about the role a command declares (`HECKS_ROLE_ENFORCEMENT`).
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Enforcement {
+    /// A caller with no role is unchecked, as before.
+    Off,
+    /// An unidentified or unassigned caller is let through and logged as `would_refuse_role`.
+    Shadow,
+    /// An unidentified or unassigned caller is refused.
+    Enforce,
+}
+
+impl Enforcement {
+    /// Reads `off` (the default), `shadow` or `enforce`; anything else is `Off`.
+    pub fn parse(value: Option<&str>) -> Self {
+        match value.map(|v| v.trim().to_ascii_lowercase()).as_deref() {
+            Some("shadow") => Self::Shadow,
+            Some("enforce") => Self::Enforce,
+            _ => Self::Off,
+        }
+    }
+
+    pub fn from_env() -> Self {
+        static MODE: std::sync::OnceLock<Enforcement> = std::sync::OnceLock::new();
+        *MODE.get_or_init(|| Self::parse(std::env::var("HECKS_ROLE_ENFORCEMENT").ok().as_deref()))
+    }
+
+    /// The caller the kernel is asked to check: an unidentified caller becomes the anonymous role
+    /// unless enforcement is off.
+    pub fn effective<'a>(self, caller: Caller<'a>) -> Caller<'a> {
+        if self != Self::Off && caller.role.is_none() && caller.actor_id.is_none() {
+            return Caller { role: Some(ANONYMOUS_ROLE), actor_id: None };
+        }
+        caller
+    }
+}
+
+/// Whether the kernel refused the command for the caller's role.
+fn refused_for_role(result: &serde_json::Value) -> bool {
+    result.get("refusals").and_then(|r| r.as_array()).is_some_and(|all| {
+        all.iter().any(|r| r.get("kind").and_then(|k| k.as_str()) == Some("Unauthorized"))
+    })
+}
+
 // Distinguishes a module refusal from a kernel failure to run at all.
 #[derive(Debug, PartialEq)]
 enum KernelAnswer {
@@ -80,6 +135,21 @@ pub async fn handle_routed(
     handle(client, wasm_path, verb, routed_invocation(to, facts)?, role, config, invoker).await
 }
 
+/// `handle_routed` for a caller the host can name.
+#[allow(clippy::too_many_arguments)]
+pub async fn handle_routed_as(
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    to: serde_json::Value,
+    facts: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    handle_as(client, wasm_path, verb, routed_invocation(to, facts)?, caller, config, invoker).await
+}
+
 // Facts-only counterpart to `handle_routed`.
 #[allow(clippy::too_many_arguments)]
 pub async fn handle_facts(
@@ -94,6 +164,20 @@ pub async fn handle_facts(
     handle(client, wasm_path, verb, facts_invocation(facts)?, role, config, invoker).await
 }
 
+/// `handle_facts` for a caller the host can name.
+#[allow(clippy::too_many_arguments)]
+pub async fn handle_facts_as(
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    facts: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    handle_as(client, wasm_path, verb, facts_invocation(facts)?, caller, config, invoker).await
+}
+
 // A Mutex, not a bare Arc<Client>: `handle` needs `Client::transaction`,
 // which takes `&mut Client`. Locking also means concurrent callers on
 // this connection can't interleave statements.
@@ -114,6 +198,57 @@ pub async fn handle(
     config: &LineageConfig,
     invoker: &dyn LambdaInvoker,
 ) -> anyhow::Result<Outcome> {
+    handle_as(client, wasm_path, verb, args, Caller { role, actor_id: None }, config, invoker).await
+}
+
+/// Dispatches for a caller, applying `HECKS_ROLE_ENFORCEMENT`: unidentified callers are refused (or,
+/// in shadow, logged as would-be refusals and let through).
+pub async fn handle_as(
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    args: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    handle_with(Enforcement::from_env(), client, wasm_path, verb, args, caller, config, invoker).await
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn handle_with(
+    mode: Enforcement,
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    args: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    let checked = mode.effective(caller);
+    let outcome = run(client, wasm_path, verb, args.clone(), checked, config, invoker).await?;
+    if mode == Enforcement::Shadow && !outcome.accepted && refused_for_role(&outcome.result) {
+        crate::log::error("would_refuse_role", serde_json::json!({
+            "verb": verb, "role": checked.role, "actor_id": checked.actor_id,
+            "refusals": outcome.result.get("refusals"),
+        }));
+        return run(client, wasm_path, verb, args, Caller::default(), config, invoker).await;
+    }
+    Ok(outcome)
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn run(
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    verb: &str,
+    args: serde_json::Value,
+    caller: Caller<'_>,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<Outcome> {
+    let role = caller.role;
     let mut guard = client.lock().await;
     let txn = guard.transaction().await?;
 
@@ -147,10 +282,19 @@ pub async fn handle(
     // carries whatever role it was dispatched with. Built as a mutable
     // step, not inlined into the `json!` literal, so a roleless call
     // still omits the `"role"` key entirely rather than sending null.
+    // A fact the command `needs` is answered here, before the kernel's gates read the arguments and
+    // before the step is journaled, so a replay re-dispatches the recorded answer (ADR 0081).
+    let mut args = args;
+    if let Some(domain_ir) = crate::ir::ir() {
+        crate::needs::fill_needs(domain_ir, verb, &mut args, &crate::needs::ProcessClock);
+    }
     let mut step = serde_json::json!({ "verb": verb, "args": args.clone() });
     if let Some(role) = role {
         step["role"] = serde_json::Value::String(role.to_string());
     }
+    if let Some(actor_id) = caller.actor_id {
+        step["actor_id"] = serde_json::Value::String(actor_id.to_string());
+    }
     // Stamped only on this live step; replayed history already carries
     // its own real timestamp, and re-stamping today's time onto a
     // replay would be wrong, not just redundant.
@@ -179,7 +323,15 @@ pub async fn handle(
         }))
         .collect::<Vec<_>>());
 
-    let input = serde_json::json!({ "seed": seed, "steps": steps, "sagas": sagas_seed }).to_string();
+    let mut input = serde_json::json!({ "seed": seed, "steps": steps, "sagas": sagas_seed });
+    // Lets the kernel answer a reaction's command that needs a fact the same way (ADR 0081).
+    if let Some(domain_ir) = crate::ir::ir() {
+        let table = crate::needs::table(domain_ir);
+        if table.as_object().is_some_and(|t| !t.is_empty()) {
+            input["needs"] = table;
+        }
+    }
+    let input = input.to_string();
     // `wasm_runner::run` is sync, and wasmtime-wasi's sync bridge spins up
     // its own tokio runtime internally — fatal on a thread already
     // driving one. `spawn_blocking` moves it off this async runtime.
@@ -1169,6 +1321,60 @@ pub(crate) mod tests {
         assert_eq!(steps.len(), 1, "only the correctly-authorized registration should be persisted");
     }
 
+    #[test]
+    fn enforcement_reads_off_shadow_and_enforce_and_treats_anything_else_as_off() {
+        assert_eq!(Enforcement::parse(None), Enforcement::Off);
+        assert_eq!(Enforcement::parse(Some("")), Enforcement::Off);
+        assert_eq!(Enforcement::parse(Some("nonsense")), Enforcement::Off);
+        assert_eq!(Enforcement::parse(Some("Shadow")), Enforcement::Shadow);
+        assert_eq!(Enforcement::parse(Some(" enforce ")), Enforcement::Enforce);
+    }
+
+    #[test]
+    fn only_an_unidentified_caller_becomes_anonymous_and_only_when_roles_are_checked() {
+        let nobody = Caller::default();
+        assert_eq!(Enforcement::Off.effective(nobody), nobody);
+        for mode in [Enforcement::Shadow, Enforcement::Enforce] {
+            assert_eq!(mode.effective(nobody).role, Some(ANONYMOUS_ROLE));
+            let stated = Caller { role: Some("Teller"), actor_id: None };
+            assert_eq!(mode.effective(stated), stated, "a stated role is kept");
+            let identified = Caller { role: None, actor_id: Some("u1") };
+            assert_eq!(mode.effective(identified), identified, "an identified caller is kept");
+        }
+    }
+
+    // The unidentified caller is the case the host never refused: no role at all.
+    #[tokio::test]
+    async fn an_unidentified_caller_is_refused_when_enforced_and_let_through_when_off_or_shadowed() {
+        let client = scratch_db("rust_host_dispatch_test_enforce").await;
+        provision_lineage(&*client.lock().await, "Banking", 1, &["Customer"]).await;
+        let config = test_config("Banking", 1);
+        let go = |mode: Enforcement, id: &'static str| {
+            let client = &client;
+            let config = &config;
+            async move {
+                handle_with(mode, client, &wasm_path(), "Banking::Customer.Register", register(id), Caller::default(), config, &lambda_client::NeverInvoker)
+                    .await
+                    .unwrap()
+            }
+        };
+
+        let off = go(Enforcement::Off, "CUST-0021").await;
+        assert!(off.accepted, "off keeps the old behaviour: {:?}", off.result);
+
+        let enforced = go(Enforcement::Enforce, "CUST-0022").await;
+        assert!(!enforced.accepted, "an unidentified caller must be refused: {:?}", enforced.result);
+        assert!(refused_for_role(&enforced.result), "{:?}", enforced.result);
+        let error = enforced.result["refusals"][0]["error"].as_str().unwrap();
+        assert!(error.contains("Branch clerk") && error.contains(ANONYMOUS_ROLE), "{error}");
+
+        let shadowed = go(Enforcement::Shadow, "CUST-0023").await;
+        assert!(shadowed.accepted, "shadow lets the command through: {:?}", shadowed.result);
+
+        let steps = journal::load_steps(&*client.lock().await).await.unwrap();
+        assert_eq!(steps.len(), 2, "the enforced refusal was not persisted; off and shadow were");
+    }
+
     #[tokio::test]
     async fn a_mid_transaction_failure_rolls_back_any_saga_state_already_written() {
         // Deliberately doesn't provision "Transfer": its mutation fails

data/rust/host/src/main.rs

@@ -13,6 +13,7 @@ mod journal;
 mod lambda_client;
 mod log;
 mod mint;
+mod needs;
 mod payments;
 mod presentation;
 mod presentation_write;

data/rust/host/src/needs.rs

@@ -0,0 +1,243 @@
+// Facts a command `needs` (ADR 0081): the host answers them before the kernel reads the arguments,
+// the way the Ruby interpreter does in `decode_arguments`. The command's own IR carries
+// `"needs": [{"fact": "now"}]`; a needed fact the caller left out is filled with the clock's
+// answer, a supplied one is kept. The answer is written into the arguments before they are
+// journaled, so a replay re-dispatches the recorded value rather than asking the clock again.
+
+use serde_json::{json, Value};
+use std::sync::atomic::{AtomicI64, Ordering};
+
+/// What answers the `now` fact: epoch seconds, UTC.
+pub trait Clock {
+    fn now_secs(&self) -> i64;
+}
+
+/// The wall clock.
+pub struct SystemClock;
+
+impl Clock for SystemClock {
+    fn now_secs(&self) -> i64 {
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_secs() as i64)
+            .unwrap_or_default()
+    }
+}
+
+/// A clock that always answers one moment, for tests.
+#[cfg(test)]
+pub struct FixedClock(pub i64);
+
+#[cfg(test)]
+impl Clock for FixedClock {
+    fn now_secs(&self) -> i64 {
+        self.0
+    }
+}
+
+const UNSET: i64 = i64::MIN;
+static OVERRIDE: AtomicI64 = AtomicI64::new(UNSET);
+
+/// Makes the process clock answer `secs` until `clear_fixed_clock`; for tests only.
+#[cfg(test)]
+pub fn set_fixed_clock(secs: i64) {
+    OVERRIDE.store(secs, Ordering::SeqCst);
+}
+
+#[cfg(test)]
+pub fn clear_fixed_clock() {
+    OVERRIDE.store(UNSET, Ordering::SeqCst);
+}
+
+/// The process clock the dispatcher uses: the wall clock unless a test has fixed it.
+pub struct ProcessClock;
+
+impl Clock for ProcessClock {
+    fn now_secs(&self) -> i64 {
+        match OVERRIDE.load(Ordering::SeqCst) {
+            UNSET => SystemClock.now_secs(),
+            fixed => fixed,
+        }
+    }
+}
+
+/// The command's declared needs, each with the type of the attribute of the same name.
+fn declared_needs<'a>(domain_ir: &'a Value, verb: &str) -> Vec<(&'a str, Option<&'a str>)> {
+    let Some((qualified_aggregate, command_name)) = verb.rsplit_once('.') else { return Vec::new() };
+    let aggregate = qualified_aggregate.rsplit("::").next().unwrap_or(qualified_aggregate);
+    let named = |value: &Value, name: &str| value.get("name").and_then(Value::as_str) == Some(name);
+    let list = |value: &'a Value, key: &str| -> Vec<&'a Value> {
+        value.get(key).and_then(Value::as_array).map(|a| a.iter().collect()).unwrap_or_default()
+    };
+    let mut needs = Vec::new();
+    for command in list(domain_ir, "aggregates")
+        .into_iter()
+        .filter(|a| named(a, aggregate))
+        .flat_map(|a| list(a, "commands"))
+        .filter(|c| named(c, command_name))
+    {
+        let attributes = list(command, "attributes");
+        for fact in list(command, "needs").into_iter().filter_map(|n| n.get("fact").and_then(Value::as_str)) {
+            let attribute_type =
+                attributes.iter().find(|a| named(a, fact)).and_then(|a| a.get("type")).and_then(Value::as_str);
+            needs.push((fact, attribute_type));
+        }
+    }
+    needs
+}
+
+/// Every command's needs as the kernel's input `"needs"` reads them: `{ verb: [{fact, type}] }`.
+/// The kernel answers a reaction's command from this (it has no IR of its own), and the same
+/// step's `occurred_at` keeps the answer the same on replay.
+pub fn table(domain_ir: &Value) -> Value {
+    let domain = domain_ir.get("name").and_then(Value::as_str).unwrap_or_default();
+    let mut verbs = serde_json::Map::new();
+    let aggregates = domain_ir.get("aggregates").and_then(Value::as_array).into_iter().flatten();
+    for aggregate in aggregates {
+        let aggregate_name = aggregate.get("name").and_then(Value::as_str).unwrap_or_default();
+        for command in aggregate.get("commands").and_then(Value::as_array).into_iter().flatten() {
+            let command_name = command.get("name").and_then(Value::as_str).unwrap_or_default();
+            let verb = format!("{domain}::{aggregate_name}.{command_name}");
+            let needs: Vec<Value> = declared_needs(domain_ir, &verb)
+                .into_iter()
+                .map(|(fact, attribute_type)| json!({"fact": fact, "type": attribute_type.unwrap_or("")}))
+                .collect();
+            if !needs.is_empty() {
+                verbs.insert(verb, Value::Array(needs));
+            }
+        }
+    }
+    Value::Object(verbs)
+}
+
+/// The facts of a command invocation: the `with` object when the call carries one, else the
+/// flat object itself (the kernel's `CommandInvocation` reads both shapes).
+fn facts_mut(args: &mut Value) -> Option<&mut serde_json::Map<String, Value>> {
+    if args.get("with").is_some_and(Value::is_object) {
+        return args.get_mut("with").and_then(Value::as_object_mut);
+    }
+    args.as_object_mut()
+}
+
+fn answer(fact: &str, attribute_type: Option<&str>, clock: &dyn Clock) -> Option<Value> {
+    match fact {
+        "now" => {
+            let secs = clock.now_secs();
+            Some(if attribute_type == Some("Integer") { json!(secs) } else { json!({ "value": secs }) })
+        }
+        _ => None,
+    }
+}
+
+/// Fills each fact `verb` needs that `args` leaves out, before any gate reads the arguments. A key
+/// the caller supplied (even a null) is kept; a command that needs nothing is untouched.
+pub fn fill_needs(domain_ir: &Value, verb: &str, args: &mut Value, clock: &dyn Clock) {
+    let needs = declared_needs(domain_ir, verb);
+    if needs.is_empty() {
+        return;
+    }
+    let Some(facts) = facts_mut(args) else { return };
+    for (fact, attribute_type) in needs {
+        if facts.contains_key(fact) {
+            continue;
+        }
+        if let Some(value) = answer(fact, attribute_type, clock) {
+            facts.insert(fact.to_string(), value);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const LEASE_IR: &str = include_str!("../../src/generated/lease_clock/ir.json");
+
+    fn lease_ir() -> Value {
+        serde_json::from_str(LEASE_IR).unwrap()
+    }
+
+    // A command whose `now` is an Integer attribute, as QualityControl's are.
+    fn integer_ir() -> Value {
+        json!({"name": "Qc", "aggregates": [{"name": "Check", "commands": [
+            {"name": "Run", "attributes": [{"name": "now", "type": "Integer"}], "needs": [{"fact": "now"}]},
+            {"name": "Plain", "attributes": [{"name": "now", "type": "Integer"}], "needs": []}
+        ]}]})
+    }
+
+    fn first_needing(ir: &Value) -> String {
+        ir["aggregates"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .flat_map(|a| {
+                a["commands"].as_array().unwrap().iter().filter(|c| !c["needs"].as_array().unwrap().is_empty()).map(
+                    move |c| format!("{}::{}.{}", ir["name"].as_str().unwrap(), a["name"].as_str().unwrap(), c["name"].as_str().unwrap()),
+                )
+            })
+            .next()
+            .expect("the lease_clock domain declares a command that needs :now")
+    }
+
+    #[test]
+    fn a_needed_fact_the_caller_left_out_is_filled_from_the_clock() {
+        let ir = lease_ir();
+        let mut args = json!({"with": {"holder": "a"}});
+        fill_needs(&ir, &first_needing(&ir), &mut args, &FixedClock(1_700_000_000));
+        assert_eq!(args["with"]["now"], json!({"value": 1_700_000_000}));
+        assert_eq!(args["with"]["holder"], "a");
+    }
+
+    #[test]
+    fn a_flat_invocation_is_filled_at_its_top_level() {
+        let ir = lease_ir();
+        let mut args = json!({"holder": "a"});
+        fill_needs(&ir, &first_needing(&ir), &mut args, &FixedClock(5));
+        assert_eq!(args["now"], json!({"value": 5}));
+    }
+
+    #[test]
+    fn a_value_the_caller_supplied_is_kept() {
+        let ir = lease_ir();
+        let mut args = json!({"with": {"now": {"value": 42}}});
+        fill_needs(&ir, &first_needing(&ir), &mut args, &FixedClock(7));
+        assert_eq!(args["with"]["now"], json!({"value": 42}));
+    }
+
+    #[test]
+    fn a_command_with_no_needs_is_untouched() {
+        let ir = integer_ir();
+        let mut args = json!({"with": {"x": 1}});
+        fill_needs(&ir, "Qc::Check.Plain", &mut args, &FixedClock(7));
+        assert_eq!(args, json!({"with": {"x": 1}}));
+        let mut unknown = json!({"with": {}});
+        fill_needs(&ir, "Qc::Check.Nope", &mut unknown, &FixedClock(7));
+        assert_eq!(unknown, json!({"with": {}}));
+    }
+
+    #[test]
+    fn an_integer_attribute_gets_a_bare_integer_and_an_instant_a_value_object() {
+        let mut integer = json!({"with": {}});
+        fill_needs(&integer_ir(), "Qc::Check.Run", &mut integer, &FixedClock(9));
+        assert_eq!(integer["with"]["now"], json!(9));
+        let ir = lease_ir();
+        let mut instant = json!({"with": {}});
+        fill_needs(&ir, &first_needing(&ir), &mut instant, &FixedClock(9));
+        assert_eq!(instant["with"]["now"], json!({"value": 9}));
+    }
+
+    #[test]
+    fn the_kernel_table_lists_only_commands_that_need_something() {
+        let table = table(&integer_ir());
+        assert_eq!(table, json!({"Qc::Check.Run": [{"fact": "now", "type": "Integer"}]}));
+        assert_eq!(super::table(&json!({"name": "D"})), json!({}));
+    }
+
+    #[test]
+    fn the_process_clock_answers_a_fixed_moment_and_otherwise_the_wall_clock() {
+        set_fixed_clock(123);
+        assert_eq!(ProcessClock.now_secs(), 123);
+        clear_fixed_clock();
+        assert!(ProcessClock.now_secs() > 1_700_000_000);
+    }
+}

data/rust/host/src/resend.rs

@@ -43,7 +43,7 @@ impl Delivery {
 
 /// How email leaves the host: really, through Resend, or logged and dropped.
 pub enum Mailer {
-    Live { http: reqwest::Client, api_key: String, from: String, base_url: String },
+    Live { http: reqwest::Client, api_key: String, from: String, reply_to: Option<String>, base_url: String },
     Mock,
 }
 
@@ -53,6 +53,7 @@ impl Mailer {
     pub fn from_env() -> Result<Option<Mailer>, String> {
         let var = |name: &str| std::env::var(name).unwrap_or_default();
         Self::configured(&var("RESEND_API_KEY"), &var("RESEND_FROM"), &var("RESEND_MOCK"))
+            .map(|mailer| mailer.map(|mailer| mailer.replying_to(&var("RESEND_REPLY_TO"))))
     }
 
     fn configured(api_key: &str, from: &str, mock: &str) -> Result<Option<Mailer>, String> {
@@ -69,7 +70,19 @@ impl Mailer {
     /// A mailer that posts to `base_url` (Resend's API, or a stand-in in tests).
     pub fn live(api_key: &str, from: &str, base_url: &str) -> Mailer {
         let http = reqwest::Client::builder().timeout(TIMEOUT).build().expect("a reqwest client with a timeout always builds");
-        Mailer::Live { http, api_key: api_key.to_string(), from: from.to_string(), base_url: base_url.to_string() }
+        Mailer::Live { http, api_key: api_key.to_string(), from: from.to_string(), reply_to: None, base_url: base_url.to_string() }
+    }
+
+    /// Sets where replies go (`Reply-To`), when the address people reply to is not the one the mail
+    /// is sent from. Blank leaves replies going to the From address. A mock mailer has no replies.
+    pub fn replying_to(self, reply_to: &str) -> Mailer {
+        match self {
+            Mailer::Live { http, api_key, from, base_url, .. } => {
+                let reply_to = (!reply_to.trim().is_empty()).then(|| reply_to.trim().to_string());
+                Mailer::Live { http, api_key, from, reply_to, base_url }
+            }
+            mock => mock,
+        }
     }
 
     #[cfg(test)]
@@ -80,7 +93,7 @@ impl Mailer {
     pub async fn deliver(&self, email: &Email<'_>) -> Delivery {
         match self {
             Mailer::Mock => mock_deliver(email),
-            Mailer::Live { http, api_key, from, base_url } => live_deliver(http, api_key, from, base_url, email).await,
+            Mailer::Live { http, api_key, from, reply_to, base_url } => live_deliver(http, api_key, from, reply_to.as_deref(), base_url, email).await,
         }
     }
 }
@@ -93,8 +106,11 @@ fn mock_deliver(email: &Email<'_>) -> Delivery {
     Delivery::sent(format!("re_{}", uuid::Uuid::new_v4().simple()))
 }
 
-fn payload(from: &str, email: &Email<'_>) -> Value {
+fn payload(from: &str, reply_to: Option<&str>, email: &Email<'_>) -> Value {
     let mut payload = json!({ "from": from, "to": [email.to], "subject": email.subject });
+    if let Some(reply_to) = reply_to {
+        payload["reply_to"] = json!(reply_to);
+    }
     let content_key = if email.body.trim_start().starts_with('<') { "html" } else { "text" };
     payload[content_key] = json!(email.body);
     if let Some(url) = email.unsubscribe_url {
@@ -113,8 +129,8 @@ fn retry_delay(response: &reqwest::Response) -> Duration {
     Duration::from_secs(secs.min(MAX_RETRY_SECS))
 }
 
-async fn live_deliver(http: &reqwest::Client, api_key: &str, from: &str, base_url: &str, email: &Email<'_>) -> Delivery {
-    let body = payload(from, email);
+async fn live_deliver(http: &reqwest::Client, api_key: &str, from: &str, reply_to: Option<&str>, base_url: &str, email: &Email<'_>) -> Delivery {
+    let body = payload(from, reply_to, email);
     for attempt in 1..=MAX_ATTEMPTS {
         let response = match http.post(format!("{base_url}/emails")).bearer_auth(api_key).json(&body).send().await {
             Ok(r) => r,
@@ -225,19 +241,45 @@ mod tests {
 
     #[test]
     fn an_html_body_goes_as_html_and_a_plain_one_as_text() {
-        assert!(payload("f", &email("a@b.com", "  <p>hi</p>")).get("html").is_some());
-        let plain = payload("f", &email("a@b.com", "just a link"));
+        assert!(payload("f", None, &email("a@b.com", "  <p>hi</p>")).get("html").is_some());
+        let plain = payload("f", None, &email("a@b.com", "just a link"));
         assert!(plain.get("text").is_some() && plain.get("html").is_none());
     }
 
     #[test]
     fn the_unsubscribe_url_rides_as_a_list_unsubscribe_header() {
-        let with = payload("f", &email("a@b.com", "x"));
+        let with = payload("f", None, &email("a@b.com", "x"));
         assert_eq!(with["headers"]["List-Unsubscribe"], "<https://example.com/newsletter-unsubscribed.html?email=a%40b.com>");
-        let without = payload("f", &Email { to: "a@b.com", subject: "s", body: "x", unsubscribe_url: None });
+        let without = payload("f", None, &Email { to: "a@b.com", subject: "s", body: "x", unsubscribe_url: None });
         assert!(without.get("headers").is_none());
     }
 
+    #[test]
+    fn a_reply_to_address_rides_in_the_payload_and_is_absent_without_one() {
+        let with = payload("f", Some("lifeadelics@gmail.com"), &email("a@b.com", "x"));
+        assert_eq!(with["reply_to"], "lifeadelics@gmail.com");
+        assert!(payload("f", None, &email("a@b.com", "x")).get("reply_to").is_none());
+    }
+
+    #[test]
+    fn replying_to_trims_the_address_and_a_blank_one_sets_none() {
+        let set = Mailer::live("re_x", "n@mail.example.com", "http://x").replying_to("  me@example.com ");
+        assert!(matches!(&set, Mailer::Live { reply_to: Some(r), .. } if r == "me@example.com"));
+        let blank = Mailer::live("re_x", "n@mail.example.com", "http://x").replying_to("   ");
+        assert!(matches!(&blank, Mailer::Live { reply_to: None, .. }));
+        assert!(Mailer::Mock.replying_to("me@example.com").is_mock(), "a mock mailer has no replies");
+    }
+
+    #[tokio::test]
+    async fn a_live_send_carries_the_reply_to_address_to_resend() {
+        let fake = FakeResend::start(vec![("200 OK", "", r#"{"id":"em_9"}"#)]);
+        let mailer = Mailer::live("re_x", "News <n@mail.example.com>", &fake.base).replying_to("lifeadelics@gmail.com");
+
+        mailer.deliver(&email("a@b.com", "x")).await;
+
+        assert!(fake.requests()[0].contains(r#""reply_to":"lifeadelics@gmail.com""#), "{}", fake.requests()[0]);
+    }
+
     #[test]
     fn the_mock_logs_instead_of_sending_and_bounces_the_test_address() {
         let sent = mock_deliver(&email("a@b.com", "x"));

data/rust/host/src/server.rs

@@ -53,25 +53,29 @@ pub async fn dispatch_body(
         .ok_or("event missing \"verb\"")?
         .to_string();
     let role = body.get("role").and_then(|v| v.as_str()).map(|s| s.to_string());
+    // Who the caller is, for Governance. Honored only where the internal protocol is: from this
+    // host's own peers (`trusts_internal_dispatch`), never from a public caller.
+    let actor_id = body.get("actor_id").and_then(|v| v.as_str()).map(|s| s.to_string());
+    let caller = dispatch::Caller { role: role.as_deref(), actor_id: actor_id.as_deref() };
 
     let outcome = if let Some(to) = body.get("to").cloned() {
         if body.get("args").is_some() {
             return Err("cannot combine to/with with legacy args".into());
         }
         let facts = body.get("with").cloned().unwrap_or_else(|| serde_json::json!({}));
-        dispatch::handle_routed(client, wasm_path, &verb, to, facts, role.as_deref(), config, invoker)
+        dispatch::handle_routed_as(client, wasm_path, &verb, to, facts, caller, config, invoker)
             .await
             .map_err(|e| format!("{e:#}"))?
     } else if let Some(facts) = body.get("with").cloned() {
         if body.get("args").is_some() {
             return Err("cannot combine \"with\" with legacy args".into());
         }
-        dispatch::handle_facts(client, wasm_path, &verb, facts, role.as_deref(), config, invoker)
+        dispatch::handle_facts_as(client, wasm_path, &verb, facts, caller, config, invoker)
             .await
             .map_err(|e| format!("{e:#}"))?
     } else {
         let args = body.get("args").cloned().unwrap_or_else(|| serde_json::json!({}));
-        dispatch::handle(client, wasm_path, &verb, args, role.as_deref(), config, invoker)
+        dispatch::handle_as(client, wasm_path, &verb, args, caller, config, invoker)
             .await
             .map_err(|e| format!("{e:#}"))?
     };