Skip to main content

khive_runtime/
params.rs

1//! Shared deserialization of a verb's JSON parameters.
2//!
3//! Every pack that decodes its parameters into a typed struct reports a malformed call the same
4//! way, so the text a caller sees for a bad argument does not depend on which pack handled it.
5
6use serde::de::DeserializeOwned;
7use serde_json::Value;
8
9use crate::secret_gate::{mask_for_redaction_surface, RedactionSurface};
10use crate::{ParamDef, RuntimeError};
11
12/// Largest magnitude at which every integer has its own `f64` (2^53).
13const EXACT_FLOAT_INTEGER_LIMIT: f64 = 9_007_199_254_740_992.0;
14
15/// Rewrite each top-level argument that `defs` declares `integer` and that arrives as a
16/// whole-number float (`5.0`) to that integer, so a client that writes every JSON number with a
17/// decimal point decodes the same as one that does not. A fractional, non-finite or inexact float
18/// stays as sent and the decoder still refuses it; nested values and other types are untouched.
19pub fn integer_params_from_whole_floats(params: &mut Value, defs: &[ParamDef]) {
20    let Value::Object(map) = params else {
21        return;
22    };
23    for def in defs.iter().filter(|def| def.param_type == "integer") {
24        if let Some(value) = map.get_mut(def.name) {
25            if let Some(integer) = whole_float_as_integer(value) {
26                *value = integer;
27            }
28        }
29    }
30}
31
32fn whole_float_as_integer(value: &Value) -> Option<Value> {
33    let Value::Number(number) = value else {
34        return None;
35    };
36    if number.is_i64() || number.is_u64() {
37        return None;
38    }
39    let float = number.as_f64()?;
40    if !float.is_finite() || float.fract() != 0.0 || float.abs() > EXACT_FLOAT_INTEGER_LIMIT {
41        return None;
42    }
43    // The bound above makes both casts exact; `-0.0` takes the non-negative arm and becomes 0.
44    Some(if float >= 0.0 {
45        Value::from(float as u64)
46    } else {
47        Value::from(float as i64)
48    })
49}
50
51/// Deserialize a verb's JSON `params` into `T`.
52///
53/// A failure becomes [`RuntimeError::InvalidInput`] whose text is `bad params: ` followed by the
54/// message serde reports with recognized secrets masked, for example a missing required field
55/// or a field rejected by `deny_unknown_fields`. Ordinary diagnostics remain unchanged.
56pub fn deser_params<T: DeserializeOwned>(params: Value) -> Result<T, RuntimeError> {
57    serde_json::from_value(params).map_err(|e| {
58        RuntimeError::InvalidInput(format!(
59            "bad params: {}",
60            mask_for_redaction_surface(RedactionSurface::GateProbe, &e.to_string())
61        ))
62    })
63}
64
65#[cfg(test)]
66mod tests {
67    use serde::Deserialize;
68    use serde_json::json;
69
70    use crate::{deser_params, RuntimeError};
71
72    #[derive(Debug, Deserialize, PartialEq)]
73    #[serde(deny_unknown_fields)]
74    struct Sample {
75        name: String,
76        #[serde(default)]
77        count: u32,
78    }
79
80    /// Ordinary serde diagnostics must still pass through byte for byte.
81    fn serde_message(params: &serde_json::Value) -> String {
82        serde_json::from_value::<Sample>(params.clone())
83            .expect_err("these params must not deserialize")
84            .to_string()
85    }
86
87    #[test]
88    fn missing_required_field_gives_bad_params_invalid_input() {
89        let params = json!({"count": 3});
90        let want = serde_message(&params);
91        assert!(want.contains("missing field `name`"), "{want}");
92
93        let err = deser_params::<Sample>(params).unwrap_err();
94        let RuntimeError::InvalidInput(message) = err else {
95            panic!("expected InvalidInput, got {err:?}");
96        };
97        assert!(message.starts_with("bad params: "), "{message}");
98        assert_eq!(message, format!("bad params: {want}"));
99    }
100
101    #[test]
102    fn unknown_field_under_deny_unknown_fields_gives_bad_params_invalid_input() {
103        let params = json!({"name": "alpha", "extra": true});
104        let want = serde_message(&params);
105        assert!(want.contains("unknown field `extra`"), "{want}");
106
107        let err = deser_params::<Sample>(params).unwrap_err();
108        let RuntimeError::InvalidInput(message) = err else {
109            panic!("expected InvalidInput, got {err:?}");
110        };
111        assert!(message.starts_with("bad params: "), "{message}");
112        assert_eq!(message, format!("bad params: {want}"));
113    }
114
115    #[test]
116    fn valid_params_deserialize_into_the_requested_type() {
117        let params = json!({"name": "alpha", "count": 3});
118        let parsed: Sample = deser_params(params).unwrap();
119        let expected = Sample {
120            name: "alpha".to_string(),
121            count: 3,
122        };
123        assert_eq!(parsed, expected);
124
125        let params = json!({"name": "beta"});
126        let defaulted: Sample = deser_params(params).unwrap();
127        let expected_default = Sample {
128            name: "beta".to_string(),
129            count: 0,
130        };
131        assert_eq!(defaulted, expected_default);
132    }
133
134    fn assert_masked_decode_failure<T: serde::de::DeserializeOwned + std::fmt::Debug>(
135        params: serde_json::Value,
136        raw: &str,
137    ) {
138        let original = serde_json::from_value::<T>(params.clone())
139            .unwrap_err()
140            .to_string();
141        assert!(
142            original.contains(raw),
143            "fixture must exercise an echoed operand"
144        );
145        let RuntimeError::InvalidInput(message) = deser_params::<T>(params).unwrap_err() else {
146            panic!("parameter refusal changed its error variant");
147        };
148        if raw.starts_with("sk-proj-") {
149            assert!(
150                !message.contains(raw),
151                "decoder exposed a recognized credential"
152            );
153            assert!(message.contains("***MASKED***"), "decoder omitted the mask");
154        }
155        assert_eq!(
156            message,
157            format!(
158                "bad params: {}",
159                crate::secret_gate::mask_for_redaction_surface(
160                    crate::secret_gate::RedactionSurface::GateProbe,
161                    &original
162                )
163            )
164        );
165    }
166
167    fn integer_defs() -> [crate::ParamDef; 3] {
168        let def = |name, param_type| crate::ParamDef {
169            name,
170            param_type,
171            required: false,
172            description: "",
173            resolution_mode: crate::IdResolutionMode::NotApplicable,
174        };
175        [
176            def("count", "integer"),
177            def("offset", "integer"),
178            def("weight", "number"),
179        ]
180    }
181
182    #[test]
183    fn a_whole_float_for_an_integer_param_decodes_as_that_integer() {
184        let mut params = json!({"name": "alpha", "count": 5.0});
185        super::integer_params_from_whole_floats(&mut params, &integer_defs());
186        assert_eq!(params, json!({"name": "alpha", "count": 5}));
187        let parsed: Sample = deser_params(params).unwrap();
188        assert_eq!(parsed.count, 5);
189    }
190
191    #[test]
192    fn a_fractional_float_for_an_integer_param_is_still_refused() {
193        let mut params = json!({"name": "alpha", "count": 5.5});
194        super::integer_params_from_whole_floats(&mut params, &integer_defs());
195        assert_eq!(params, json!({"name": "alpha", "count": 5.5}));
196        let RuntimeError::InvalidInput(message) = deser_params::<Sample>(params).unwrap_err()
197        else {
198            panic!("expected InvalidInput");
199        };
200        assert!(
201            message.contains("floating point") && message.contains("5.5"),
202            "{message}"
203        );
204    }
205
206    #[test]
207    fn only_exact_whole_floats_of_declared_integer_params_change() {
208        let mut params = json!({
209            "count": -3.0,
210            "offset": -0.0,
211            "weight": 2.0,
212            "undeclared": 4.0,
213            "nested": {"count": 6.0},
214            "list": [7.0],
215        });
216        super::integer_params_from_whole_floats(&mut params, &integer_defs());
217        assert_eq!(
218            params,
219            json!({
220                "count": -3,
221                "offset": 0,
222                "weight": 2.0,
223                "undeclared": 4.0,
224                "nested": {"count": 6.0},
225                "list": [7.0],
226            })
227        );
228        assert!(params["offset"].is_u64(), "{params}");
229
230        for inexact in [9_007_199_254_740_994.0_f64, 1e300, -1e300] {
231            let mut params = json!({ "count": inexact });
232            super::integer_params_from_whole_floats(&mut params, &integer_defs());
233            assert!(
234                params["count"].is_f64(),
235                "{inexact} must stay a float: {params}"
236            );
237        }
238        let mut params = json!({"count": 9_007_199_254_740_992.0_f64});
239        super::integer_params_from_whole_floats(&mut params, &integer_defs());
240        assert_eq!(params["count"], json!(9_007_199_254_740_992_u64));
241
242        let mut integers = json!({"count": 5, "offset": -2});
243        super::integer_params_from_whole_floats(&mut integers, &integer_defs());
244        assert_eq!(integers, json!({"count": 5, "offset": -2}));
245
246        let mut not_an_object = json!([5.0]);
247        super::integer_params_from_whole_floats(&mut not_an_object, &integer_defs());
248        assert_eq!(not_an_object, json!([5.0]));
249    }
250
251    #[test]
252    fn wrong_type_diagnostics_mask_recognized_credentials() {
253        for raw in ["bogus".to_string(), format!("sk-proj-{}", "A".repeat(80))] {
254            assert_masked_decode_failure::<Sample>(json!({"name":"alpha", "count":raw}), &raw);
255        }
256    }
257
258    #[test]
259    fn unknown_field_diagnostics_mask_recognized_credentials() {
260        for raw in ["extra".to_string(), format!("sk-proj-{}", "A".repeat(80))] {
261            let mut params = json!({"name":"alpha"});
262            params
263                .as_object_mut()
264                .unwrap()
265                .insert(raw.clone(), json!(true));
266            assert_masked_decode_failure::<Sample>(params, &raw);
267        }
268    }
269
270    #[test]
271    fn nested_enum_diagnostics_mask_recognized_credentials() {
272        #[derive(Debug, Deserialize, PartialEq)]
273        enum Mode {
274            Read,
275            Write,
276        }
277        #[derive(Debug, Deserialize, PartialEq)]
278        struct Nested {
279            modes: Vec<Mode>,
280        }
281        for raw in ["bogus".to_string(), format!("sk-proj-{}", "A".repeat(80))] {
282            assert_masked_decode_failure::<Nested>(json!({"modes":[raw]}), &raw);
283        }
284        assert_eq!(
285            deser_params::<Nested>(json!({"modes":["Read", "Write"]})).unwrap(),
286            Nested {
287                modes: vec![Mode::Read, Mode::Write]
288            }
289        );
290    }
291}