hecks 3.6.0 → 3.9.0

data/qa/settings.yml

@@ -22,6 +22,7 @@ adversarial_fraction: 0.3
 guided_generation: true
 corpus_splice_probability: 0.0
 favor_rare_verbs: 3
+runtime_coverage_feedback: false
 self_consistency_checks: true
 shrink_budget: 200
 

data/rust/codegen/src/fielded.rs

@@ -30,7 +30,7 @@ pub fn emit_fielded_flat(exemplar: &Exemplar, struct_name: &str, attributes: &[J
             let scalar = scalar.unwrap();
             Some(exemplar.render(
                 "fielded_arm_optional_scalar",
-                &[("\"tmpl_field\"", naming::ruby_inspect_string(&key)), ("tmpl_ident", ident.clone()), ("tmpl_value_expr_placeholder(v)", naming::scalar_to_value(scalar, "v").unwrap())],
+                &[("\"tmpl_field\"", naming::ruby_inspect_string(&key)), ("tmpl_ident", ident.clone()), ("tmpl_value_expr_placeholder(v)", naming::scalar_to_value(scalar, &naming::deref_scalar(scalar, "v")).unwrap())],
             ))
         } else if optional {
             if is_fielded_nested(crate::attr::type_name(attr), value_objects_by_name) {
@@ -97,7 +97,7 @@ pub fn emit_fielded_record(exemplar: &Exemplar, aggregate: &Json, value_objects_
         } else if let Some(scalar) = scalar {
             Some(exemplar.render(
                 "fielded_arm_optional_scalar",
-                &[("\"tmpl_field\"", naming::ruby_inspect_string(&key)), ("tmpl_ident", ident.clone()), ("tmpl_value_expr_placeholder(v)", naming::scalar_to_value(scalar, "v").unwrap())],
+                &[("\"tmpl_field\"", naming::ruby_inspect_string(&key)), ("tmpl_ident", ident.clone()), ("tmpl_value_expr_placeholder(v)", naming::scalar_to_value(scalar, &naming::deref_scalar(scalar, "v")).unwrap())],
             ))
         } else if is_fielded_nested(crate::attr::type_name(attr), value_objects_by_name) {
             Some(exemplar.render("fielded_arm_optional_nested", &[("\"tmpl_field\"", naming::ruby_inspect_string(&key)), ("tmpl_ident", ident)]))
@@ -184,7 +184,7 @@ fn items_arms(exemplar: &Exemplar, attributes: &[Json], value_objects_by_name: &
         let shape = format!("fielded_items_arm_list_{}{}", if optional(attr) { "optional_" } else { "" }, if scalar.is_some() { "scalar" } else { "nested" });
         let mut subs: Vec<(&str, String)> = vec![("\"tmpl_field\"", naming::ruby_inspect_string(&key)), ("tmpl_ident", ident)];
         if let Some(scalar) = scalar {
-            subs.push(("tmpl_value_expr_placeholder(v)", naming::scalar_to_value(scalar, "v").unwrap()));
+            subs.push(("tmpl_value_expr_placeholder(v)", naming::scalar_to_value(scalar, &naming::deref_scalar(scalar, "v")).unwrap()));
         }
         arms.push(format!("            {}", exemplar.render(&shape, &subs)));
     }

data/rust/codegen/src/json_codec.rs

@@ -130,7 +130,7 @@ pub fn list_element_from_json_mapper(struct_name: &str, key: &str, attr: &Json,
 /// Inverse of `list_element_from_json_mapper`: scalar elements have no `.to_json()` method.
 pub fn list_element_to_json_expr(attr: &Json) -> String {
     match naming::effective_scalar_type(crate::attr::type_name(attr)) {
-        Some(scalar) => scalar_to_json_expr(scalar, "x"),
+        Some(scalar) => scalar_to_json_expr(scalar, &naming::deref_scalar(scalar, "x")),
         None => "x.to_json()".to_string(),
     }
 }
@@ -392,7 +392,7 @@ pub fn emit_to_json_flat(exemplar: &Exemplar, struct_name: &str, attributes: &[J
             } else if list {
                 format!("crate::kernel::Json::Array(self.{ident}.iter().map(|x| {}).collect())", elem_to_json.as_deref().unwrap())
             } else if field_optional && scalar.is_some() {
-                format!("self.{ident}.as_ref().map(|v| {}).unwrap_or(crate::kernel::Json::Null)", scalar_to_json_expr(scalar.unwrap(), "v"))
+                format!("self.{ident}.as_ref().map(|v| {}).unwrap_or(crate::kernel::Json::Null)", scalar_to_json_expr(scalar.unwrap(), &naming::deref_scalar(scalar.unwrap(), "v")))
             } else if field_optional {
                 format!("self.{ident}.as_ref().map(|v| v.to_json()).unwrap_or(crate::kernel::Json::Null)")
             } else if let Some(scalar) = scalar {

data/rust/codegen/src/naming.rs

@@ -248,6 +248,16 @@ pub fn screaming_snake(name: &str) -> String {
     out.to_uppercase()
 }
 
+/// The expression for a scalar reached through a reference (`v` in `as_ref().map(|v| ..)`, `x` in
+/// `iter().map(|x| ..)`): the copy types are dereferenced, since `Value::Int(v)` takes an `i64`, not an
+/// `&i64`; a `String` is left to the `.clone()` the scalar helpers already apply.
+pub fn deref_scalar(type_name: &str, ident: &str) -> String {
+    match type_name {
+        "Integer" | "Float" | "TrueClass" | "FalseClass" => format!("*{ident}"),
+        _ => ident.to_string(),
+    }
+}
+
 pub fn scalar_to_value(type_name: &str, rust_expr: &str) -> Option<String> {
     match type_name {
         "String" => Some(format!("Value::Str({rust_expr}.clone())")),
@@ -316,6 +326,16 @@ pub fn ruby_inspect_string(s: &str) -> String {
 mod tests {
     use super::*;
 
+    #[test]
+    fn a_scalar_reached_through_a_reference_is_dereferenced_when_it_is_a_copy_type() {
+        // `self.level.as_ref().map(|v| Field::Value(Value::Int(v)))` does not compile: `v` is `&i64`.
+        assert_eq!(scalar_to_value("Integer", &deref_scalar("Integer", "v")).as_deref(), Some("Value::Int(*v)"));
+        assert_eq!(scalar_to_value("Float", &deref_scalar("Float", "v")).as_deref(), Some("Value::Float(*v)"));
+        assert_eq!(scalar_to_value("TrueClass", &deref_scalar("TrueClass", "v")).as_deref(), Some("Value::Bool(*v)"));
+        // A String is cloned, so the reference is left alone.
+        assert_eq!(scalar_to_value("String", &deref_scalar("String", "v")).as_deref(), Some("Value::Str(v.clone())"));
+    }
+
     #[test]
     fn refuses_an_aggregate_whose_module_name_is_a_rust_keyword() {
         let refusal = reserved_name_refusal("shop", "shop", &["Pizza", "Match", "Type"]).expect("refused");

data/rust/host/Cargo.toml

@@ -6,6 +6,10 @@ edition = "2021"
 # Empty table: makes this crate its own workspace root instead of joining `rust`'s.
 [workspace]
 
+[lib]
+name = "rust_host"
+path = "src/lib.rs"
+
 [[bin]]
 name = "bootstrap"
 path = "src/main.rs"
@@ -61,6 +65,6 @@ async-trait = "0.1.92"
 debug = 0
 
 # The tests compile wasm modules through wasmtime's Cranelift, which is far slower unoptimized.
-# Optimize dependencies only; the host crate itself stays at opt-level 0.
-[profile.dev.package."*"]
+# Optimize dependencies only, and only for cargo test; the host crate and cargo build stay at opt-level 0.
+[profile.test.package."*"]
 opt-level = 2

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.6.0
+3.9.0

data/rust/host/src/api.rs

@@ -479,8 +479,13 @@ fn apply_identity(presentation: &Value, aggregate: &Value, args: &mut Value, exi
         }
         Some("sequence") => {
             let prefix = rule.get("prefix").and_then(|v| v.as_str()).unwrap_or("");
-            let pad = rule.get("pad").and_then(|v| v.as_u64()).unwrap_or(3) as usize;
-            Some(format!("{prefix}{:0>pad$}", existing + 1))
+            let pad = rule.get("pad").and_then(|v| v.as_u64()).unwrap_or(3);
+            // `pad` rides in as free-form config JSON, and a width like 10^15 would have the
+            // formatter allocate that many bytes: refuse it rather than abort the process.
+            if pad > MAX_IDENTITY_PAD {
+                return Err(internal_error(&format!("the identity pad {pad} for {name} is wider than the {MAX_IDENTITY_PAD} this host will mint")));
+            }
+            Some(format!("{prefix}{:0>pad$}", existing + 1, pad = pad as usize))
         }
         // `port` delegates to a Ruby adapter this host has no runtime for
         // (ADR 0007); refusing names the real reason rather than
@@ -499,6 +504,9 @@ fn apply_identity(presentation: &Value, aggregate: &Value, args: &mut Value, exi
     Ok(())
 }
 
+/// The widest zero-padded `sequence` identity `apply_identity` will mint.
+const MAX_IDENTITY_PAD: u64 = 64;
+
 /// The wire key an identity value has to be wrapped in — whatever the
 /// target value object's own single attribute is actually called. This
 /// domain always spells it "value"; nothing here assumes that.
@@ -727,10 +735,21 @@ fn compare_sort_keys(left: Option<&Value>, right: Option<&Value>, descending: bo
     }
 }
 
+/// Numbers, then strings, then anything else (all equal, so the id breaks the tie). A column can
+/// hold mixed types, and `sort_by` panics on a comparison that is not a total order: comparing a
+/// number with a string as `""` made `5`, `""` and `3` each equal to a neighbour but not to each other.
 fn compare_values(left: &Value, right: &Value) -> Ordering {
-    match (left.as_f64(), right.as_f64()) {
-        (Some(left), Some(right)) => left.partial_cmp(&right).unwrap_or(Ordering::Equal),
-        _ => left.as_str().unwrap_or("").cmp(right.as_str().unwrap_or("")),
+    fn rank(value: &Value) -> u8 {
+        match value {
+            Value::Number(_) => 0,
+            Value::String(_) => 1,
+            _ => 2,
+        }
+    }
+    match (left, right) {
+        (Value::Number(a), Value::Number(b)) => a.as_f64().unwrap_or(0.0).total_cmp(&b.as_f64().unwrap_or(0.0)),
+        (Value::String(a), Value::String(b)) => a.cmp(b),
+        _ => rank(left).cmp(&rank(right)),
     }
 }
 
@@ -1594,3 +1613,7 @@ mod tests {
         );
     }
 }
+
+#[cfg(test)]
+#[path = "boundary_fuzz/api.rs"]
+mod boundary_fuzz;

data/rust/host/src/auth.rs

@@ -882,13 +882,19 @@ fn sign(secret: &str, payload: &str) -> String {
 
 fn verify_sig(secret: &str, token: &str) -> Option<String> {
     let (payload, sig) = token.rsplit_once('.')?;
-    if sign(secret, payload) == sig {
+    if constant_time_eq(sign(secret, payload).as_bytes(), sig.as_bytes()) {
         Some(payload.to_string())
     } else {
         None
     }
 }
 
+/// Compares two signatures without stopping at the first differing byte, so how long a forged
+/// cookie takes to refuse does not tell the caller how many leading characters were right.
+fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
+    a.len() == b.len() && a.iter().zip(b).fold(0u8, |diff, (x, y)| diff | (x ^ y)) == 0
+}
+
 fn hex_encode(bytes: &[u8]) -> String {
     bytes.iter().map(|b| format!("{b:02x}")).collect()
 }
@@ -1341,3 +1347,7 @@ mod tests {
         assert_eq!(state["role"]["value"], "Admin", "a lower ordinal must never move the snapshot backward");
     }
 }
+
+#[cfg(test)]
+#[path = "boundary_fuzz/auth.rs"]
+mod boundary_fuzz;

data/rust/host/src/boundary_fuzz/api.rs

@@ -0,0 +1,260 @@
+//! Seeded fuzz of the `/api` request-shaping helpers that run on caller-controlled input before
+//! anything reaches the database: body parsing, identity minting, preconditions, sorting and
+//! query-argument shaping. Each must refuse bad input with a structured answer, never panic, and
+//! leave the arguments it was given untouched when it refuses.
+
+use super::*;
+use crate::fuzz_support::*;
+
+fn envelope_is_structured(response: &Value) {
+    let status = response["statusCode"].as_u64().expect("a refusal carries its status");
+    assert!((400..600).contains(&status), "a refusal is a 4xx/5xx, got {status}");
+    assert_eq!(response["headers"]["content-type"], "application/json");
+    let body: Value = serde_json::from_str(response["body"].as_str().expect("a JSON body")).expect("the body is JSON");
+    assert!(body["error"].is_string() && body["message"].is_string(), "the refusal names itself: {body}");
+}
+
+fn client_aggregate() -> Value {
+    json!({
+        "name": "Client",
+        "identified_by": ["reference.value"],
+        "attributes": [
+            {"name": "reference", "type": "ClientReference", "list": false, "optional": false},
+            {"name": "name", "type": "ClientName", "list": false, "optional": false},
+            {"name": "owner", "type": "Reference<Member>", "list": false, "optional": true},
+            {"name": "status", "type": "String", "list": false, "optional": true}
+        ],
+        "value_objects": [
+            {"name": "ClientReference", "attributes": [{"name": "value", "type": "String"}], "closed_set": false, "members": []},
+            {"name": "ClientName", "attributes": [{"name": "value", "type": "String"}], "closed_set": false, "members": []}
+        ],
+        "entities": [], "commands": [], "queries": [], "lifecycle": {"field": "status"}
+    })
+}
+
+#[test]
+fn parsed_body_refuses_everything_that_is_not_an_object_with_a_structured_400() {
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed);
+            for _ in 0..50 {
+                let text = match rng.below(4) {
+                    0 => random_text(&mut rng),
+                    1 => {
+                        let valid = random_value(&mut rng, 0).to_string();
+                        mutate_text(&mut rng, &valid)
+                    }
+                    2 => random_value(&mut rng, 0).to_string(),
+                    _ => format!("{}{}", " \t\n".repeat(rng.below(3)), random_value(&mut rng, 1)),
+                };
+                match parsed_body(&text) {
+                    Ok(body) => {
+                        assert!(body.is_object(), "seed {seed}: {text:?} parsed to a non-object");
+                        assert!(text.trim().is_empty() || serde_json::from_str::<Value>(&text).is_ok(), "seed {seed}: {text:?} is not JSON yet was accepted");
+                    }
+                    Err(refusal) => {
+                        assert_eq!(refusal["statusCode"], 400, "seed {seed}: {text:?}");
+                        envelope_is_structured(&refusal);
+                    }
+                }
+            }
+        });
+    }
+}
+
+#[test]
+fn parsed_body_survives_depth_width_and_size() {
+    guarded("depth and size", || {
+        for text in [
+            "[".repeat(1_000_000),
+            format!("{}1{}", "[".repeat(100_000), "]".repeat(100_000)),
+            format!("{}1{}", "{\"a\":".repeat(100_000), "}".repeat(100_000)),
+            format!("[{}]", vec!["1"; 500_000].join(",")),
+            format!("{{\"a\":\"{}\"}}", "x".repeat(16 * 1024 * 1024)),
+        ] {
+            let _ = parsed_body(&text);
+        }
+        for text in ["[]", "1", "\"s\"", "null", "true", "{", "{\"a\":1}{}", "{} {}", "\u{feff}{}", "{\"a\":NaN}", "{\"a\":1e999}"] {
+            if let Err(refusal) = parsed_body(text) {
+                assert_eq!(refusal["statusCode"], 400, "{text:?}");
+            }
+        }
+        assert_eq!(parsed_body("   ").unwrap(), json!({}));
+        assert!(parsed_body("{\"a\":1,\"a\":2}").unwrap().is_object());
+    });
+}
+
+#[test]
+fn slugify_always_answers_a_clean_non_empty_slug() {
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed);
+            for _ in 0..100 {
+                let text = random_text(&mut rng);
+                let slug = slugify(&text);
+                assert!(!slug.is_empty(), "seed {seed}: {text:?} slugged to nothing");
+                assert!(slug.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'), "seed {seed}: {text:?} -> {slug:?}");
+                assert!(!slug.starts_with('-') && !slug.ends_with('-') && !slug.contains("--"), "seed {seed}: {text:?} -> {slug:?}");
+            }
+        });
+    }
+}
+
+#[test]
+fn identity_minting_survives_any_rule_and_leaves_args_alone_when_it_refuses() {
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed ^ 0x1D);
+            let aggregate = client_aggregate();
+            for _ in 0..50 {
+                let mut rule = serde_json::Map::new();
+                for key in ["field", "strategy", "source", "prefix", "pad"] {
+                    if rng.chance(5) {
+                        continue;
+                    }
+                    let value = match key {
+                        "field" if rng.chance(2) => json!(*rng.pick(&["reference", "name", "owner", "status", "missing", ""])),
+                        "strategy" if rng.chance(2) => json!(*rng.pick(&["slug", "sequence", "port", "nope", ""])),
+                        "source" if rng.chance(2) => json!(*rng.pick(&["name", "reference", "owner", "missing", ""])),
+                        "pad" if rng.chance(2) => json!(*rng.pick(&[0u64, 1, 3, 64, 65, 1_000, 1_000_000, 1u64 << 40, 1u64 << 62, u64::MAX])),
+                        _ => random_value(&mut rng, 2),
+                    };
+                    rule.insert(key.to_string(), value);
+                }
+                let presentation = json!({"collections": {"Client": {"identity": Value::Object(rule)}}});
+                let mut args = random_value(&mut rng, 0);
+                if rng.chance(2) {
+                    args = json!({"name": random_value(&mut rng, 2)});
+                }
+                let before = args.clone();
+                let existing = *rng.pick(&[0usize, 1, 41, 999_999, usize::MAX - 1]);
+                match apply_identity(&presentation, &aggregate, &mut args, existing) {
+                    Ok(()) => {}
+                    Err(refusal) => {
+                        envelope_is_structured(&refusal);
+                        assert_eq!(args, before, "seed {seed}: a refused identity must not have touched the args");
+                    }
+                }
+            }
+        });
+    }
+}
+
+#[test]
+fn an_absurd_sequence_pad_is_refused_rather_than_allocating_it() {
+    let aggregate = client_aggregate();
+    for pad in [65u64, 1_000_000, 1 << 40, u64::MAX] {
+        let presentation = json!({"collections": {"Client": {"identity": {"field": "reference", "strategy": "sequence", "prefix": "C-", "pad": pad}}}});
+        let mut args = json!({"name": {"value": "Acme"}});
+        let refusal = apply_identity(&presentation, &aggregate, &mut args, 1).expect_err("a pad this wide is refused");
+        envelope_is_structured(&refusal);
+        assert_eq!(args, json!({"name": {"value": "Acme"}}), "pad {pad}: nothing was minted");
+    }
+    let presentation = json!({"collections": {"Client": {"identity": {"field": "reference", "strategy": "sequence", "prefix": "C-", "pad": 64}}}});
+    let mut args = json!({});
+    apply_identity(&presentation, &aggregate, &mut args, 0).expect("the widest allowed pad still mints");
+    assert_eq!(args["reference"]["value"].as_str().unwrap().len(), 2 + 64);
+}
+
+#[test]
+fn preconditions_survive_any_config_and_instances_shape() {
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed ^ 0xC0);
+            for _ in 0..50 {
+                let domain = json!({"name": random_text(&mut rng), "aggregates": [client_aggregate(), {"name": "Member", "lifecycle": random_value(&mut rng, 2)}]});
+                let aggregate = client_aggregate();
+                let rule = if rng.chance(3) {
+                    random_value(&mut rng, 0)
+                } else {
+                    json!({"field": *rng.pick(&["owner", "name", "status", "missing"]), "state": random_value(&mut rng, 2), "message": random_value(&mut rng, 2)})
+                };
+                let args = if rng.chance(3) { random_value(&mut rng, 0) } else { json!({"owner": random_value(&mut rng, 2)}) };
+                let instances = if rng.chance(3) { random_value(&mut rng, 0) } else { json!({format!("{}::Member#m1", domain_name(&domain)): random_value(&mut rng, 2)}) };
+                if let Err(refusal) = check_precondition(&domain, &aggregate, &rule, &args, &instances) {
+                    envelope_is_structured(&refusal);
+                }
+            }
+        });
+    }
+}
+
+#[test]
+fn sorting_records_of_mixed_types_never_panics_on_an_inconsistent_order() {
+    // `sort_by` may panic when its comparator is not a total order, so a column holding numbers,
+    // empty strings, strings, nulls and objects together must still order consistently.
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed ^ 0x50);
+            for _ in 0..10 {
+                let mut records: Vec<(String, Value)> = (0..20 + rng.below(200))
+                    .map(|i| {
+                        let cell = match rng.below(8) {
+                            0 => json!(rng.below(5)),
+                            1 => json!(rng.below(5) as f64 / 2.0),
+                            2 => json!(""),
+                            3 => json!(*rng.pick(&["a", "b", "B", "10", "9", "é", "🍕"])),
+                            4 => Value::Null,
+                            5 => json!({"cents": rng.below(50)}),
+                            6 => json!({"value": random_text(&mut rng)}),
+                            _ => random_value(&mut rng, 2),
+                        };
+                        (format!("id{}", i % 17), json!({"col": cell}))
+                    })
+                    .collect();
+                for descending in [false, true] {
+                    let spec = Some(SortSpec { field: "col".to_string(), descending });
+                    sort_records(&mut records, &spec);
+                    sort_records(&mut records, &None);
+                }
+            }
+        });
+    }
+}
+
+#[test]
+fn query_arguments_and_sort_params_survive_hostile_input() {
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed ^ 0x9A);
+            let aggregate = client_aggregate();
+            let domain = json!({"name": "Crm", "aggregates": [aggregate.clone()]});
+            for _ in 0..30 {
+                let named = if rng.chance(3) {
+                    random_value(&mut rng, 0)
+                } else {
+                    json!({"attributes": [
+                        {"name": *rng.pick(&["name", "owner", "reference", "x"]), "type": *rng.pick(&["ClientName", "String", "Reference<Member>", "Nope", "Integer"]), "optional": rng.chance(2)},
+                        random_value(&mut rng, 2)
+                    ]})
+                };
+                let mut params: HashMap<String, String> = HashMap::new();
+                for _ in 0..rng.below(5) {
+                    params.insert(random_text(&mut rng), random_text(&mut rng));
+                }
+                params.insert("name".to_string(), random_text(&mut rng));
+                let _ = query_args_from_params(&aggregate, &named, &params);
+
+                let sort: HashMap<String, String> = [("sort", random_text(&mut rng)), ("direction", random_text(&mut rng))].into_iter().map(|(k, v)| (k.to_string(), v)).collect();
+                let config = random_value(&mut rng, 0);
+                let _ = resolve_sort(&domain, &config, "Client", &aggregate, &sort);
+                let _ = resolve_sort(&domain, &json!({}), "Client", &aggregate, &HashMap::from([("sort".to_string(), "__state__".to_string())]));
+            }
+        });
+    }
+}
+
+#[test]
+fn identity_sources_and_scalars_render_any_json_value() {
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed ^ 0x5C);
+            for _ in 0..50 {
+                let args = json!({"name": random_value(&mut rng, 0)});
+                let _ = dig_source(&args, "name");
+                let _ = dig_source(&random_value(&mut rng, 0), &random_text(&mut rng));
+                let _ = scalar_to_string(&random_value(&mut rng, 0));
+            }
+        });
+    }
+}

data/rust/host/src/boundary_fuzz/auth.rs

@@ -0,0 +1,119 @@
+//! Seeded fuzz of the signed-cookie and token readers: whatever text arrives in a `Cookie`
+//! header or a query string, it either verifies as exactly what this host signed or yields
+//! nothing. A forged, truncated or tampered token must never read as a session, and none of it
+//! may panic.
+
+use super::*;
+use crate::fuzz_support::*;
+
+const SECRET: &str = "fuzz-secret";
+
+fn session(rng: &mut Rng) -> Session {
+    Session { identity_id: random_text(rng), email: random_text(rng), name: random_text(rng), role: if rng.chance(2) { Some(random_text(rng)) } else { None } }
+}
+
+#[test]
+fn a_signed_cookie_reads_back_as_the_session_it_was_made_from() {
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed);
+            for _ in 0..30 {
+                let original = session(&mut rng);
+                let cookie = session_cookie(SECRET, &original);
+                let read = parse_session_cookie(SECRET, &cookie).unwrap_or_else(|| panic!("seed {seed}: own cookie for {:?} refused", original.email));
+                assert_eq!((read.identity_id, read.email, read.name, read.role), (original.identity_id, original.email, original.name, original.role), "seed {seed}");
+                assert!(parse_session_cookie("another-secret", &cookie).is_none(), "seed {seed}: a different secret verified the cookie");
+            }
+        });
+    }
+}
+
+#[test]
+fn no_arbitrary_or_tampered_token_ever_verifies() {
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed ^ 0x70C);
+            let genuine_cookie = session_cookie(SECRET, &session(&mut rng));
+            let genuine_account = account_token(SECRET, &random_text(&mut rng), 60);
+            let genuine_purpose = purpose_token(SECRET, "reset", json!({"email": random_text(&mut rng)}), 60);
+            for _ in 0..40 {
+                let junk = match rng.below(4) {
+                    0 => random_text(&mut rng),
+                    1 => format!("{}.{}", random_text(&mut rng), random_text(&mut rng)),
+                    2 => ".".repeat(rng.below(4)),
+                    _ => String::from_utf8_lossy(&random_bytes(&mut rng)).into_owned(),
+                };
+                assert!(parse_session_cookie(SECRET, &junk).is_none(), "seed {seed}: {junk:?} read as a session");
+                assert!(verify_account_token(SECRET, &junk).is_none(), "seed {seed}: {junk:?} read as an account token");
+                assert!(verify_purpose_token(SECRET, "reset", &junk).is_none(), "seed {seed}: {junk:?} read as a purpose token");
+
+                for (genuine, verifies) in [
+                    (&genuine_cookie, (|t: &str| parse_session_cookie(SECRET, t).is_some()) as fn(&str) -> bool),
+                    (&genuine_account, |t: &str| verify_account_token(SECRET, t).is_some()),
+                    (&genuine_purpose, |t: &str| verify_purpose_token(SECRET, "reset", t).is_some()),
+                ] {
+                    assert!(verifies(genuine), "seed {seed}: the untampered token must verify");
+                    let tampered = mutate_text(&mut rng, genuine);
+                    assert!(tampered == *genuine || !verifies(&tampered), "seed {seed}: tampered token {tampered:?} verified");
+                }
+            }
+        });
+    }
+}
+
+#[test]
+fn a_token_for_one_purpose_never_verifies_for_another_or_as_an_account_token() {
+    let token = purpose_token(SECRET, "reset", json!({"email": "a@example.com"}), 60);
+    assert!(verify_purpose_token(SECRET, "reset", &token).is_some());
+    for other in ["", "RESET", "reset ", "reset:", "invite", "reset:fuzz-secret"] {
+        assert!(verify_purpose_token(SECRET, other, &token).is_none(), "purpose {other:?}");
+    }
+    assert!(verify_account_token(SECRET, &token).is_none());
+    assert!(parse_session_cookie(SECRET, &token).is_none());
+}
+
+#[test]
+fn an_expired_or_unexpiring_signed_payload_is_not_a_session() {
+    let sign_payload = |payload: Value| {
+        let encoded = base64_encode(payload.to_string().as_bytes());
+        format!("{encoded}.{}", sign(SECRET, &encoded))
+    };
+    let person = json!({"identity_id": "i", "email": "e", "name": "n"});
+    for exp in [json!(0), json!(1), json!(-1), json!(1.5), json!("9999999999"), json!(null), json!(u64::MAX)] {
+        let mut payload = person.clone();
+        payload["exp"] = exp.clone();
+        let verdict = parse_session_cookie(SECRET, &sign_payload(payload)).is_some();
+        assert_eq!(verdict, exp == json!(u64::MAX), "exp {exp}");
+    }
+    assert!(parse_session_cookie(SECRET, &sign_payload(person)).is_none(), "no exp is no session");
+    for payload in [json!([]), json!(1), json!("s"), json!(null), json!({"exp": u64::MAX}), json!({"exp": u64::MAX, "identity_id": 1, "email": "e", "name": "n"})] {
+        assert!(parse_session_cookie(SECRET, &sign_payload(payload.clone())).is_none(), "{payload}");
+        assert!(verify_account_token(SECRET, &sign_payload(payload.clone())).is_none() || payload.get("email").is_some(), "{payload}");
+    }
+}
+
+#[test]
+fn signature_comparison_checks_every_byte_and_the_length() {
+    assert!(constant_time_eq(b"", b""));
+    assert!(constant_time_eq(b"abc", b"abc"));
+    assert!(!constant_time_eq(b"abc", b"abd"));
+    assert!(!constant_time_eq(b"abc", b"xbc"));
+    assert!(!constant_time_eq(b"abc", b"ab"));
+    assert!(!constant_time_eq(b"ab", b"abc"));
+}
+
+#[test]
+fn base64_decoding_and_cookie_names_take_any_text() {
+    for seed in 0..seeds() {
+        guarded(&format!("seed {seed}"), move || {
+            let mut rng = Rng::new(seed ^ 0xBA5E);
+            for _ in 0..100 {
+                let text = random_text(&mut rng);
+                let _ = base64_decode(&text);
+                let _ = resolve_account_cookie(Some(&text));
+                let bytes = random_bytes(&mut rng);
+                assert_eq!(base64_decode(&base64_encode(&bytes)), bytes, "seed {seed}");
+            }
+        });
+    }
+}