refactor(stack-encrypt): read a record plan from its frame with serde, not FfiValue

record::plan and plan_with took an FfiValue tree and walked it by hand:
the object, each field spec's keys, the outputs list, each index's wire
form and a match index's options. They now take the plan's frame bytes
and read them with serde (vitaminc_aead_frame::serde). One small visitor
reads the top-level map, to tell the reserved "context_field" key from a
field's name; everything below it is derived:
- a field spec is a deny_unknown_fields struct, with exactly one of
  "outputs" and "target" checked in TryFrom, and a present key that is
  null refused through a three-line `present` helper;
- an output is an externally tagged enum, so "match", {"match": null} and
  {"match": {...}} are one variant, Match(Option<MatchWire>);
- match options default field by field and are checked against the
  scheme's bounds in TryFrom;
- a "type" is a try_from newtype over ValueKind's names;
- a field's context is the context visitor's.

Every Reason a plan was refused with is kept: plan_refusal reads the field
from the error's path and the reason from where in the field it happened,
or from the reason a field's own rule gave. Two changes, both from the
frame: a key, field or match option given twice is refused by the frame
before the plan is read, as NotAnObject naming no field (RepeatedKey and
DuplicateField before); and a missing index payload and a null one mean
the same, so {"eq": null} is a bare "eq".

IndexSpec::from_frame replaces IndexSpec::from_value, and
Output::from_value is gone. The Go guest checks a plan is a frame, then
hands its bytes over. Unit tests build plans from FfiValue through the
shared test helper, and integration tests write them as JSON serialised
straight to frame bytes; the fuzz target sends each plan as its frame.

Refs #1252.

Author: coderdan

.cargo/mutants.toml

@@ -96,6 +96,13 @@ exclude_re = [
   # `true` there refuses the same values with the same error. The guard stays
   # so the model says what it holds without leaning on the writer behind it.
   'stack-encrypt/src/dynamic/value_frame\.rs:\d+:\d+: replace match guard logical\.admits\(&value\) with true in model$',
+  # A serde visitor's `expecting` writes only the "expected ..." half of a
+  # serde error's message, and no caller of these three reads that message:
+  # a context, statistics and a plan's root are each refused with one fixed
+  # `Reason` (`ContextKind`, `NotStats`, `NotAnObject`), and the plan's
+  # field-level reasons are read from the error's path, so writing nothing
+  # refuses the same input with the same error.
+  'stack-encrypt/src/dynamic/(context|query|record)\.rs:\d+:\d+: replace <impl (Visitor<\x27de> for ContextVisitor|serde::Deserialize<\x27de> for Confidence>::deserialize::<impl serde::de::Visitor<\x27_> for V|Deserialize<\x27de> for PlanWire>::deserialize::<impl Visitor<\x27de> for V)>::expecting -> fmt::Result with Ok\(Default::default\(\)\)$',
 ]
 
 # Headroom over the measured baseline before a slow-but-correct mutant is

languages/golang/encrypt/guest/Cargo.toml

@@ -47,7 +47,7 @@ eql = ["dep:eql-bindings"]
 # HTTP comes from the host (see `wasm:wasi-check` in the suite root).
 stack-auth = { path = "../../../../packages/stack-auth", default-features = false }
 # `dynamic`: the runtime value model this guest speaks — contexts, index
-# terms and record plans over `FfiValue`, shared with every other binding.
+# terms and record plans read from frames, shared with every other binding.
 stack-encrypt = { path = "../../../../packages/stack-encrypt", default-features = false, features = ["dynamic"] }
 # The guest ABI every guest under bindings/go shares: the allocator and
 # buffer registry (and with them the `se_alloc`/`se_dealloc` exports), the

languages/golang/encrypt/guest/src/ops.rs

@@ -42,8 +42,8 @@
 //! values to verify are read as [`ValueFrame`]s: the frame is checked against
 //! the engine's value model, and the engine walks it, splitting a source into
 //! one frame per field as it goes. A record opens into one frame, which is
-//! the output. Control data (a plan, an options object, query statistics)
-//! carries no secret and is decoded into an [`FfiValue`].
+//! the output. Control data (a plan, a context, an options object, query
+//! statistics) carries no secret and is read from its frame with serde.
 
 use stack_encrypt::dynamic::{self, FfiValue, Scope, ValueFrame};
 use stack_encrypt::sem::MatchOptions;
@@ -357,11 +357,13 @@ fn parse_query<'f>(
     Ok((plan, field, operator))
 }
 
-/// A codec-encoded plan, parsed against this build's resolver: a target
-/// name this build cannot run is refused here, the same way at every
-/// export that takes a plan.
+/// A plan's frame, parsed against this build's resolver: a target name this
+/// build cannot run is refused here, the same way at every export that
+/// takes a plan. Bytes that are not a frame are refused as every other
+/// input's are, before the plan's own grammar.
 fn parse_plan(plan: &[u8]) -> Result<dynamic::record::Plan, u32> {
-    dynamic::record::plan_with(decode_value(plan)?, &resolver()).map_err(|e| fail_dynamic(&e))
+    let _ = parse_frame(plan)?;
+    dynamic::record::plan_with(plan, &resolver()).map_err(|e| fail_dynamic(&e))
 }
 
 // =============================================================================
@@ -518,11 +520,6 @@ pub mod validate {
 // Codec glue
 // =============================================================================
 
-/// Control data from a frame: a plan, an options object, statistics.
-fn decode_value(bytes: &[u8]) -> Result<FfiValue, u32> {
-    FfiValue::from_frame(bytes).map_err(|_| not_a_frame())
-}
-
 /// Plaintext from a frame: checked against the engine's value model and
 /// held as the frame, in a buffer wiped when it drops. The same frames are
 /// refused as control data's, so a malformed input fails the same way on
@@ -832,7 +829,7 @@ mod tests {
     #[test]
     fn targets_lists_what_this_build_holds_in_the_wire_shape() {
         let out = targets().expect("encodes");
-        let FfiValue::Object(entries) = decode_value(&out).expect("decodes") else {
+        let FfiValue::Object(entries) = FfiValue::from_frame(&out).expect("decodes") else {
             panic!("an object");
         };
         assert_eq!(entries.len(), 1);
@@ -955,7 +952,7 @@ mod tests {
         validate::record_tree(&sealed, &plan, None).expect("the tree fits");
         let opened =
             block_on(decrypt_record(Scope::Client(&cipher), &sealed, &plan, None)).expect("opens");
-        let FfiValue::Object(values) = decode_value(&opened).expect("a value") else {
+        let FfiValue::Object(values) = FfiValue::from_frame(&opened).expect("a value") else {
             panic!("an object")
         };
         assert!(
@@ -968,7 +965,7 @@ mod tests {
         let probe = encoded(text("alice@example.com"));
         validate::query_term(&probe, &plan, b"email", b"eq").expect("a target field answers eq");
         let term = block_on(query_term(&keyset, &probe, &plan, b"email", b"eq")).expect("derives");
-        let FfiValue::Object(term) = decode_value(&term).expect("a value") else {
+        let FfiValue::Object(term) = FfiValue::from_frame(&term).expect("a value") else {
             panic!("a query term is an object")
         };
         assert!(

packages/stack-encrypt/CHANGELOG.md

@@ -272,6 +272,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     are contexts: an 8- or 16-bit integer, which was widened to 32 bits
     before, and a 128-bit one are `Reason::ContextKind`, as are bytes that
     are not one frame.
+  - `record::plan` and `record::plan_with` take the plan's frame bytes.
+    `IndexSpec::from_frame` replaces `IndexSpec::from_value`, and
+    `Output::from_value` is gone. Each `Reason` a plan was refused with is
+    unchanged, with two exceptions: a key, a field or a match option given
+    twice is refused by the frame before the plan is read, as
+    `Reason::NotAnObject` naming no field (it was `RepeatedKey` or
+    `DuplicateField`), and so are bytes that are not one frame. An index's
+    payload may be missing or null alike: `{"match": null}` is a bare
+    `"match"`, and `{"eq": null}` a bare `"eq"`.
   - `Stats::from_frame` replaces `Stats::from_value`.
 
 - **A match value with no tokens is stored as the empty filter, so

packages/stack-encrypt/fuzz/fuzz_targets/check_record.rs

@@ -401,7 +401,12 @@ fuzz_target!(|case: Case| {
     let Case { plan: spec, record } = case;
     // The plan parser is fuzzed for panics only: its rules are a separate
     // model, and a plan that does not parse has no record to check.
-    let Ok(plan) = plan_with(spec.into_value(), &Fixed) else {
+    // The plan crosses as a binding sends it, as frame bytes; a spec the
+    // frame cannot carry is no plan.
+    let Ok(frame) = spec.into_value().to_frame() else {
+        return;
+    };
+    let Ok(plan) = plan_with(frame.risky_ref(), &Fixed) else {
         if trace {
             eprintln!("verdict: plan refused");
         }

packages/stack-encrypt/src/dynamic/mod.rs

@@ -21,12 +21,13 @@
 //! indexed by walking its frame into the encrypting sink and the term
 //! derivers; and a record opens straight into a frame (vitaminc ADR 0001: a
 //! value describes itself once, and sinks consume it). A binding's control
-//! data (a plan, a context, options, a configuration, whose credentials are
-//! secret) is an [`FfiValue`] tree, with its text and bytes wiped.
+//! data (a plan, a context, query statistics) is read from its frame by
+//! serde (`vitaminc_aead_frame::serde`) into a typed message, with no tree
+//! built.
 //!
 //! # What is here
 //!
-//! * [`context`](context()) — an [`FfiValue`] read as an encryption context.
+//! * [`context`](context()) — a frame read as an encryption context.
 //! * [`ValueFrame`] — the engine's plaintext for a value whose type is known
 //!   only at run time, and the value model it holds.
 //! * [`term`](term()) — one index term for a value, derived at the one
@@ -159,8 +160,9 @@ impl<K> fmt::Debug for Scope<'_, K> {
     }
 }
 
-/// The UTF-8 inside a string leaf. Valid by `Utf8String`'s construction
-/// invariant; checked rather than assumed because this is boundary code.
+/// The UTF-8 inside a string leaf, for tests. Valid by `Utf8String`'s
+/// construction invariant; checked rather than assumed.
+#[cfg(test)]
 fn utf8(s: &Utf8String) -> Option<&str> {
     std::str::from_utf8(s.risky_ref()).ok()
 }

packages/stack-encrypt/src/dynamic/query.rs

@@ -473,24 +473,18 @@ fn answers(
 /// with [`operator_to_value`].
 ///
 /// ```
-/// use stack_encrypt::dynamic::{field_operators, record, FfiValue, NoTargets, OpSpec};
+/// use stack_encrypt::dynamic::{field_operators, record, NoTargets, OpSpec};
 /// use stack_encrypt::target::IndexSpec;
 ///
-/// let text = |s: &str| FfiValue::String(s.into());
-/// let plan = record::plan(FfiValue::Object(vec![(
-///     "age".into(),
-///     FfiValue::Object(vec![
-///         ("context".into(), FfiValue::Array(vec![text("users"), text("age")])),
-///         ("outputs".into(), FfiValue::Array(vec![text("c"), text("eq"), text("ore")])),
-///         ("type".into(), text("uint32")),
-///     ]),
-/// )]))?;
+/// let plan = record::plan(&vitaminc_aead_frame::serde::to_vec(&serde_json::json!({
+///     "age": { "context": ["users", "age"], "outputs": ["c", "eq", "ore"], "type": "uint32" },
+/// }))?)?;
 ///
 /// let operators = field_operators(&plan, "age", &NoTargets)?;
 /// assert_eq!(operators[0], (OpSpec::Eq, IndexSpec::Equality));
 /// assert_eq!(operators[1], (OpSpec::Lt, IndexSpec::Ore));
 /// assert_eq!(operators.len(), 6, "eq, the four comparisons and between");
-/// # Ok::<(), stack_encrypt::dynamic::Error>(())
+/// # Ok::<(), Box<dyn std::error::Error>>(())
 /// ```
 ///
 /// # Errors
@@ -699,15 +693,9 @@ pub fn check_query(
 /// # tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap().block_on(async {
 /// let cipher = StackCipher::builder().kms(FakeDataKeySource::new()).init().await?;
 /// let keyset = cipher.default_keyset();
-/// let text = |s: &str| FfiValue::String(s.into());
-/// let plan = record::plan(FfiValue::Object(vec![(
-///     "age".into(),
-///     FfiValue::Object(vec![
-///         ("context".into(), FfiValue::Array(vec![text("users"), text("age")])),
-///         ("outputs".into(), FfiValue::Array(vec![text("c"), text("ore")])),
-///         ("type".into(), text("uint32")),
-///     ]),
-/// )]))?;
+/// let plan = record::plan(&vitaminc_aead_frame::serde::to_vec(&serde_json::json!({
+///     "age": { "context": ["users", "age"], "outputs": ["c", "ore"], "type": "uint32" },
+/// }))?)?;
 ///
 /// let term = query_term(&keyset, &plan, "age", OpSpec::Lt, FfiValue::UInt32(40), &NoTargets)?.await?;
 ///
@@ -1020,6 +1008,7 @@ pub fn limit_to_value(limit: Limit) -> FfiValue {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::dynamic::test_frame::frame_of;
 
     /// Statistics as a binding sends them.
     fn stats_frame(value: &FfiValue) -> Result<Stats, Error> {
@@ -1071,14 +1060,14 @@ mod tests {
             "match".into(),
             FfiValue::Object(vec![("downcase".into(), FfiValue::Bool(false))]),
         )]);
-        record::plan(FfiValue::Object(vec![
+        record::plan(&frame_of(&FfiValue::Object(vec![
             field("email", "string", vec![text("c"), text("eq")]),
             field("name", "string", vec![text("c"), text("match")]),
             field("age", "uint32", vec![text("c"), text("ope"), text("ore")]),
             field("score", "int64", vec![text("ope")]),
             field("nickname", "string", vec![text("c"), text("ore")]),
             field("handle", "string", vec![text("c"), case_sensitive]),
-        ]))
+        ])))
         .expect("the plan parses")
     }
 
@@ -1471,11 +1460,11 @@ mod tests {
                 ]),
             )
         };
-        let plan = record::plan(FfiValue::Object(vec![
+        let plan = record::plan(&frame_of(&FfiValue::Object(vec![
             ("context_field".into(), text("tenant")),
             one("tenant", "string", "passthrough"),
             one("email", "string", "eq"),
-        ]))
+        ])))
         .unwrap();
         let error = query_term(&keyset, &plan, "email", OpSpec::Eq, text("a"), &NoTargets)
             .map(drop)
@@ -1860,13 +1849,13 @@ mod tests {
         use vitaminc_aead::plaintext::{Int, Logical, Physical, Raw, TimeUnit};
         let cipher = cipher().await;
         let keyset = cipher.default_keyset();
-        let plan = record::plan(FfiValue::Object(vec![
+        let plan = record::plan(&frame_of(&FfiValue::Object(vec![
             field("tiny", "int8", vec![text("c"), text("ore")]),
             field("huge", "int128", vec![text("c"), text("ope")]),
             field("day", "date", vec![text("c"), text("eq")]),
             field("at", "timestamp", vec![text("c"), text("eq")]),
             field("price", "decimal", vec![text("c"), text("eq")]),
-        ]))
+        ])))
         .expect("the plan parses");
         let frame = |ty: Option<Logical>, value: Physical<'_>| {
             ValueFrame::of(Raw(ty, value)).expect("a value")
@@ -2368,7 +2357,7 @@ mod tests {
 
     fn match_type_plan() -> Plan {
         record::plan_with(
-            FfiValue::Object(vec![(
+            &frame_of(&FfiValue::Object(vec![(
                 "name".into(),
                 FfiValue::Object(vec![
                     (
@@ -2377,7 +2366,7 @@ mod tests {
                     ),
                     ("target".into(), text("Some")),
                 ]),
-            )]),
+            )])),
             &MatchType,
         )
         .unwrap()
@@ -2547,7 +2536,7 @@ mod tests {
         let cipher = cipher().await;
         let keyset = cipher.default_keyset();
         let plan = record::plan_with(
-            FfiValue::Object(vec![(
+            &frame_of(&FfiValue::Object(vec![(
                 "email".into(),
                 FfiValue::Object(vec![
                     (
@@ -2556,7 +2545,7 @@ mod tests {
                     ),
                     ("target".into(), text("Some")),
                 ]),
-            )]),
+            )])),
             &OneType,
         )
         .unwrap();